From 81fbafb18d0dc7bda9199351219486d575042417 Mon Sep 17 00:00:00 2001 From: Richardson Gunde Date: Wed, 10 Jun 2026 09:49:57 +0530 Subject: [PATCH 1/2] docs: add RFC ADR process --- README.md | 4 +- docs/mintlify/docs.json | 8 +- docs/mintlify/mint.json | 4 +- .../reference/research-backed-design.mdx | 44 ++++++++++ docs/mintlify/reference/rfc-process.mdx | 59 ++++++++++++++ package.json | 3 +- rfcs/README.md | 80 +++++++++++++++++++ rfcs/RFC-0001-rstack-spec-v1alpha1.md | 43 ++++++++++ ...-0002-decision-queue-and-readiness-gate.md | 42 ++++++++++ rfcs/RFC-0003-cross-harness-validation.md | 41 ++++++++++ rfcs/RFC-0004-attestation-envelope.md | 41 ++++++++++ rfcs/RFC-0005-traceability-drift-detection.md | 41 ++++++++++ rfcs/RFC-0006-untrusted-pr-gate.md | 41 ++++++++++ rfcs/TEMPLATE.md | 24 ++++++ tests/validate-package-assets.test.js | 4 +- tests/validate-rfcs.test.js | 71 ++++++++++++++++ 16 files changed, 543 insertions(+), 7 deletions(-) create mode 100644 docs/mintlify/reference/research-backed-design.mdx create mode 100644 docs/mintlify/reference/rfc-process.mdx create mode 100644 rfcs/README.md create mode 100644 rfcs/RFC-0001-rstack-spec-v1alpha1.md create mode 100644 rfcs/RFC-0002-decision-queue-and-readiness-gate.md create mode 100644 rfcs/RFC-0003-cross-harness-validation.md create mode 100644 rfcs/RFC-0004-attestation-envelope.md create mode 100644 rfcs/RFC-0005-traceability-drift-detection.md create mode 100644 rfcs/RFC-0006-untrusted-pr-gate.md create mode 100644 rfcs/TEMPLATE.md create mode 100644 tests/validate-rfcs.test.js diff --git a/README.md b/README.md index 0ed1373..5044143 100644 --- a/README.md +++ b/README.md @@ -207,8 +207,10 @@ Mintlify docs live in [`docs/mintlify`](docs/mintlify): - [AI SDLC Trends & Loopholes](docs/mintlify/reference/loopholes-roadmap.mdx) - [Business Hub](docs/mintlify/reference/business-hub.mdx) - [Research Program](docs/mintlify/reference/research-program.mdx) +- [RFC / ADR Process](docs/mintlify/reference/rfc-process.mdx) +- [Research-Backed Design Decisions](docs/mintlify/reference/research-backed-design.mdx) -Research-paper source material lives in [`research/`](research/): bibliography, methodology, prior-art comparison, productivity claims discipline, design history, paper outline, and the current-state audit. +Research-paper source material lives in [`research/`](research/): bibliography, methodology, prior-art comparison, productivity claims discipline, design history, paper outline, and the current-state audit. Architecture decisions live in [`rfcs/`](rfcs/), with CI-backed validation for filename/status/section discipline. The original presentation is kept as a backup at: diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json index aef2cb5..afa57cd 100644 --- a/docs/mintlify/docs.json +++ b/docs/mintlify/docs.json @@ -38,7 +38,9 @@ "reference/approvals", "reference/webhooks", "reference/loopholes-roadmap", - "reference/research-program" + "reference/research-program", + "reference/research-backed-design", + "reference/rfc-process" ] }, { @@ -90,7 +92,9 @@ "reference/configuration", "reference/protected-actions", "reference/loopholes-roadmap", - "reference/research-program" + "reference/research-program", + "reference/research-backed-design", + "reference/rfc-process" ] } ] diff --git a/docs/mintlify/mint.json b/docs/mintlify/mint.json index 0742a9b..dd2c2d0 100644 --- a/docs/mintlify/mint.json +++ b/docs/mintlify/mint.json @@ -112,7 +112,9 @@ "reference/observability", "reference/configuration", "reference/protected-actions", - "reference/research-program" + "reference/research-program", + "reference/research-backed-design", + "reference/rfc-process" ] } ], diff --git a/docs/mintlify/reference/research-backed-design.mdx b/docs/mintlify/reference/research-backed-design.mdx new file mode 100644 index 0000000..0b24fb4 --- /dev/null +++ b/docs/mintlify/reference/research-backed-design.mdx @@ -0,0 +1,44 @@ +--- +title: "Research-Backed Design Decisions" +description: "How RStack turns prior art, standards, and implementation evidence into governed product evolution." +--- + +RStack is developed through research-backed design decisions, not ad-hoc feature copying. The project compares prior art, captures claims discipline, records RFCs, and then implements validated roadmap slices. + +## Development loop + +```text +research → issue → RFC/ADR → implementation PR → validation → evidence → paper update +``` + +## What this means in practice + +1. **Research first** — RStack starts with references such as NIST AI RMF, NIST SSDF, ISO/IEC 42001, OWASP LLM Top 10, SLSA, DSSE, Sigstore, Augment Code's AI-SDLC reference architecture, and `ai-sdlc-framework/ai-sdlc`. +2. **Issue tracking** — roadmap ideas are captured in GitHub issues with acceptance criteria and paper angles. +3. **RFC/ADR** — major design decisions are recorded under `rfcs/` before implementation. +4. **Implementation** — code and docs changes are delivered through PRs with local validation and CI. +5. **Evidence discipline** — productivity claims are measured or clearly marked as hypotheses. + +## Primary-source artifacts + +- [`research/bibliography.md`](https://github.com/richard-devbot/SDLC-rstack/blob/main/research/bibliography.md) +- [`research/methodology.md`](https://github.com/richard-devbot/SDLC-rstack/blob/main/research/methodology.md) +- [`research/productivity-claims.md`](https://github.com/richard-devbot/SDLC-rstack/blob/main/research/productivity-claims.md) +- [`research/prior-art-ai-sdlc-framework.md`](https://github.com/richard-devbot/SDLC-rstack/blob/main/research/prior-art-ai-sdlc-framework.md) +- [`rfcs/`](https://github.com/richard-devbot/SDLC-rstack/tree/main/rfcs) + +## Current roadmap chain + +The first research-backed chain is: + +1. [#77 Research bibliography and methodology](https://github.com/richard-devbot/SDLC-rstack/issues/77) — completed first to establish claims discipline. +2. [#76 RFC / ADR process](https://github.com/richard-devbot/SDLC-rstack/issues/76) — records decisions before major implementation. +3. [#70 Decision Queue / DoR](https://github.com/richard-devbot/SDLC-rstack/issues/70) — first product feature that should follow an RFC. + +## Paper-safe wording + +Use this wording until measured evidence exists: + +> RStack creates the governed lifecycle, evidence structure, and observability needed to measure and improve AI-assisted software delivery. + +Do not claim quantified productivity improvement until RStack has measured comparison runs. diff --git a/docs/mintlify/reference/rfc-process.mdx b/docs/mintlify/reference/rfc-process.mdx new file mode 100644 index 0000000..2f6bd12 --- /dev/null +++ b/docs/mintlify/reference/rfc-process.mdx @@ -0,0 +1,59 @@ +--- +title: "RFC / ADR Process" +description: "How RStack records research-backed architecture decisions and roadmap governance." +--- + +RStack uses RFCs as lightweight Architecture Decision Records. The process keeps major AI-SDLC platform decisions explicit, reviewable, and citable. + +## Why RFCs matter + +RStack is evolving from an npm package into a research-backed AI-SDLC operating layer. That means important choices should be traceable: + +- why the feature exists, +- what decision was made, +- what alternatives were rejected, +- which research or prior-art references informed the decision, +- how implementation will be validated. + +This turns roadmap work into primary-source evidence for the RStack research paper. + +## Registry + +The source registry lives in [`rfcs/`](https://github.com/richard-devbot/SDLC-rstack/tree/main/rfcs). + +| RFC | Status | Issue | Purpose | +|---|---|---:|---| +| [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-0002](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0002-decision-queue-and-readiness-gate.md) | Draft | [#70](https://github.com/richard-devbot/SDLC-rstack/issues/70) | Decision Queue and Definition-of-Ready gate. | +| [RFC-0003](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0003-cross-harness-validation.md) | Draft | [#72](https://github.com/richard-devbot/SDLC-rstack/issues/72) | Cross-harness validation independence. | +| [RFC-0004](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0004-attestation-envelope.md) | Draft | [#73](https://github.com/richard-devbot/SDLC-rstack/issues/73) | Attestation envelope. | +| [RFC-0005](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0005-traceability-drift-detection.md) | Draft | [#74](https://github.com/richard-devbot/SDLC-rstack/issues/74) | Traceability drift detection. | +| [RFC-0006](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0006-untrusted-pr-gate.md) | Draft | [#75](https://github.com/richard-devbot/SDLC-rstack/issues/75) | Untrusted PR gate. | + +## Lifecycle states + +- `Draft` — proposed and open for refinement. +- `Accepted` — approved for implementation. +- `Implemented` — shipped and validated. +- `Superseded` — replaced by a later RFC. + +## Validation + +RStack includes a CI-backed RFC validator in `tests/validate-rfcs.test.js`. It checks: + +- RFC filenames use `RFC-000N-short-title.md`, +- headers match the file number, +- statuses are valid, +- required sections exist, +- RFC numbers are unique and sequential, +- the index links every RFC. + +Run locally: + +```bash +npm test -- tests/validate-rfcs.test.js +``` + +## Human review rule + +RFC PRs should wait for CI and reviewer-bot comments before merge. A human operator should approve the merge after reviewing the summary. diff --git a/package.json b/package.json index fd3b91b..06505f0 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "rstack-agents", "version": "1.8.0", - "description": "Production-ready agentic SDLC framework for Pi and coding agents — orchestrator, builder/validator teams, lifecycle state, and specialist reuse", + "description": "Production-ready agentic SDLC framework for Pi and coding agents \u2014 orchestrator, builder/validator teams, lifecycle state, and specialist reuse", "type": "module", "main": "src/index.js", "bin": { @@ -48,6 +48,7 @@ "docs/public/", "docs/HARNESS.md", "research/", + "rfcs/", "operator.json", "README.md" ], diff --git a/rfcs/README.md b/rfcs/README.md new file mode 100644 index 0000000..10865f5 --- /dev/null +++ b/rfcs/README.md @@ -0,0 +1,80 @@ + + +# RStack RFC / ADR Registry + +RStack uses RFCs as lightweight Architecture Decision Records (ADRs). The goal is not bureaucracy; the goal is traceable, citable design history for a research-backed AI-SDLC platform. + +RFCs are required when a change affects one or more of: + +- public lifecycle semantics, +- `.rstack` state shape, +- builder/validator contract fields, +- Business Hub governance behavior, +- package or adapter compatibility, +- security, compliance, or evidence guarantees, +- research claims or paper methodology. + +Small bug fixes, copy edits, and implementation-only refactors do not need an RFC unless they change a documented decision. + +## Lifecycle states + +Every RFC must include exactly one `## Status` section whose first non-empty line is one of: + +| Status | Meaning | +|---|---| +| `Draft` | Proposed direction; implementation should not claim stability yet. | +| `Accepted` | Direction approved for implementation; details may still evolve. | +| `Implemented` | Code/docs shipped and validated. | +| `Superseded` | Replaced by a later RFC; link to the replacement. | + +## File naming + +RFC filenames must use this format: + +```text +RFC-000N-short-kebab-title.md +``` + +Examples: + +- `RFC-0001-rstack-spec-v1alpha1.md` +- `RFC-0002-decision-queue-and-readiness-gate.md` + +Numbers are append-only. Do not renumber accepted or implemented RFCs. + +## Required sections + +Use [`TEMPLATE.md`](TEMPLATE.md). The CI validator checks that each RFC has the required sections: + +1. `# RFC-000N: Title` +2. `## Status` +3. `## Context` +4. `## Decision` +5. `## Alternatives considered` +6. `## Research references` +7. `## Implementation plan` +8. `## Validation` + +## Current registry + +| RFC | Status | Roadmap issue | Purpose | +|---|---|---:|---| +| [RFC-0001: RStack Spec v1alpha1](RFC-0001-rstack-spec-v1alpha1.md) | Draft | [#71](https://github.com/richard-devbot/SDLC-rstack/issues/71) | Define public schemas and conformance examples for RStack artifacts. | +| [RFC-0002: Decision Queue and readiness gate](RFC-0002-decision-queue-and-readiness-gate.md) | Draft | [#70](https://github.com/richard-devbot/SDLC-rstack/issues/70) | Introduce decision objects and Definition-of-Ready enforcement. | +| [RFC-0003: Cross-harness validation](RFC-0003-cross-harness-validation.md) | Draft | [#72](https://github.com/richard-devbot/SDLC-rstack/issues/72) | Require independent builder/validator harness evidence. | +| [RFC-0004: Attestation envelope](RFC-0004-attestation-envelope.md) | Draft | [#73](https://github.com/richard-devbot/SDLC-rstack/issues/73) | Wrap builder, validator, and release evidence in a signable envelope. | +| [RFC-0005: Traceability drift detection](RFC-0005-traceability-drift-detection.md) | Draft | [#74](https://github.com/richard-devbot/SDLC-rstack/issues/74) | Detect drift across requirements, tasks, evidence, and docs. | +| [RFC-0006: Untrusted PR gate](RFC-0006-untrusted-pr-gate.md) | Draft | [#75](https://github.com/richard-devbot/SDLC-rstack/issues/75) | Add protected-path handling for untrusted contributor PRs. | + +## How to update an RFC + +1. Start an issue or PR that explains the proposed change. +2. Add or edit an RFC on a branch. +3. Link the RFC to research references and implementation issues. +4. Run `npm test` so `tests/validate-rfcs.test.js` validates filenames, statuses, and required sections. +5. Wait for CI and CodeRabbit review. +6. Merge only after human approval. + +## Research-paper value + +The RFC registry is primary-source evidence for the RStack paper. It shows that the platform evolves through explicit design decisions grounded in prior art, standards, implementation constraints, and measurable validation plans. diff --git a/rfcs/RFC-0001-rstack-spec-v1alpha1.md b/rfcs/RFC-0001-rstack-spec-v1alpha1.md new file mode 100644 index 0000000..47df0b5 --- /dev/null +++ b/rfcs/RFC-0001-rstack-spec-v1alpha1.md @@ -0,0 +1,43 @@ + + +# RFC-0001: RStack Spec v1alpha1 + +## Status +Draft + +## Context +RStack already has `.rstack` run state, lifecycle stages, builder/validator contracts, evidence JSONL, approvals, profiles, and Business Hub state. These artifacts work inside the package, but they are not yet formalized as a public spec. A public spec is needed before external harnesses, research papers, or enterprise adopters can reason about conformance. + +## Decision +Adopt a `spec/`-first direction for RStack v1alpha1. The spec should define canonical resources such as Run, Task, StageArtifact, BuilderReport, ValidatorReport, EvidenceEvent, Approval, Decision, Profile, BudgetPolicy, and future AttestationEnvelope. JSON schemas should be versioned and shipped with conformance examples. + +## Alternatives considered +- **Do nothing:** keeps RStack fast to evolve, but weakens interoperability and paper credibility. +- **Clone the external AI-SDLC spec:** rejected because RStack should adapt patterns while preserving its Business Hub and npm package identity. +- **Schema only, no narrative spec:** rejected because human-readable semantics matter for research and adoption. + +## Research references +- RStack research bibliography: `research/bibliography.md` +- RStack prior-art comparison: `research/prior-art-ai-sdlc-framework.md` +- RStack current-state audit: `research/current-state-audit.md` +- Epic tracker: https://github.com/richard-devbot/SDLC-rstack/issues/79 +- Prior-art repo: https://github.com/ai-sdlc-framework/ai-sdlc +- Roadmap issue: https://github.com/richard-devbot/SDLC-rstack/issues/71 + +## Implementation plan +- Create `spec/rstack-spec.md`. +- Create `spec/schemas/` with versioned JSON schemas. +- Add conformance examples under `spec/examples/`. +- Add tests that validate examples against schemas. +- Link spec docs from Mintlify and README. +- Keep backward compatibility with existing `.rstack` artifacts where feasible. + +## Validation +- `npm test` passes. +- Schema example validation passes. +- `npm pack --dry-run --json` includes spec files when package allowlist is updated. +- Business Hub still reads existing run artifacts. +- Paper claims reference a concrete spec version instead of informal implementation notes. + +## Paper angle +Define a public RStack specification with JSON schemas and conformance examples. This RFC records the rationale before implementation so the RStack paper can cite design intent, accepted tradeoffs, and validation criteria. diff --git a/rfcs/RFC-0002-decision-queue-and-readiness-gate.md b/rfcs/RFC-0002-decision-queue-and-readiness-gate.md new file mode 100644 index 0000000..86360ee --- /dev/null +++ b/rfcs/RFC-0002-decision-queue-and-readiness-gate.md @@ -0,0 +1,42 @@ + + +# RFC-0002: Decision Queue and readiness gate + +## Status +Draft + +## Context +RStack currently supports clarify, plan, spec, approval, build, validate, and release-readiness stages. Approval gates exist, but there is no first-class Decision Queue that captures unresolved product/architecture/security decisions and blocks build until ready. + +## Decision +Add decision objects under `.rstack/runs//decisions/` and expose them in Business Hub. The Definition-of-Ready gate should block build when required decisions are unresolved or when required approval evidence is missing. + +## Alternatives considered +- **Use free-text planning docs only:** insufficient for gating and metrics. +- **Make every question a blocking approval:** too heavy for lean profiles. +- **Adopt a heavy workflow engine:** rejected to preserve RStack's simple package install. + +## Research references +- RStack research bibliography: `research/bibliography.md` +- RStack prior-art comparison: `research/prior-art-ai-sdlc-framework.md` +- RStack current-state audit: `research/current-state-audit.md` +- Epic tracker: https://github.com/richard-devbot/SDLC-rstack/issues/79 +- Prior-art repo: https://github.com/ai-sdlc-framework/ai-sdlc +- Roadmap issue: https://github.com/richard-devbot/SDLC-rstack/issues/70 + +## Implementation plan +- Define decision object shape. +- Add decision creation/resolution helpers. +- Add DoR validation command or harness stage check. +- Add Business Hub Decision Queue panel. +- Add profile-specific strictness. +- Add tests for blocked/unblocked runs. + +## Validation +- Tests prove unresolved required decisions block build. +- Tests prove optional decisions do not block lean workflows. +- Business Hub displays pending decisions from real `.rstack` state. +- Research metrics can count decisions captured before build. + +## Paper angle +Introduce first-class decisions and a Definition-of-Ready gate before build work proceeds. This RFC records the rationale before implementation so the RStack paper can cite design intent, accepted tradeoffs, and validation criteria. diff --git a/rfcs/RFC-0003-cross-harness-validation.md b/rfcs/RFC-0003-cross-harness-validation.md new file mode 100644 index 0000000..3ccd4bc --- /dev/null +++ b/rfcs/RFC-0003-cross-harness-validation.md @@ -0,0 +1,41 @@ + + +# RFC-0003: Cross-harness validation + +## Status +Draft + +## Context +RStack already separates builder and validator contracts, but the current contract does not require that validation be performed by an independent harness, model, or runtime. Cross-harness validation helps reduce correlated failure and rubber-stamp validation. + +## Decision +Add optional-to-strict review independence metadata to builder and validator reports. Enterprise profiles should be able to require validator harness/model identity to differ from builder identity for protected stages. + +## Alternatives considered +- **Trust same-harness validation:** simpler but weaker for high-stakes changes. +- **Always require a different vendor:** too rigid and may increase cost. +- **Manual reviewer only:** useful, but not enough for automated RStack evidence. + +## Research references +- RStack research bibliography: `research/bibliography.md` +- RStack prior-art comparison: `research/prior-art-ai-sdlc-framework.md` +- RStack current-state audit: `research/current-state-audit.md` +- Epic tracker: https://github.com/richard-devbot/SDLC-rstack/issues/79 +- Prior-art repo: https://github.com/ai-sdlc-framework/ai-sdlc +- Roadmap issue: https://github.com/richard-devbot/SDLC-rstack/issues/72 + +## Implementation plan +- Extend contract metadata with harness/model identity. +- Add independence check helper. +- Add profile policy fields for `review_independence`. +- Surface independence status in Business Hub. +- Add tests for pass/fail independence combinations. + +## Validation +- Contract tests cover missing, equal, and independent harness identities. +- Enterprise profile can require independence. +- Business Hub displays review independence status. +- Validation failure messages are actionable. + +## Paper angle +Require validator independence from the builder harness for higher-trust workflows. This RFC records the rationale before implementation so the RStack paper can cite design intent, accepted tradeoffs, and validation criteria. diff --git a/rfcs/RFC-0004-attestation-envelope.md b/rfcs/RFC-0004-attestation-envelope.md new file mode 100644 index 0000000..35f7d49 --- /dev/null +++ b/rfcs/RFC-0004-attestation-envelope.md @@ -0,0 +1,41 @@ + + +# RFC-0004: Attestation envelope + +## Status +Draft + +## Context +RStack has evidence JSONL and builder/validator reports, but evidence is not yet packaged into a standard signable envelope. Enterprise users need tamper-evident provenance and audit-friendly evidence bundles. + +## Decision +Design a local-first attestation envelope inspired by DSSE/SLSA/Sigstore patterns. Initial implementation can be unsigned but schema-compatible with future signing. Envelopes should reference run ID, task ID, stage, subject artifacts, builder/validator identity, evidence, and verification results. + +## Alternatives considered +- **Raw JSONL only:** easy, but hard to verify or cite. +- **Require signing immediately:** too much setup for early users. +- **Adopt DSSE byte-for-byte now:** may overfit before RStack payloads are stable. + +## Research references +- RStack research bibliography: `research/bibliography.md` +- RStack prior-art comparison: `research/prior-art-ai-sdlc-framework.md` +- RStack current-state audit: `research/current-state-audit.md` +- Epic tracker: https://github.com/richard-devbot/SDLC-rstack/issues/79 +- Prior-art repo: https://github.com/ai-sdlc-framework/ai-sdlc +- Roadmap issue: https://github.com/richard-devbot/SDLC-rstack/issues/73 + +## Implementation plan +- Define `AttestationEnvelope` schema. +- Add envelope generation for builder/validator/release readiness. +- Add verification helper for local structural checks. +- Add docs explaining unsigned vs signed modes. +- Add future hooks for Sigstore signing. + +## Validation +- Envelope schema validation passes. +- Verification fails malformed evidence. +- Package dry-run includes schemas/docs. +- Research paper can cite evidence-envelope semantics without claiming cryptographic signing until implemented. + +## Paper angle +Wrap builder, validator, and release evidence in a structured signable envelope. This RFC records the rationale before implementation so the RStack paper can cite design intent, accepted tradeoffs, and validation criteria. diff --git a/rfcs/RFC-0005-traceability-drift-detection.md b/rfcs/RFC-0005-traceability-drift-detection.md new file mode 100644 index 0000000..08c3e41 --- /dev/null +++ b/rfcs/RFC-0005-traceability-drift-detection.md @@ -0,0 +1,41 @@ + + +# RFC-0005: Traceability drift detection + +## Status +Draft + +## Context +Business Hub already has traceability state, but RStack does not yet enforce traceability completeness or detect drift. AI-assisted development can produce code that no longer maps cleanly to requirements or documentation. + +## Decision +Add a drift detector that scans requirement artifacts, task records, stage artifacts, evidence events, and docs references. The detector should produce findings with severity, missing links, stale references, and recommended remediation. + +## Alternatives considered +- **Dashboard-only traceability:** informative but not enforceable. +- **Require perfect traceability in every profile:** too heavy for lean MVPs. +- **Use external ALM only:** weakens RStack's self-contained package story. + +## Research references +- RStack research bibliography: `research/bibliography.md` +- RStack prior-art comparison: `research/prior-art-ai-sdlc-framework.md` +- RStack current-state audit: `research/current-state-audit.md` +- Epic tracker: https://github.com/richard-devbot/SDLC-rstack/issues/79 +- Prior-art repo: https://github.com/ai-sdlc-framework/ai-sdlc +- Roadmap issue: https://github.com/richard-devbot/SDLC-rstack/issues/74 + +## Implementation plan +- Define traceability link model. +- Add drift scanner. +- Add Business Hub drift findings panel. +- Add profile thresholds. +- Add CI/release-readiness integration for strict profiles. + +## Validation +- Tests cover missing requirement links, stale docs references, and clean runs. +- Business Hub reads drift findings from `.rstack` state. +- Strict profile can fail release readiness on high-severity drift. +- Research metrics can measure evidence completeness. + +## Paper angle +Detect drift from requirements to tasks to evidence to docs. This RFC records the rationale before implementation so the RStack paper can cite design intent, accepted tradeoffs, and validation criteria. diff --git a/rfcs/RFC-0006-untrusted-pr-gate.md b/rfcs/RFC-0006-untrusted-pr-gate.md new file mode 100644 index 0000000..9d5c399 --- /dev/null +++ b/rfcs/RFC-0006-untrusted-pr-gate.md @@ -0,0 +1,41 @@ + + +# RFC-0006: Untrusted PR gate + +## Status +Draft + +## Context +RStack ships agents, prompts, plugins, and lifecycle code. Changes to these areas can alter agent behavior, governance, or security posture. Public contribution flows need a protected-path gate that distinguishes trusted maintainers from untrusted contributors. + +## Decision +Add a GitHub Actions gate that identifies untrusted PRs touching protected paths and requires maintainer approval before dangerous workflows or package validation paths proceed. The gate should be documented as part of RStack governance. + +## Alternatives considered +- **Rely only on normal CI:** does not address trust boundary concerns. +- **Block all external PRs:** too hostile to contributors. +- **Manual review with no automation:** easy to miss protected-path changes. + +## Research references +- RStack research bibliography: `research/bibliography.md` +- RStack prior-art comparison: `research/prior-art-ai-sdlc-framework.md` +- RStack current-state audit: `research/current-state-audit.md` +- Epic tracker: https://github.com/richard-devbot/SDLC-rstack/issues/79 +- Prior-art repo: https://github.com/ai-sdlc-framework/ai-sdlc +- Roadmap issue: https://github.com/richard-devbot/SDLC-rstack/issues/75 + +## Implementation plan +- Define protected paths. +- Add workflow or script for PR trust classification. +- Add docs for maintainers and contributors. +- Add tests for protected-path matching if script-based. +- Surface the model in RFC/research docs. + +## Validation +- CI gate identifies protected-path changes. +- Trusted maintainer paths remain low friction. +- Untrusted PRs receive clear instructions. +- Security baseline remains green. + +## Paper angle +Protect sensitive RStack paths in untrusted contributor PRs. This RFC records the rationale before implementation so the RStack paper can cite design intent, accepted tradeoffs, and validation criteria. diff --git a/rfcs/TEMPLATE.md b/rfcs/TEMPLATE.md new file mode 100644 index 0000000..2f09826 --- /dev/null +++ b/rfcs/TEMPLATE.md @@ -0,0 +1,24 @@ + + +# RFC-000N: Title + +## Status +Draft + +## Context +What problem are we solving? Describe the user, product, research, governance, or implementation pressure that makes this decision necessary. + +## Decision +What are we choosing? Be concrete about artifacts, files, commands, data model changes, policy changes, and compatibility expectations. + +## Alternatives considered +What options did we reject, and why? Include "do nothing" when useful. + +## Research references +List papers, reports, standards, repositories, issues, and docs that justify the decision. + +## Implementation plan +List concrete tasks and likely files. Link GitHub issues when the implementation is tracked elsewhere. + +## Validation +How will we prove this decision works? Include tests, CLI checks, CI checks, docs checks, and research metrics when relevant. diff --git a/tests/validate-package-assets.test.js b/tests/validate-package-assets.test.js index feb61ee..7ab25ba 100644 --- a/tests/validate-package-assets.test.js +++ b/tests/validate-package-assets.test.js @@ -21,9 +21,9 @@ test('package-local publishable asset directories exist', () => { } }); -test('package.json ships Pi extension, agents, skills, prompts, and plugins', async () => { +test('package.json ships Pi extension, agents, skills, prompts, plugins, research, and RFCs', async () => { const pkg = await readJson('package.json'); - for (const required of ['extensions/', 'agents/', 'skills/', 'prompts/', 'plugins/']) { + for (const required of ['extensions/', 'agents/', 'skills/', 'prompts/', 'plugins/', 'research/', 'rfcs/']) { assert.ok(pkg.files.includes(required), `package.json files should include ${required}`); } assert.deepEqual(pkg.pi.extensions, ['./extensions/rstack-sdlc.ts']); diff --git a/tests/validate-rfcs.test.js b/tests/validate-rfcs.test.js new file mode 100644 index 0000000..295e2da --- /dev/null +++ b/tests/validate-rfcs.test.js @@ -0,0 +1,71 @@ +/** + * Validate RStack RFC / ADR registry structure. + */ + +import test from 'node:test'; +import assert from 'node:assert/strict'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { readdir, readFile } from 'node:fs/promises'; +import { existsSync } from 'node:fs'; + +const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..'); +const RFCS_DIR = path.join(REPO_ROOT, 'rfcs'); +const VALID_STATUSES = new Set(['Draft', 'Accepted', 'Implemented', 'Superseded']); +const REQUIRED_SECTIONS = [ + '## Status', + '## Context', + '## Decision', + '## Alternatives considered', + '## Research references', + '## Implementation plan', + '## Validation', +]; + +async function rfcFiles() { + const entries = await readdir(RFCS_DIR, { withFileTypes: true }); + return entries + .filter((entry) => entry.isFile() && /^RFC-\d{4}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(entry.name)) + .map((entry) => entry.name) + .sort(); +} + +function statusFrom(text) { + const match = text.match(/^## Status\s*\n+([^\n]+)/m); + return match?.[1]?.trim(); +} + +test('RFC registry files and template exist', () => { + assert.ok(existsSync(path.join(RFCS_DIR, 'README.md')), 'rfcs/README.md should exist'); + assert.ok(existsSync(path.join(RFCS_DIR, 'TEMPLATE.md')), 'rfcs/TEMPLATE.md should exist'); +}); + +test('RFC files use valid names, headers, statuses, and required sections', async () => { + const files = await rfcFiles(); + assert.ok(files.length >= 6, 'expected initial roadmap RFC stubs'); + + const seenNumbers = []; + for (const file of files) { + const number = Number(file.match(/^RFC-(\d{4})-/)[1]); + seenNumbers.push(number); + const text = await readFile(path.join(RFCS_DIR, file), 'utf8'); + + assert.match(text, new RegExp(`^# RFC-${String(number).padStart(4, '0')}: .+`, 'm'), `${file} header should match filename number`); + const status = statusFrom(text); + assert.ok(VALID_STATUSES.has(status), `${file} has invalid status: ${status}`); + for (const section of REQUIRED_SECTIONS) { + assert.ok(text.includes(section), `${file} missing ${section}`); + } + assert.ok(text.includes('RStack developed by Richardson Gunde'), `${file} should carry owner label`); + } + + assert.deepEqual(seenNumbers, [...new Set(seenNumbers)], 'RFC numbers should be unique'); + assert.deepEqual(seenNumbers, seenNumbers.map((_, index) => index + 1), 'RFC numbers should be sequential from 0001'); +}); + +test('RFC README indexes every RFC file', async () => { + const readme = await readFile(path.join(RFCS_DIR, 'README.md'), 'utf8'); + for (const file of await rfcFiles()) { + assert.ok(readme.includes(file), `README should link ${file}`); + } +}); From 1fc63094a782d515eeaa7273a54ccdb5f6aacac8 Mon Sep 17 00:00:00 2001 From: Richardson Gunde Date: Wed, 10 Jun 2026 09:58:58 +0530 Subject: [PATCH 2/2] docs: address RFC review feedback --- .../reference/research-backed-design.mdx | 2 +- docs/mintlify/reference/rfc-process.mdx | 16 +++++++++------- rfcs/README.md | 4 +++- tests/validate-references.test.js | 4 +++- tests/validate-rfcs.test.js | 8 ++++++++ 5 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/mintlify/reference/research-backed-design.mdx b/docs/mintlify/reference/research-backed-design.mdx index 0b24fb4..56b91d8 100644 --- a/docs/mintlify/reference/research-backed-design.mdx +++ b/docs/mintlify/reference/research-backed-design.mdx @@ -13,7 +13,7 @@ research → issue → RFC/ADR → implementation PR → validation → evidence ## What this means in practice -1. **Research first** — RStack starts with references such as NIST AI RMF, NIST SSDF, ISO/IEC 42001, OWASP LLM Top 10, SLSA, DSSE, Sigstore, Augment Code's AI-SDLC reference architecture, and `ai-sdlc-framework/ai-sdlc`. +1. **Research first** — RStack starts with references such as NIST Artificial Intelligence Risk Management Framework (AI RMF), NIST Secure Software Development Framework (SSDF), ISO/IEC 42001:2023 AI management systems, OWASP Top 10 for Large Language Model Applications, Supply-chain Levels for Software Artifacts (SLSA), Dead Simple Signing Envelope (DSSE), Sigstore, Augment Code's AI-SDLC reference architecture, and `ai-sdlc-framework/ai-sdlc`. 2. **Issue tracking** — roadmap ideas are captured in GitHub issues with acceptance criteria and paper angles. 3. **RFC/ADR** — major design decisions are recorded under `rfcs/` before implementation. 4. **Implementation** — code and docs changes are delivered through PRs with local validation and CI. diff --git a/docs/mintlify/reference/rfc-process.mdx b/docs/mintlify/reference/rfc-process.mdx index 2f6bd12..c29b66f 100644 --- a/docs/mintlify/reference/rfc-process.mdx +++ b/docs/mintlify/reference/rfc-process.mdx @@ -23,12 +23,12 @@ The source registry lives in [`rfcs/`](https://github.com/richard-devbot/SDLC-rs | RFC | Status | Issue | Purpose | |---|---|---:|---| -| [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-0002](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0002-decision-queue-and-readiness-gate.md) | Draft | [#70](https://github.com/richard-devbot/SDLC-rstack/issues/70) | Decision Queue and Definition-of-Ready gate. | -| [RFC-0003](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0003-cross-harness-validation.md) | Draft | [#72](https://github.com/richard-devbot/SDLC-rstack/issues/72) | Cross-harness validation independence. | -| [RFC-0004](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0004-attestation-envelope.md) | Draft | [#73](https://github.com/richard-devbot/SDLC-rstack/issues/73) | Attestation envelope. | -| [RFC-0005](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0005-traceability-drift-detection.md) | Draft | [#74](https://github.com/richard-devbot/SDLC-rstack/issues/74) | Traceability drift detection. | -| [RFC-0006](https://github.com/richard-devbot/SDLC-rstack/blob/main/rfcs/RFC-0006-untrusted-pr-gate.md) | Draft | [#75](https://github.com/richard-devbot/SDLC-rstack/issues/75) | Untrusted PR gate. | +| [RFC-0001](../../../rfcs/RFC-0001-rstack-spec-v1alpha1.md) | Draft | #71 | RStack Spec v1alpha1. | +| [RFC-0002](../../../rfcs/RFC-0002-decision-queue-and-readiness-gate.md) | Draft | #70 | Decision Queue and Definition-of-Ready gate. | +| [RFC-0003](../../../rfcs/RFC-0003-cross-harness-validation.md) | Draft | #72 | Cross-harness validation independence. | +| [RFC-0004](../../../rfcs/RFC-0004-attestation-envelope.md) | Draft | #73 | Attestation envelope. | +| [RFC-0005](../../../rfcs/RFC-0005-traceability-drift-detection.md) | Draft | #74 | Traceability drift detection. | +| [RFC-0006](../../../rfcs/RFC-0006-untrusted-pr-gate.md) | Draft | #75 | Untrusted PR gate. | ## Lifecycle states @@ -51,9 +51,11 @@ RStack includes a CI-backed RFC validator in `tests/validate-rfcs.test.js`. It c Run locally: ```bash -npm test -- tests/validate-rfcs.test.js +npm test ``` +For a fast local RFC-only check, run `npx tsx --test tests/validate-rfcs.test.js`. + ## Human review rule RFC PRs should wait for CI and reviewer-bot comments before merge. A human operator should approve the merge after reviewing the summary. diff --git a/rfcs/README.md b/rfcs/README.md index 10865f5..95343ac 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -32,9 +32,11 @@ Every RFC must include exactly one `## Status` section whose first non-empty lin RFC filenames must use this format: ```text -RFC-000N-short-kebab-title.md +RFC-000N-lowercase-kebab-slug.md ``` +The slug must match the validator pattern `[a-z0-9]+(?:-[a-z0-9]+)*`: lowercase letters and digits separated by hyphens. Uppercase letters, underscores, spaces, and punctuation are intentionally rejected by CI. + Examples: - `RFC-0001-rstack-spec-v1alpha1.md` diff --git a/tests/validate-references.test.js b/tests/validate-references.test.js index 431775b..10bb7b7 100644 --- a/tests/validate-references.test.js +++ b/tests/validate-references.test.js @@ -8,6 +8,7 @@ import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { readdir, readFile } from 'node:fs/promises'; import { existsSync } from 'node:fs'; +import { execFileSync } from 'node:child_process'; const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..'); @@ -27,7 +28,8 @@ async function walk(dir, predicate = () => true) { test('no legacy hidden workspace directories are required', () => { for (const dir of ['.claude', '.agents', '.codex']) { - assert.equal(existsSync(path.join(REPO_ROOT, dir)), false, `${dir} should not exist`); + const trackedFiles = execFileSync('git', ['ls-files', dir], { cwd: REPO_ROOT, encoding: 'utf8' }).trim(); + assert.equal(trackedFiles, '', `${dir} should not be tracked or required by package runtime`); } }); diff --git a/tests/validate-rfcs.test.js b/tests/validate-rfcs.test.js index 295e2da..e0cfb15 100644 --- a/tests/validate-rfcs.test.js +++ b/tests/validate-rfcs.test.js @@ -22,6 +22,10 @@ const REQUIRED_SECTIONS = [ '## Validation', ]; +/** + * Return sorted RFC markdown filenames that follow the public RFC naming contract. + * Non-RFC support files such as README.md and TEMPLATE.md are intentionally excluded. + */ async function rfcFiles() { const entries = await readdir(RFCS_DIR, { withFileTypes: true }); return entries @@ -30,6 +34,10 @@ async function rfcFiles() { .sort(); } +/** + * Extract the first status value from an RFC document. + * The validator requires this value to be one of the documented lifecycle states. + */ function statusFrom(text) { const match = text.match(/^## Status\s*\n+([^\n]+)/m); return match?.[1]?.trim();