@codedrifters/configulator 0.0.234 → 0.0.236

package/lib/index.mjs

@@ -7264,6 +7264,106 @@ var projenBundle = {
   ]
 };
 
+// src/agent/bundles/requirements-taxonomy.ts
+var REQUIREMENTS_TAXONOMY_TABLE_SECTION = [
+  "## The 11-Category Taxonomy",
+  "",
+  "All requirements follow the BIZBOK-aligned 11-category taxonomy",
+  "below. Getting requirements into the right category matters because",
+  "it determines which template applies, which standards inform it, and",
+  "how it traces to other requirements.",
+  "",
+  "| Category | Prefix | Directory (default) | Question it answers |",
+  "|----------|--------|---------------------|---------------------|",
+  "| Business Requirements | BR | `business/` | **Why** are we building this? What business value does it deliver? |",
+  "| Functional Requirements | FR | `functional/` | **What** does the system do? What is the user-visible behavior? |",
+  "| Non-Functional Requirements | NFR | `non-functional/` | **How well** must the system perform? What quality bar must it meet? |",
+  "| Technical Requirements | TR | `technical/` | **What technology** are we using, and why that one? |",
+  "| Architectural Decisions | ADR | `architectural-decisions/` | **What structural decision** are we making, and what are the trade-offs? |",
+  "| Security & Compliance | SEC | `security/` | **What must we protect**, and what rules govern that protection? |",
+  "| Data Requirements | DR | `data/` | **What data** do we store, how long, and how do we recover it? |",
+  "| Integration Requirements | INT | `integration/` | **What external systems** do we connect to, and how? |",
+  "| Operational Requirements | OPS | `operational/` | **How do we deploy, monitor, and respond** to incidents? |",
+  "| UX Requirements | UX | `ux/` | **How must the interface look, feel, and behave** for users? |",
+  "| Multi-Tenancy & Licensing | MT | `multi-tenancy/` | **How do we isolate tenants, gate features, and meter usage?** |",
+  "",
+  "All requirement documents live under `<REQUIREMENTS_ROOT>` in the",
+  "category directory shown above. Directory names are defaults \u2014",
+  "consuming projects may rename them, but the prefixes are universal."
+];
+var REQUIREMENTS_TAXONOMY_DISAMBIGUATION_SECTION = [
+  "- **SEC vs NFR:** Protecting data, enforcing access control, or",
+  "  meeting a regulation \u2192 SEC. System performance, uptime, or",
+  '  scalability \u2192 NFR. "99.9% uptime" is NFR; "audit logs for all',
+  '  admin actions" is SEC.',
+  '- **TR vs ADR:** A TR pins down a specific technology choice ("use',
+  '  PostgreSQL 16+"). An ADR records a structural decision with',
+  '  context, trade-offs, and alternatives ("why row-level isolation',
+  '  over schema-per-tenant"). TRs often follow from ADRs.',
+  "- **FR vs INT:** What the user experiences \u2192 FR. How two systems",
+  '  communicate \u2192 INT. "User can pay with a credit card" is FR;',
+  '  "Stripe Checkout API integration for payment processing" is INT.',
+  "- **DR vs SEC:** What data exists, how long we keep it, and how we",
+  "  recover it \u2192 DR. Who can access it and how it's protected \u2192 SEC.",
+  "  These often cross-reference each other.",
+  "- **NFR vs OPS:** A measurable target the system must meet \u2192 NFR.",
+  '  The tooling and processes to run the system \u2192 OPS. "p99 latency',
+  '  < 200ms" is NFR; "Datadog APM for latency monitoring" is OPS.'
+];
+var REQUIREMENTS_TIER_TABLE_SECTION = [
+  "| Tier | Slug | When to use |",
+  "|------|------|-------------|",
+  "| **Platform** | `platform` | Core platform services \u2014 APIs, tenant isolation, auth, event bus, shared infrastructure |",
+  "| **Industry** | `industry` | Vertical-specific capabilities not every tenant needs |",
+  "| **Customer Workflow** | `customer-workflow` | Business logic tenants configure within the platform \u2014 approval chains, notification rules, intake processes |",
+  "| **Consumer Application** | `consumer-app` | UI/UX and integrations in external front-ends/systems consuming the platform's APIs |"
+];
+var REQ_WRITE_ISSUE_SCHEMA_SECTION = [
+  "The body of every `req:write` issue **must** declare the three",
+  "fields below. The downstream `requirements-writer` agent parses",
+  "them on intake and will refuse to write a document (and flag the",
+  "issue `status:needs-attention`) if any required field is missing",
+  "or contradictory.",
+  "",
+  "### Required Fields",
+  "",
+  "- **Category:** one of `BR` / `FR` / `NFR` / `TR` / `ADR` / `SEC` /",
+  "  `DR` / `INT` / `OPS` / `UX` / `MT`. Must match the category",
+  "  prefix in the requirement's title and file name.",
+  "- **Tier:** one of `platform` / `industry` / `customer-workflow` /",
+  "  `consumer-app`. Must match the `tier:*` label applied to the",
+  "  issue.",
+  "- **Output Path:** absolute-from-repo-root path ending in",
+  "  `<PREFIX>-<NNN>-<slug>.md` under the target category directory",
+  "  (for example,",
+  "  `docs/requirements/functional/FR-012-checkout-flow.md`).",
+  "",
+  "### Strongly Recommended",
+  "",
+  "- **Inputs / Read:** bullet list of source files the writer should",
+  "  consult \u2014 the upstream proposal file (when one exists), the",
+  "  BCM/source document(s) the proposal cites, and any related",
+  "  requirements the new document should trace to. Omit only for",
+  "  ad-hoc requirements where no upstream proposal exists; the",
+  "  writer will then treat the issue body itself as the input.",
+  "",
+  "### Missing Fields",
+  "",
+  "When an upstream producer cannot derive one of the required",
+  "fields, it **must not** guess a value. Instead it opens the",
+  "`req:write` issue with `status:needs-attention` (not",
+  "`status:ready`) and includes a `Missing:` line listing the",
+  "field(s) that could not be determined. For example:",
+  "",
+  "```",
+  "Missing: Tier \u2014 source document has no tier metadata and the",
+  "referencing requirement is cross-tier.",
+  "```",
+  "",
+  "A human triages the issue, fills in the missing field, and flips",
+  "the label to `status:ready` before the writer picks it up."
+];
+
 // src/agent/bundles/requirements-analyst.ts
 var requirementsAnalystSubAgent = {
   name: "requirements-analyst",
@@ -7494,6 +7594,7 @@ var requirementsAnalystSubAgent = {
     "   ## Proposed: <PREFIX>-<NNN> \u2014 <Title>",
     "",
     "   **Category:** <FR/BR/NFR/SEC/DR/INT/OPS/UX/MT/ADR/TR>",
+    "   **Tier:** <platform/industry/customer-workflow/consumer-app>",
     "   **Priority:** <High/Normal/Low>",
     "   **Source:** <document path and section>",
     "",
@@ -7547,6 +7648,41 @@ var requirementsAnalystSubAgent = {
     "**Budget:** No web searches. Issue creation + minor edits to source",
     "documents.",
     "",
+    "### `req:write` issue schema",
+    "",
+    "The `req:write` issues this phase creates are picked up by the",
+    "downstream `requirements-writer` agent, which parses a strict",
+    "schema on intake. The authoritative schema is defined in the",
+    "`requirements-writer` sub-agent prompt under **The `req:write`",
+    "Issue Schema** \u2014 every `req:write` issue this phase opens must",
+    "conform. The same schema is embedded in the",
+    "`requirements-reviewer` follow-up generator so the three",
+    "producers never drift apart.",
+    "",
+    ...REQ_WRITE_ISSUE_SCHEMA_SECTION,
+    "",
+    "**Deriving the three required fields from the proposal.** For",
+    "every `req:write` issue this phase opens, the three fields come",
+    "directly from the Phase 2 proposal entry:",
+    "",
+    "- **Category** \u2014 the proposal's `**Category:**` line.",
+    "- **Tier** \u2014 the proposal's `**Tier:**` line (added in Phase 2).",
+    "  If the proposal omitted the Tier line (older proposals may),",
+    "  route the issue through `Missing:` rather than guessing.",
+    "- **Output Path** \u2014",
+    "  `<REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md`,",
+    "  using the sequence number determined in Phase 2 step 4.",
+    "",
+    "**Validation step \u2014 required before opening the issue.** Before",
+    "calling `gh issue create`, verify all three required fields are",
+    "populated and internally consistent (Category matches title",
+    "prefix, Tier matches `tier:*` label, Output Path filename starts",
+    "with the Category prefix). If any field cannot be derived, open",
+    "the issue with `status:needs-attention` (not `status:ready`) and",
+    "include a `Missing: <field> \u2014 <one-line reason>` line so a human",
+    "triaging the issue only has to supply the remaining value(s)",
+    "before flipping the label to `status:ready`.",
+    "",
     "### Steps",
     "",
     "1. **Read the proposals** from Phase 2.",
@@ -7555,21 +7691,26 @@ var requirementsAnalystSubAgent = {
     "",
     "   All `type:requirement` issues default to `priority:medium` (override",
     "   only if the proposal's priority was explicitly High or Low). Each",
-    "   issue must also carry the `req:write` phase label so the downstream",
-    "   `requirements-writer` bundle picks it up.",
+    "   issue must also carry the `req:write` phase label plus the matching",
+    "   `tier:*` label so the downstream `requirements-writer` bundle picks",
+    "   it up with the correct tier.",
     "",
     "   ```bash",
     "   gh issue create \\",
     '     --title "docs(<category>): <PREFIX>-<NNN> \u2014 <title>" \\',
-    '     --label "type:requirement" --label "req:write" --label "status:ready" --label "priority:medium" \\',
+    '     --label "type:requirement" --label "req:write" --label "tier:<tier-slug>" --label "status:ready" --label "priority:medium" \\',
     '     --body "## Objective',
     "   Write <PREFIX>-<NNN> \u2014 <title>.",
     "",
+    "   **Category:** <BR/FR/NFR/TR/ADR/SEC/DR/INT/OPS/UX/MT>",
+    "   **Tier:** <platform/industry/customer-workflow/consumer-app>",
+    "   **Output Path:** <REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md",
+    "",
     "   ## Context",
     "   - **Gap identified by:** requirements scan of <source>",
     "   - **Proposals file:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md",
     "",
-    "   ## Inputs",
+    "   ## Inputs / Read",
     "   - **Depends on:** (none)",
     "   - **Read:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md, <source docs>",
     "",
@@ -7580,12 +7721,17 @@ var requirementsAnalystSubAgent = {
     "   - [ ] Decision authority rules followed (direct write vs. proposed)",
     "",
     "   ## Scope Size",
-    "   small",
-    "",
-    "   ## Output Path",
-    '   <REQUIREMENTS_ROOT>/<category>/<PREFIX>-<NNN>-<slug>.md"',
+    '   small"',
     "   ```",
     "",
+    "   When one of Category / Tier / Output Path could not be derived",
+    "   from the proposal (for example, the proposal omitted the Tier",
+    "   line), replace `status:ready` with `status:needs-attention` in",
+    "   the label list and add a `Missing: <field> \u2014 <reason>` line",
+    "   directly below the Output Path line in the body. Populate",
+    "   whichever of the three fields **could** be derived so a human",
+    "   triaging the issue has the minimum possible cleanup.",
+    "",
     "3. **Update source documents.** In each BCM model doc or competitive",
     "   analysis that was scanned, add a note in the project-relevance /",
     "   strategic-implications section (whichever heading the source doc uses)",
@@ -7746,61 +7892,6 @@ var requirementsAnalystBundle = {
   ]
 };
 
-// src/agent/bundles/requirements-taxonomy.ts
-var REQUIREMENTS_TAXONOMY_TABLE_SECTION = [
-  "## The 11-Category Taxonomy",
-  "",
-  "All requirements follow the BIZBOK-aligned 11-category taxonomy",
-  "below. Getting requirements into the right category matters because",
-  "it determines which template applies, which standards inform it, and",
-  "how it traces to other requirements.",
-  "",
-  "| Category | Prefix | Directory (default) | Question it answers |",
-  "|----------|--------|---------------------|---------------------|",
-  "| Business Requirements | BR | `business/` | **Why** are we building this? What business value does it deliver? |",
-  "| Functional Requirements | FR | `functional/` | **What** does the system do? What is the user-visible behavior? |",
-  "| Non-Functional Requirements | NFR | `non-functional/` | **How well** must the system perform? What quality bar must it meet? |",
-  "| Technical Requirements | TR | `technical/` | **What technology** are we using, and why that one? |",
-  "| Architectural Decisions | ADR | `architectural-decisions/` | **What structural decision** are we making, and what are the trade-offs? |",
-  "| Security & Compliance | SEC | `security/` | **What must we protect**, and what rules govern that protection? |",
-  "| Data Requirements | DR | `data/` | **What data** do we store, how long, and how do we recover it? |",
-  "| Integration Requirements | INT | `integration/` | **What external systems** do we connect to, and how? |",
-  "| Operational Requirements | OPS | `operational/` | **How do we deploy, monitor, and respond** to incidents? |",
-  "| UX Requirements | UX | `ux/` | **How must the interface look, feel, and behave** for users? |",
-  "| Multi-Tenancy & Licensing | MT | `multi-tenancy/` | **How do we isolate tenants, gate features, and meter usage?** |",
-  "",
-  "All requirement documents live under `<REQUIREMENTS_ROOT>` in the",
-  "category directory shown above. Directory names are defaults \u2014",
-  "consuming projects may rename them, but the prefixes are universal."
-];
-var REQUIREMENTS_TAXONOMY_DISAMBIGUATION_SECTION = [
-  "- **SEC vs NFR:** Protecting data, enforcing access control, or",
-  "  meeting a regulation \u2192 SEC. System performance, uptime, or",
-  '  scalability \u2192 NFR. "99.9% uptime" is NFR; "audit logs for all',
-  '  admin actions" is SEC.',
-  '- **TR vs ADR:** A TR pins down a specific technology choice ("use',
-  '  PostgreSQL 16+"). An ADR records a structural decision with',
-  '  context, trade-offs, and alternatives ("why row-level isolation',
-  '  over schema-per-tenant"). TRs often follow from ADRs.',
-  "- **FR vs INT:** What the user experiences \u2192 FR. How two systems",
-  '  communicate \u2192 INT. "User can pay with a credit card" is FR;',
-  '  "Stripe Checkout API integration for payment processing" is INT.',
-  "- **DR vs SEC:** What data exists, how long we keep it, and how we",
-  "  recover it \u2192 DR. Who can access it and how it's protected \u2192 SEC.",
-  "  These often cross-reference each other.",
-  "- **NFR vs OPS:** A measurable target the system must meet \u2192 NFR.",
-  '  The tooling and processes to run the system \u2192 OPS. "p99 latency',
-  '  < 200ms" is NFR; "Datadog APM for latency monitoring" is OPS.'
-];
-var REQUIREMENTS_TIER_TABLE_SECTION = [
-  "| Tier | Slug | When to use |",
-  "|------|------|-------------|",
-  "| **Platform** | `platform` | Core platform services \u2014 APIs, tenant isolation, auth, event bus, shared infrastructure |",
-  "| **Industry** | `industry` | Vertical-specific capabilities not every tenant needs |",
-  "| **Customer Workflow** | `customer-workflow` | Business logic tenants configure within the platform \u2014 approval chains, notification rules, intake processes |",
-  "| **Consumer Application** | `consumer-app` | UI/UX and integrations in external front-ends/systems consuming the platform's APIs |"
-];
-
 // src/agent/bundles/requirements-writer.ts
 var TEMPLATE_BR = `---
 title: "BR-NNN: [Business Requirement Title]"
@@ -10079,6 +10170,19 @@ var requirementsWriterSubAgent = {
     "",
     "---",
     "",
+    "## The `req:write` Issue Schema",
+    "",
+    "This section is the **authoritative schema** for `req:write` issue",
+    "bodies. Upstream producers (the `requirements-analyst` trace phase,",
+    "the `requirements-reviewer` follow-up generator, and any human",
+    "authoring a `req:write` issue directly) must embed or link to this",
+    "same schema so the three required fields are always present when",
+    "the writer picks the issue up.",
+    "",
+    ...REQ_WRITE_ISSUE_SCHEMA_SECTION,
+    "",
+    "---",
+    "",
     "## The `req:write` Phase",
     "",
     "**Goal:** Read the proposal that produced this issue, write a single",
@@ -10093,14 +10197,25 @@ var requirementsWriterSubAgent = {
     "",
     "### Steps",
     "",
-    "1. **Parse the issue.** The `req:write` issue body must include:",
-    "   - **Category** (`BR`/`FR`/`NFR`/`TR`/`ADR`/`SEC`/`DR`/`INT`/`OPS`/`UX`/`MT`)",
-    "   - **Tier** (`platform`/`industry`/`customer-workflow`/`consumer-app`)",
-    "   - **Output Path** under `<REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md`",
-    "   - **Inputs / Read** \u2014 the upstream proposals file and any source",
-    "     documents",
-    "   If any of these are missing or contradictory, comment on the",
-    "   issue, add `status:needs-attention`, and stop without writing.",
+    "1. **Parse the issue.** The `req:write` issue body follows the",
+    "   authoritative schema in the",
+    "   [The `req:write` Issue Schema](#the-reqwrite-issue-schema)",
+    "   section below. Before writing, verify every required field",
+    "   (Category, Tier, Output Path) is present and internally",
+    "   consistent:",
+    "",
+    "   - Category matches the prefix on the requirement title and on",
+    "     the Output Path filename.",
+    "   - Tier matches the `tier:*` label applied to the issue.",
+    "   - Output Path sits under",
+    "     `<REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md`.",
+    "",
+    "   If any required field is missing, contradictory, or the issue",
+    "   already carries `status:needs-attention` with a `Missing:` line",
+    "   (upstream could not derive it), comment on the issue with",
+    "   which field is wrong, ensure `status:needs-attention` is set,",
+    "   and stop without writing. A human triages before the writer",
+    "   tries again.",
     "",
     "2. **Read the proposal.** Open the proposals file referenced in the",
     "   issue inputs (under `<RESEARCH_REQUIREMENTS_ROOT>`). Find the",
@@ -10395,7 +10510,7 @@ var requirementsWriterBundle = {
 // src/agent/bundles/requirements-reviewer.ts
 var requirementsReviewerSubAgent = {
   name: "requirements-reviewer",
-  description: "Audits and deprecates existing requirement documents (BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT). In `req:review` mode, runs the 11-check audit (structural compliance, categorization, traceability, cross-reference integrity, sequence integrity, content quality, registry sync, decision-authority compliance, tier classification, cross-referencing conventions) and produces a report grouped by Critical / Warning / Info. In `req:deprecate` mode, transitions target documents to `Deprecated` or `Superseded`, updates the category index row, and files `req:write` follow-ups for every back-reference so the writer can rewrite them. One phase per session.",
+  description: "Audits and deprecates existing requirement documents (BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT). In `req:review` mode, runs the 12-check audit (structural compliance, categorization, traceability, cross-reference integrity, sequence integrity, content quality, registry sync, decision-authority compliance, tier classification, cross-referencing conventions, stale `Proposed` ADR/TR decisions) and produces a report grouped by Critical / Warning / Info (plus a dedicated Stale decisions section). In `req:deprecate` mode, transitions target documents to `Deprecated` or `Superseded`, updates the category index row, and files `req:write` follow-ups for every back-reference so the writer can rewrite them. One phase per session.",
   model: AGENT_MODEL.POWERFUL,
   maxTurns: 80,
   platforms: { cursor: { exclude: true } },
@@ -10522,6 +10637,7 @@ var requirementsReviewerSubAgent = {
     "| `<REVIEW_REPORTS_ROOT>` | Where review reports are written | `docs/research/reviews/` |",
     `| \`<TEMPLATES_ROOT>\` | Where the writer bundle ships category templates (read-only for this agent) | \`${REQUIREMENTS_WRITER_PATHS.templatesRoot}\` |`,
     `| \`<STANDARDS_REF>\` | Standards & frameworks reference shipped by the writer bundle | \`${REQUIREMENTS_WRITER_PATHS.standardsRef}\` |`,
+    "| `<STALE_PROPOSED_THRESHOLD_DAYS>` | Age (in days) after which a `Proposed` ADR/TR is flagged as a stale decision by Check 12 | `14` |",
     "",
     "If `docs/project-context.md` specifies a different requirements",
     "tree, prefer that. Otherwise fall back to the defaults above.",
@@ -10571,7 +10687,7 @@ var requirementsReviewerSubAgent = {
     "",
     "## Review Checklist",
     "",
-    "Apply the following 11 checks. Each check produces zero or more",
+    "Apply the following 12 checks. Each check produces zero or more",
     "findings. Findings are graded Critical / Warning / Info using the",
     "severity ladder in the next section.",
     "",
@@ -10816,6 +10932,60 @@ var requirementsReviewerSubAgent = {
     "  reverse-link structure (e.g., a `referencedIn.meetings[]`",
     "  frontmatter block) and that structure is in active use.",
     "",
+    "### 12. Stale Proposed Decisions",
+    "",
+    "ADR and TR documents ship as `Status: Proposed` because they",
+    "encode architectural or technology decisions that require explicit",
+    "human acceptance (see Check 9 and the `requirements-writer`",
+    "decision-authority rules). Once `Proposed`, there is no automatic",
+    "signal that surfaces long-`Proposed` documents for decision \u2014 the",
+    "backlog silently accumulates. Check 12 surfaces them.",
+    "",
+    "For every document under `<REQUIREMENTS_ROOT>` whose category is",
+    "**ADR** or **TR** and whose `Status` is `Proposed`:",
+    "",
+    "- Determine the document's last-touched date. Prefer the YAML",
+    "  frontmatter `updated` field when present. If frontmatter does",
+    "  not carry an `updated` field, fall back to the most recent entry",
+    "  in the `## Revision History` section. If neither exists, fall",
+    "  back to `git log -1 --format=%cI -- <path>` for the file.",
+    "- Compare that date to today. If the document has carried",
+    "  `Status: Proposed` for longer than",
+    "  `<STALE_PROPOSED_THRESHOLD_DAYS>` days (default 14), record a",
+    "  **Warning** finding that names the document, the age in days,",
+    "  the threshold, and the source used for the last-touched date.",
+    "- Do **not** flag `Proposed` ADRs or TRs that are below the",
+    "  threshold \u2014 they are in active decision and not stale.",
+    "- Do **not** auto-transition any status. Deprecation and",
+    "  acceptance both remain human decisions: Check 12 only surfaces",
+    "  the backlog for the human running `/review-requirements` (or",
+    "  for the follow-up issue it files) to act on.",
+    "",
+    "The threshold placeholder `<STALE_PROPOSED_THRESHOLD_DAYS>` is",
+    "configurable \u2014 override it in the `req:review` issue body, in",
+    "`docs/project-context.md`, or via `agentConfig.rules`. The default",
+    "of 14 days sits above the orchestrator's existing 72h / 168h stale",
+    "thresholds for `status:in-progress` / `status:blocked` and fits",
+    "the pace at which architectural decisions are typically ratified.",
+    "",
+    "Findings from Check 12 describe a decision the human must make \u2014",
+    "not an edit to the requirement document itself. Follow-up routing",
+    "is therefore different from Checks 3 and 4:",
+    "",
+    "- Surface every stale `Proposed` ADR/TR in a distinct",
+    "  **Stale decisions** section in the review report (see Reporting",
+    "  Format below), separate from Critical / Warning / Info.",
+    "- File **one** follow-up issue covering the stale decisions found",
+    "  in this review. Title:",
+    "  `req(review): decide on stale Proposed ADR/TR documents`.",
+    "  Labels: `type:requirement`, `req:review`, `priority:medium`,",
+    "  `status:needs-attention`. Body must list each stale document",
+    "  path, its age in days, and a link back to the review report.",
+    "  Do **not** file one follow-up per document \u2014 humans triage the",
+    "  backlog in a single pass.",
+    "- When no stale documents are found, omit the Stale decisions",
+    "  section entirely and do not file the follow-up issue.",
+    "",
     "---",
     "",
     "## Severity Ladder",
@@ -10851,6 +11021,13 @@ var requirementsReviewerSubAgent = {
     "- Missing cross-tier traceability; missing Implementor / Customer",
     "  fields on Customer Workflow / Consumer Application requirements",
     "  when the project tracks those fields",
+    "- Stale `Proposed` ADR/TR documents that have carried the",
+    "  `Proposed` status longer than",
+    "  `<STALE_PROPOSED_THRESHOLD_DAYS>` (default 14) days. The",
+    "  underlying document is valid; only the absence of human",
+    "  decision is stale, so these are reported in the report's",
+    "  dedicated **Stale decisions** section rather than inline in",
+    "  the Warning list.",
     "",
     "### Info (Consider)",
     "",
@@ -10894,6 +11071,20 @@ var requirementsReviewerSubAgent = {
     "1. **[<file path>] <short title>** `Info`",
     "   ...",
     "",
+    "## Stale decisions",
+    "",
+    "*Omit this section entirely when Check 12 found no stale",
+    "`Proposed` ADR/TR documents.*",
+    "",
+    "| Document | Age (days) | Threshold | Last-touched source |",
+    "|----------|------------|-----------|---------------------|",
+    "| `<file path>` | N | <STALE_PROPOSED_THRESHOLD_DAYS> | frontmatter `updated` / revision history / git log |",
+    "",
+    "Human decision required for each row. A single follow-up",
+    "`req:review` issue (labels `type:requirement`, `req:review`,",
+    "`priority:medium`, `status:needs-attention`) is filed to",
+    "track triage; see Check 12 for the exact follow-up contract.",
+    "",
     "## Review Summary",
     "",
     "| Severity | Count |",
@@ -10901,6 +11092,7 @@ var requirementsReviewerSubAgent = {
     "| Critical | N |",
     "| Warning | N |",
     "| Info | N |",
+    "| Stale decisions | N |",
     "",
     "**Categories reviewed:** [list]",
     "**Documents reviewed:** N",
@@ -10962,7 +11154,7 @@ var requirementsReviewerSubAgent = {
     "1. Read scope from the `req:review` issue.",
     "2. Read the matching templates from `<TEMPLATES_ROOT>` for every",
     "   category in scope.",
-    "3. Run the 11 checks. For audits >10 documents, write the",
+    "3. Run the 12 checks. For audits >10 documents, write the",
     "   verification script to disk first and run it.",
     "4. Write the report to",
     "   `<REVIEW_REPORTS_ROOT>/review-<scope>-YYYY-MM-DD.md`.",
@@ -10992,7 +11184,9 @@ var requirementsReviewerSubAgent = {
     "    `requirements-writer` agent picks it up to revise the",
     "    document). Only the writer is scoped to edit requirement",
     "    documents, so anything that requires an in-place edit under",
-    "    `<REQUIREMENTS_ROOT>` routes here.",
+    "    `<REQUIREMENTS_ROOT>` routes here. `req:write` follow-ups",
+    "    must also carry the matching `tier:*` label and an issue",
+    "    body that conforms to the `req:write` issue schema below.",
     "  - Missing traceability in **source documents** \u2014 BCM model",
     "    docs, competitive-analysis notes, product-roadmap entries,",
     "    meeting extracts \u2014 that should link forward to an existing",
@@ -11013,9 +11207,81 @@ var requirementsReviewerSubAgent = {
     "- Adds `status:ready` (or `status:blocked` when the finding",
     "  declares a `Depends on: #N` on another open issue)",
     "",
+    "**Check 12 exception \u2014 stale `Proposed` ADR/TR triage.** Check 12",
+    "findings are the one case where follow-up flows through a new",
+    "`req:review` issue rather than `req:write` / `req:trace` /",
+    "`req:scan`. The finding is a decision a human must make, not an",
+    "edit to a requirement document, so:",
+    "",
+    "- File **one** aggregated follow-up (not one per document). The",
+    "  title is",
+    "  `req(review): decide on stale Proposed ADR/TR documents`.",
+    "- Labels: `type:requirement`, `req:review`, `priority:medium`,",
+    "  `status:needs-attention`.",
+    "- Body lists every stale document surfaced in this review with",
+    "  its path, age in days, and the threshold used, and links back",
+    "  to the Stale decisions section of the review report.",
+    "- This is the **only** case in which the reviewer opens a",
+    "  `req:review` issue \u2014 it is explicitly not self-referential",
+    "  because the new issue triages decisions rather than triggering",
+    "  another review.",
+    "- The `req:write` follow-up schema below does **not** apply to",
+    "  this Check 12 issue; the schema governs `req:write` payloads,",
+    "  and this follow-up is a `req:review` triage item.",
+    "",
+    "### `req:write` follow-up schema",
+    "",
+    "Because this bundle is the second-largest producer of `req:write`",
+    "issues (the analyst's trace phase is the first), every `req:write`",
+    "follow-up opened in either the review phase or the deprecation",
+    "phase must satisfy the schema the writer parses on intake:",
+    "",
+    ...REQ_WRITE_ISSUE_SCHEMA_SECTION,
+    "",
+    "**Deriving the three required fields from the target document.**",
+    "For every structural-repair follow-up the reviewer generates, the",
+    "three fields come directly from the requirement document being",
+    "edited:",
+    "",
+    "- **Category** \u2014 read the category prefix from the document's",
+    "  filename (`FR-012-...` \u2192 `FR`). Confirm against the frontmatter",
+    "  / Metadata table `ID` row and the document's `# Heading`. If",
+    "  the three disagree, route through `Missing:` with the",
+    "  disagreement noted rather than picking one.",
+    "- **Tier** \u2014 read the Metadata table `Tier` row. Normalize to the",
+    "  slug form (`platform`, `industry`, `customer-workflow`,",
+    "  `consumer-app`). If the Tier row is missing, empty, or set to",
+    "  a value outside the four-tier taxonomy, route through",
+    "  `Missing:`.",
+    "- **Output Path** \u2014 the current absolute-from-repo-root path of",
+    "  the document being edited. The writer edits in place; the path",
+    "  does not change for a structural repair.",
+    "",
+    "For deprecation back-reference follow-ups, the three fields come",
+    "from the **referencing** document (the one that still mentions",
+    "the deprecated ID), not the deprecated target itself.",
+    "",
+    "**Validation step \u2014 required before opening the issue.** The",
+    "reviewer asserts all three required fields are populated before",
+    "it calls `gh issue create`. If any field cannot be derived:",
+    "",
+    "1. Open the follow-up with `status:needs-attention` (not",
+    "   `status:ready`).",
+    "2. Include a `Missing: <field> \u2014 <one-line reason>` line at the",
+    "   top of the body explaining which field could not be",
+    "   determined and why (e.g., `Missing: Tier \u2014 Metadata table",
+    "   has no Tier row and the document predates the four-tier",
+    "   classification`).",
+    "3. Populate whichever of the three fields **could** be derived",
+    "   so a human triaging the issue only has to supply the",
+    "   remaining value(s) before flipping the label to",
+    "   `status:ready`.",
+    "",
     "**Do NOT create:**",
     "",
-    "- `req:review` issues \u2014 that would be self-referential",
+    "- `req:review` issues for any reason other than the Check 12",
+    "  stale-decisions triage documented above \u2014 that would be",
+    "  self-referential",
     "- `bcm:*`, `people:*`, `company:*`, `software:*`, `research:*`,",
     "  or `industry:*` issues \u2014 those belong to their respective",
     "  bundles. If the review surfaces work for one of those bundles,",
@@ -11190,15 +11456,26 @@ var requirementsReviewerSubAgent = {
     "  references that a single writer session can address together).",
     "- The issue title must be",
     "  `req(deprecate): update references to <deprecated-ID> in <referencing-ID>`.",
-    "- The body must include: the referencing document path, the",
-    "  deprecated document path, the successor path (when applicable),",
-    "  the list of line ranges that mention the deprecated ID, the",
-    "  `req:deprecate` issue number, and a short instruction asking the",
-    "  writer to either remove the reference, point it at the successor,",
-    "  or convert it to a historical note (the writer decides per",
+    "- The body must conform to the `req:write` issue schema defined",
+    "  in the review phase's **`req:write` follow-up schema** section",
+    "  above: Category, Tier, and Output Path derived from the",
+    "  **referencing** document (not the deprecated target) via the",
+    "  same rules \u2014 prefix from filename, Tier from the Metadata",
+    "  table, Output Path is the referencing document's current path.",
+    "  In addition, the body must include: the deprecated document",
+    "  path, the successor path (when applicable), the list of line",
+    "  ranges that mention the deprecated ID, the `req:deprecate`",
+    "  issue number, and a short instruction asking the writer to",
+    "  either remove the reference, point it at the successor, or",
+    "  convert it to a historical note (the writer decides per",
     "  reference).",
-    "- Labels: `type:requirement`, `req:write`, `priority:medium`,",
-    "  `status:ready`.",
+    "- Labels: `type:requirement`, `req:write`, the matching",
+    "  `tier:*` label derived from the referencing document's Tier,",
+    "  `priority:medium`, `status:ready`.",
+    "- If any of Category / Tier / Output Path cannot be derived from",
+    "  the referencing document, open the follow-up with",
+    "  `status:needs-attention` and a `Missing:` line, per the same",
+    "  validation rule that applies in the review phase.",
     "- Body must include `Depends on: #<req:deprecate issue number>`",
     "  when the rewrite should wait for the deprecation to land, or",
     "  omit that line when the rewrite can run in parallel.",
@@ -11285,7 +11562,7 @@ var requirementsReviewerSubAgent = {
 };
 var reviewRequirementsSkill = {
   name: "review-requirements",
-  description: "Audit existing requirement documents (BR / FR / NFR / TR / ADR / SEC / DR / INT / OPS / UX / MT) for structural compliance, categorization, traceability, cross-reference integrity, sequence integrity, content quality, registry sync, decision-authority compliance, tier classification, and cross-referencing conventions. Supports four scopes (full audit, category, single document, targeted check) and dispatches the requirements-reviewer agent. Audits documents \u2014 never writes them. Soft dependency: expects requirement templates at `" + REQUIREMENTS_WRITER_PATHS.templatesRoot + "`, shipped by the requirements-writer bundle.",
+  description: "Audit existing requirement documents (BR / FR / NFR / TR / ADR / SEC / DR / INT / OPS / UX / MT) for structural compliance, categorization, traceability, cross-reference integrity, sequence integrity, content quality, registry sync, decision-authority compliance, tier classification, cross-referencing conventions, and stale `Proposed` ADR/TR decisions. Supports four scopes (full audit, category, single document, targeted check) and dispatches the requirements-reviewer agent. Audits documents \u2014 never writes them. Soft dependency: expects requirement templates at `" + REQUIREMENTS_WRITER_PATHS.templatesRoot + "`, shipped by the requirements-writer bundle.",
   disableModelInvocation: true,
   userInvocable: true,
   context: "fork",
@@ -11317,9 +11594,10 @@ var reviewRequirementsSkill = {
     "- `category:<slug>` \u2014 audit one category directory (e.g.,",
     "  `category:functional` audits every FR)",
     "- `doc:<path>` \u2014 audit one specific requirement file",
-    "- `check:<n>[,<n>...]` \u2014 run one or more checks (1\u201311) across the",
+    "- `check:<n>[,<n>...]` \u2014 run one or more checks (1\u201312) across the",
     "  documents in scope (e.g., `check:4` runs cross-reference",
-    "  integrity only)",
+    "  integrity only, `check:12` runs the stale-proposed-decision",
+    "  audit only)",
     "",
     "Optional extensions in the issue body:",
     "",
@@ -11327,6 +11605,9 @@ var reviewRequirementsSkill = {
     "- `requirements-root: <path>` \u2014 override `<REQUIREMENTS_ROOT>`",
     "- `targets: <glob>` \u2014 restrict the document set with a glob",
     "  pattern relative to `<REQUIREMENTS_ROOT>`",
+    "- `stale-proposed-threshold-days: <n>` \u2014 override the default",
+    "  14-day threshold used by Check 12 (stale `Proposed` ADR/TR",
+    "  decisions) for this review",
     "",
     "## Default Paths",
     "",
@@ -11345,10 +11626,12 @@ var reviewRequirementsSkill = {
     "   scope, the requirements root (or accept the default), and the",
     "   output path.",
     "2. Execute the review phase of the requirements-reviewer agent.",
-    "3. The agent runs the 11-check audit, writes a structured report",
-    "   grouped by Critical / Warning / Info, files follow-up issues",
-    "   for actionable findings, and comments on the `req:review`",
-    "   issue with the summary.",
+    "3. The agent runs the 12-check audit, writes a structured report",
+    "   grouped by Critical / Warning / Info (plus a separate",
+    "   **Stale decisions** section when Check 12 surfaces stale",
+    "   `Proposed` ADR/TR documents), files follow-up issues for",
+    "   actionable findings, and comments on the `req:review` issue",
+    "   with the summary.",
     "",
     "## Audits >10 Documents",
     "",
@@ -11368,6 +11651,11 @@ var reviewRequirementsSkill = {
     "- Follow-up GitHub issues for every Critical and Warning finding,",
     "  carrying the appropriate phase label (`req:write`, `req:trace`,",
     "  or `req:scan`) for the downstream agent that should act",
+    "- An aggregated `req:review` follow-up issue labeled",
+    "  `status:needs-attention` when Check 12 surfaces stale `Proposed`",
+    "  ADR/TR documents (one issue per review, not one per document);",
+    "  the review report also includes a dedicated **Stale decisions**",
+    "  section in that case",
     "- A summary comment on the originating `req:review` issue"
   ].join("\n")
 };
@@ -11475,7 +11763,7 @@ var deprecateRequirementSkill = {
 };
 var requirementsReviewerBundle = {
   name: "requirements-reviewer",
-  description: "Requirements reviewer agent bundle. Audits existing requirement documents (BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT) via the 11-check review phase, and transitions requirements to `Deprecated` or `Superseded` via the deprecation phase (narrow writes to Status, Revision History, Superseded-by, and category index row, with `req:write` follow-ups for every back-reference). Reads templates from the requirements-writer bundle's reference directory; ships no templates of its own.",
+  description: "Requirements reviewer agent bundle. Audits existing requirement documents (BR, FR, NFR, TR, ADR, SEC, DR, INT, OPS, UX, MT) via the 12-check review phase (including Check 12: stale `Proposed` ADR/TR decisions), and transitions requirements to `Deprecated` or `Superseded` via the deprecation phase (narrow writes to Status, Revision History, Superseded-by, and category index row, with `req:write` follow-ups for every back-reference). Reads templates from the requirements-writer bundle's reference directory; ships no templates of its own.",
   appliesWhen: () => true,
   rules: [
     {
@@ -11500,14 +11788,26 @@ var requirementsReviewerBundle = {
         "Use `/review-requirements <scope>` to audit existing requirement",
         "documents. Four scopes are supported: `full` (every document),",
         "`category:<slug>` (one category directory), `doc:<path>` (one",
-        "specific document), and `check:<n>` (one or more of the 11",
+        "specific document), and `check:<n>` (one or more of the 12",
         "checks across the documents in scope).",
         "",
+        "Check 12 flags ADR and TR documents that have carried",
+        "`Status: Proposed` longer than",
+        "`<STALE_PROPOSED_THRESHOLD_DAYS>` days (default 14, configurable",
+        "via the `req:review` issue body, `docs/project-context.md`, or",
+        "`agentConfig.rules`). Stale decisions are reported in a separate",
+        "**Stale decisions** section of the review report and trigger one",
+        "aggregated `req:review` follow-up issue labeled",
+        "`status:needs-attention` so a human can triage the backlog. The",
+        "reviewer never auto-transitions status \u2014 acceptance and",
+        "deprecation both remain human decisions.",
+        "",
         "The review phase produces **review reports and follow-up issues",
         "only** \u2014 it never edits requirement documents, capability",
         "models, or research notes. It files follow-up issues with the",
-        "appropriate phase label (`req:write`, `req:trace`, or",
-        "`req:scan`) for the downstream agent to pick up.",
+        "appropriate phase label (`req:write`, `req:trace`, `req:scan`,",
+        "or \u2014 only for Check 12 stale-decision triage \u2014 `req:review`)",
+        "for the downstream agent or human to pick up.",
         "",
         "For audits covering more than 10 documents, the reviewer writes",
         "a read-only Python verification script alongside the report and",