docs: add RStack RFC ADR process#85
Conversation
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (3)
📝 WalkthroughWalkthroughThis PR establishes an RFC/ADR governance framework for RStack by adding a registry, template, and six initial RFC proposals; implementing CI-backed validation for RFC structure; integrating RFC assets into the package; and publishing research-backed design documentation with Mintlify navigation. ChangesRFC/ADR Governance Framework
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (4)
rfcs/README.md (1)
32-42: ⚡ Quick winClarify that kebab-case slugs must be lowercase.
The filename format documentation shows examples in lowercase (
rstack-spec-v1alpha1,decision-queue-and-readiness-gate), but doesn't explicitly state that the slug portion must be lowercase. The validation test attests/validate-rfcs.test.jsline 28 enforces this with the regex pattern[a-z0-9]+(?:-[a-z0-9]+)*.📝 Proposed clarification
RFC filenames must use this format: ```text -RFC-000N-short-kebab-title.md +RFC-000N-lowercase-kebab-slug.mdExamples:
</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@rfcs/README.mdaround lines 32 - 42, Update the RFC filename guidance to
explicitly state that the kebab-case slug must be lowercase and adjust the
example filename accordingly (e.g., change "RFC-000N-short-kebab-title.md" to
"RFC-000N-lowercase-kebab-slug.md"); reference the validation regex
[a-z0-9]+(?:-[a-z0-9]+)* to make clear the slug only allows lowercase letters
and digits separated by hyphens so maintainers and contributors follow the same
rule enforced by the tests.</details> <!-- cr-comment:v1:c27e1e8361e78a0aa12a17ae --> </blockquote></details> <details> <summary>docs/mintlify/reference/research-backed-design.mdx (1)</summary><blockquote> `16-16`: **Clarify the NIST AI RMF naming; keep the other references in scope for a quick check.** - NIST’s “AI RMF” is officially the “Artificial Intelligence Risk Management Framework,” and “AI RMF” is the correct abbreviation. - Still consider confirming the formal titles/abbreviations of the other cited items (e.g., NIST SSDF, ISO/IEC 42001, OWASP, SLSA, DSSE, Sigstore) so the documentation matches current official wording. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/mintlify/reference/research-backed-design.mdxat line 16, Update the
"Research first" reference line so that "NIST AI RMF" is written with its full
formal name followed by the abbreviation (e.g., "Artificial Intelligence Risk
Management Framework (AI RMF)") while keeping the other references in scope;
also verify and standardize the formal titles/abbreviations for the other cited
items (NIST SSDF, ISO/IEC 42001, OWASP LLM Top 10, SLSA, DSSE, Sigstore, Augment
Code's AI-SDLC reference architecture, and theai-sdlc-framework/ai-sdlc
string) to match their official naming/abbreviations and update the list
accordingly in the "Research first" bullet.</details> <!-- cr-comment:v1:996e6327d086092cfb97c759 --> </blockquote></details> <details> <summary>docs/mintlify/reference/rfc-process.mdx (2)</summary><blockquote> `22-31`: _⚡ Quick win_ **Hardcoded GitHub URLs reduce portability.** The RFC registry table uses absolute GitHub URLs to `richard-devbot/SDLC-rstack`. If the repository is forked, renamed, or moved to a different organization, all six links will break. Consider using relative paths or repository-agnostic references. <details> <summary>♻️ Suggested relative-path approach</summary> Mintlify typically supports relative references for content within the same repository. Consider replacing the full GitHub URLs with relative links to the RFC files: ```diff -| [RFC-0001](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0001-rstack-spec-v1alpha1.md) | Draft | [`#71`](https://github.com/richard-devbot/SDLC-rstack/issues/71) | RStack Spec v1alpha1. | +| [RFC-0001](/rfcs/RFC-0001-rstack-spec-v1alpha1.md) | Draft | [`#71`](https://github.com/richard-devbot/SDLC-rstack/issues/71) | RStack Spec v1alpha1. |Apply similar changes to RFC-0002 through RFC-0006.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/mintlify/reference/rfc-process.mdx` around lines 22 - 31, The table rows for RFC-0001 through RFC-0006 use hardcoded GitHub URLs; replace each absolute RFC file link (e.g., the [RFC-0001] link target) with a relative repository path (e.g., relative link to rfcs/RFC-0001-...md) and change issue links (e.g., [`#71`], [`#70`], etc.) to repository-agnostic references or relative issue references supported by Mintlify so links remain valid if the repo is forked/renamed; update all six table entries (RFC-0001..RFC-0006) accordingly and verify the rendered links still point to the correct RFC files and issues.
40-55: 💤 Low valueMinor command inconsistency with RFC README.
Line 54 instructs users to run
npm test -- tests/validate-rfcs.test.js, but the RFC README (per context snippet from rfcs/README.md:72) instructs maintainers to runnpm test. While both commands work, the README's simpler form runs all tests including RFC validation, which may be preferable for consistency.♻️ Align with README command
-npm test -- tests/validate-rfcs.test.js +npm testOr clarify that the filtered command runs only RFC validation if that's the intended workflow.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/mintlify/reference/rfc-process.mdx` around lines 40 - 55, The command in docs/mintlify/reference/rfc-process.mdx is inconsistent with the rfcs/README.md guidance; update the example to use the README's simpler "npm test" or explicitly state the difference: replace "npm test -- tests/validate-rfcs.test.js" with "npm test" for consistency, or keep the current filtered command but add a clarifying sentence that "npm test -- tests/validate-rfcs.test.js" runs only the RFC validator (tests/validate-rfcs.test.js) while "npm test" runs the full test suite, referencing the RFC validator test name tests/validate-rfcs.test.js and the rfcs/README.md guidance.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/mintlify/reference/research-backed-design.mdx`:
- Line 16: Update the "Research first" reference line so that "NIST AI RMF" is
written with its full formal name followed by the abbreviation (e.g.,
"Artificial Intelligence Risk Management Framework (AI RMF)") while keeping the
other references in scope; also verify and standardize the formal
titles/abbreviations for the other cited items (NIST SSDF, ISO/IEC 42001, OWASP
LLM Top 10, SLSA, DSSE, Sigstore, Augment Code's AI-SDLC reference architecture,
and the `ai-sdlc-framework/ai-sdlc` string) to match their official
naming/abbreviations and update the list accordingly in the "Research first"
bullet.
In `@docs/mintlify/reference/rfc-process.mdx`:
- Around line 22-31: The table rows for RFC-0001 through RFC-0006 use hardcoded
GitHub URLs; replace each absolute RFC file link (e.g., the [RFC-0001] link
target) with a relative repository path (e.g., relative link to
rfcs/RFC-0001-...md) and change issue links (e.g., [`#71`], [`#70`], etc.) to
repository-agnostic references or relative issue references supported by
Mintlify so links remain valid if the repo is forked/renamed; update all six
table entries (RFC-0001..RFC-0006) accordingly and verify the rendered links
still point to the correct RFC files and issues.
- Around line 40-55: The command in docs/mintlify/reference/rfc-process.mdx is
inconsistent with the rfcs/README.md guidance; update the example to use the
README's simpler "npm test" or explicitly state the difference: replace "npm
test -- tests/validate-rfcs.test.js" with "npm test" for consistency, or keep
the current filtered command but add a clarifying sentence that "npm test --
tests/validate-rfcs.test.js" runs only the RFC validator
(tests/validate-rfcs.test.js) while "npm test" runs the full test suite,
referencing the RFC validator test name tests/validate-rfcs.test.js and the
rfcs/README.md guidance.
In `@rfcs/README.md`:
- Around line 32-42: Update the RFC filename guidance to explicitly state that
the kebab-case slug must be lowercase and adjust the example filename
accordingly (e.g., change "RFC-000N-short-kebab-title.md" to
"RFC-000N-lowercase-kebab-slug.md"); reference the validation regex
[a-z0-9]+(?:-[a-z0-9]+)* to make clear the slug only allows lowercase letters
and digits separated by hyphens so maintainers and contributors follow the same
rule enforced by the tests.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: a08a116f-a76b-4b07-b183-4c0b5584a02c
📒 Files selected for processing (16)
README.mddocs/mintlify/docs.jsondocs/mintlify/mint.jsondocs/mintlify/reference/research-backed-design.mdxdocs/mintlify/reference/rfc-process.mdxpackage.jsonrfcs/README.mdrfcs/RFC-0001-rstack-spec-v1alpha1.mdrfcs/RFC-0002-decision-queue-and-readiness-gate.mdrfcs/RFC-0003-cross-harness-validation.mdrfcs/RFC-0004-attestation-envelope.mdrfcs/RFC-0005-traceability-drift-detection.mdrfcs/RFC-0006-untrusted-pr-gate.mdrfcs/TEMPLATE.mdtests/validate-package-assets.test.jstests/validate-rfcs.test.js
# Conflicts: # tests/validate-package-assets.test.js
2 participants
Summary
rfcs/README.md,rfcs/TEMPLATE.md, and initial RFC stubs for Roadmap: Add RStack Decision Queue and Definition-of-Ready readiness gate #70-Roadmap: Add untrusted contributor PR gate for protected RStack paths #75 / Roadmap: Publish RStack Spec v1alpha1 with JSON schemas and conformance examples #71.rfcs/in package files and updates package asset tests.Deep-dive findings
RFCs added
RFC-0001-rstack-spec-v1alpha1.md→ Roadmap: Publish RStack Spec v1alpha1 with JSON schemas and conformance examples #71RFC-0002-decision-queue-and-readiness-gate.md→ Roadmap: Add RStack Decision Queue and Definition-of-Ready readiness gate #70RFC-0003-cross-harness-validation.md→ Roadmap: Enforce cross-harness builder/validator review independence #72RFC-0004-attestation-envelope.md→ Roadmap: Add RStack attestation envelopes for builder, validator, and release evidence #73RFC-0005-traceability-drift-detection.md→ Roadmap: Add traceability drift detection from requirements to tasks, evidence, and docs #74RFC-0006-untrusted-pr-gate.md→ Roadmap: Add untrusted contributor PR gate for protected RStack paths #75Validation
npx tsx --test tests/validate-rfcs.test.js— 3 pass, 0 failnpm test— 185 pass, 0 failnpm run lint— passnpm run validate— all 196 agents passed validationgit diff --check— passnpm pack --dry-run --json— package includesrfcs/README.md, six RFCs, andrfcs/TEMPLATE.mdCloses #76
Summary by CodeRabbit