richard-devbot · richard-devbot · Jun 10, 2026 · Jun 10, 2026
diff --git 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
@@ -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
@@ -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
@@ -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 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.
+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
@@ -0,0 +1,61 @@
+---
+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](../../../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
+
+- `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
+```
+
+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/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
@@ -0,0 +1,82 @@
+<!-- owner: RStack developed by Richardson Gunde -->
+
+# 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-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`
+- `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
@@ -0,0 +1,43 @@
+<!-- owner: RStack developed by Richardson Gunde -->
+
+# 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
@@ -0,0 +1,42 @@
+<!-- owner: RStack developed by Richardson Gunde -->
+
+# 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/<run-id>/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
@@ -0,0 +1,41 @@
+<!-- owner: RStack developed by Richardson Gunde -->
+
+# 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.