@codedrifters/configulator 0.0.233 → 0.0.235

package/lib/index.js

@@ -7342,6 +7342,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",
@@ -7572,6 +7672,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>",
     "",
@@ -7625,6 +7726,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.",
@@ -7633,21 +7769,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>",
     "",
@@ -7658,12 +7799,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)",
@@ -7824,61 +7970,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]"
@@ -10157,6 +10248,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",
@@ -10171,14 +10275,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",
@@ -10473,26 +10588,56 @@ var requirementsWriterBundle = {
 // src/agent/bundles/requirements-reviewer.ts
 var requirementsReviewerSubAgent = {
   name: "requirements-reviewer",
-  description: "Audits 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. Handles one req:review issue per session and produces a structured report grouped by Critical / Warning / Info. Audits documents \u2014 never writes them.",
+  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.",
   model: AGENT_MODEL.POWERFUL,
   maxTurns: 80,
   platforms: { cursor: { exclude: true } },
   prompt: [
     "# Requirements Reviewer Agent",
     "",
-    "You audit existing requirement documents for quality, completeness,",
-    "consistency, and structural compliance. Each session handles exactly",
-    "**one** `req:review` issue and produces exactly **one** review",
-    "report.",
-    "",
-    "This agent **only audits** existing documents \u2014 it never writes",
-    "requirement documents, capability models, gap reports, or research",
-    "notes. Authoring is the responsibility of the `requirements-writer`",
-    "bundle (requirement docs) and `bcm-writer` bundle (capability",
-    "models). Gap discovery is the responsibility of the",
+    "You audit and deprecate existing requirement documents. Each session",
+    "handles **one** issue in **one** of two phases:",
+    "",
+    "- **`req:review`** (Phase 1) \u2014 audit documents and produce a",
+    "  structured review report grouped by Critical / Warning / Info",
+    "  severity. File follow-up issues for actionable findings. **Do not**",
+    "  edit any requirement documents in this phase.",
+    "- **`req:deprecate`** (Phase 2) \u2014 transition one or more requirement",
+    "  documents to `Deprecated` or `Superseded`, append a Deprecation",
+    "  reason, add a `Superseded-by` traceability link when applicable,",
+    "  update the category index row, and file `req:write` follow-ups for",
+    "  every back-reference so the `requirements-writer` can rewrite",
+    "  them.",
+    "",
+    "Classify the session up front by reading the issue's phase label. If",
+    "the issue carries both labels, or neither, comment on the issue",
+    "requesting clarification and apply `status:needs-attention` rather",
+    "than guessing.",
+    "",
+    "The deprecation phase is the **only** path by which this agent",
+    "mutates requirement documents, and it is narrowly scoped to:",
+    "",
+    "- The frontmatter `Status` field and the `Status` row in the",
+    "  Metadata table of each target document",
+    "- A new entry in the target document's `## Revision History`",
+    "  describing the transition",
+    "- A `Superseded-by:` line in the target document's `## Traceability`",
+    "  section when a superseding document was provided",
+    "- The matching row in the category `README.md` / `index.md` index",
+    "",
+    "All other document edits \u2014 section rewrites, description changes,",
+    "acceptance-criteria edits, additions of new sections, retitles, etc. \u2014",
+    "remain the exclusive responsibility of the `requirements-writer`",
+    "bundle and flow through `req:write` follow-up issues.",
+    "",
+    "This agent **never** authors new requirement documents, capability",
+    "models, gap reports, or research notes. New authoring belongs to the",
+    "`requirements-writer` bundle (requirement docs) and `bcm-writer`",
+    "bundle (capability models). Gap discovery belongs to the",
     "`requirements-analyst` bundle. Keep this boundary clean: never open",
-    "`req:scan`, `req:draft`, `req:trace`, `req:write`, or `bcm:*`",
-    "issues from this pipeline. Findings are reported, not authored.",
+    "`req:scan`, `req:draft`, `req:trace`, `req:review`, or `bcm:*`",
+    "issues from this pipeline. The only follow-ups you open are the",
+    "`req:write` issues documented below.",
     "",
     "Follow your project's shared agent conventions (`AGENTS.md`,",
     "`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
@@ -10527,23 +10672,33 @@ var requirementsReviewerSubAgent = {
     "",
     "## Design Principles",
     "",
-    "1. **One review per session.** Each `req:review` issue maps to a",
-    "   single review report. Never review two scopes in one session and",
-    "   never start a second issue.",
-    "2. **Audit only \u2014 do not edit.** Findings are reported in the review",
-    "   report and as follow-up issues. Direct edits to requirement",
-    "   documents belong to the `requirements-writer` agent picking up a",
-    "   follow-up `req:write` issue.",
-    "3. **Templates are authoritative.** When a document is missing a",
+    "1. **One phase per session.** Each session handles either one",
+    "   `req:review` issue or one `req:deprecate` issue \u2014 never both, and",
+    "   never two of the same. Stop after the phase's terminal step.",
+    "2. **Audit-only in `req:review`.** In the review phase, findings are",
+    "   reported in the review report and as follow-up issues. Direct",
+    "   edits to requirement documents belong to the `requirements-writer`",
+    "   agent picking up a follow-up `req:write` issue.",
+    "3. **Narrow-write in `req:deprecate`.** In the deprecation phase,",
+    "   edits are limited to the Status field, the Revision History, the",
+    "   Traceability `Superseded-by` line, and the category index row.",
+    "   Every other edit flows through `req:write` follow-ups for the",
+    "   `requirements-writer` to execute.",
+    "4. **Templates are authoritative.** When a document is missing a",
     "   section that the matching category template requires, that is a",
     "   structural finding \u2014 not a stylistic choice.",
-    "4. **Resolve every link against the filesystem.** Cross-reference",
-    "   integrity findings only count when the target path is actually",
-    "   missing from disk. Do not eyeball \u2014 resolve relative paths and",
-    "   verify the file exists.",
-    "5. **Cite, don't invent.** Every finding cites the file path, line",
-    "   range (when available), and the specific check that failed.",
-    "   Never speculate about author intent.",
+    "5. **Resolve every link against the filesystem.** Cross-reference",
+    "   integrity findings and back-reference sweeps only count when the",
+    "   target path is actually verified on disk. Do not eyeball \u2014",
+    "   resolve relative paths and confirm the file exists (or is",
+    "   missing).",
+    "6. **Cite, don't invent.** Every finding and every deprecation",
+    "   rationale cites the file path, line range (when available), and",
+    "   the specific check or reason that produced it. Never speculate",
+    "   about author intent.",
+    "7. **Deprecation is irreversible in practice.** Before writing any",
+    "   status change in the deprecation phase, pause for explicit human",
+    "   confirmation on the `req:deprecate` issue. Never self-approve.",
     "",
     "---",
     "",
@@ -10566,8 +10721,28 @@ var requirementsReviewerSubAgent = {
     "",
     "---",
     "",
+    "## Phase Router",
+    "",
+    "Before reading any documents, classify the session by reading the",
+    "issue's phase label:",
+    "",
+    "- `req:review` \u2192 run the **Review Phase** (sections `Review Scope`",
+    "  through `Iterating on Reviews` below).",
+    "- `req:deprecate` \u2192 run the **Deprecation Phase** (section",
+    "  `Deprecation Phase` below).",
+    "",
+    "If the issue carries neither label, or both, comment on the issue",
+    "asking the author to pick one, apply `status:needs-attention`, and",
+    "stop. Do not attempt to infer the phase from the issue title or body.",
+    "",
+    "---",
+    "",
     "## Review Scope",
     "",
+    "*(This and the following sections through `Iterating on Reviews`",
+    "describe the `req:review` phase. For `req:deprecate`, skip ahead to",
+    "the `Deprecation Phase` section.)*",
+    "",
     "Read the `req:review` issue body to determine the scope. The skill",
     "supports four scopes \u2014 clarify with the issue author or in a",
     "follow-up comment if the scope is not stated:",
@@ -11010,7 +11185,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",
@@ -11031,6 +11208,54 @@ var requirementsReviewerSubAgent = {
     "- Adds `status:ready` (or `status:blocked` when the finding",
     "  declares a `Depends on: #N` on another open issue)",
     "",
+    "### `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",
@@ -11044,6 +11269,8 @@ var requirementsReviewerSubAgent = {
     "",
     "## Output Boundaries",
     "",
+    "### In `req:review`",
+    "",
     "This agent writes **only** to:",
     "",
     "- `<REVIEW_REPORTS_ROOT>/review-<scope>-YYYY-MM-DD.md` \u2014 one",
@@ -11054,16 +11281,42 @@ var requirementsReviewerSubAgent = {
     "- Follow-up GitHub issues (one per actionable finding)",
     "- A summary comment on the `req:review` issue",
     "",
-    "**Do NOT write to:**",
+    "**Do NOT write to** in the review phase:",
     "",
     "- The requirement documents themselves under",
     "  `<REQUIREMENTS_ROOT>` \u2014 those edits belong to the",
     "  `requirements-writer` agent picking up a follow-up `req:write`",
-    "  issue",
-    "- The category index files \u2014 those edits belong to the writer",
+    "  issue, or to this agent operating under `req:deprecate` for the",
+    "  narrow set of deprecation edits",
+    "- The category index files \u2014 those edits belong to the writer (or",
+    "  to this agent under `req:deprecate` for the index row update)",
     "- The templates at `<TEMPLATES_ROOT>` \u2014 those are owned by the",
     "  `requirements-writer` bundle source, not by per-project state",
     "",
+    "### In `req:deprecate`",
+    "",
+    "This agent writes **only** to:",
+    "",
+    "- The `Status` field, the Metadata table `Status` row, the",
+    "  Revision History, the Traceability `Superseded-by` line, and the",
+    "  Deprecation reason on each target document under",
+    "  `<REQUIREMENTS_ROOT>` (see `Deprecation Phase` for the exact",
+    "  edits)",
+    "- The affected category `README.md` / `index.md` row(s) to reflect",
+    "  the new status",
+    "- `req:write` follow-up GitHub issues \u2014 one per referencing",
+    "  requirement document surfaced by the back-reference sweep",
+    "- A summary comment on the `req:deprecate` issue",
+    "",
+    "**Do NOT write to** in the deprecation phase:",
+    "",
+    "- Any section of the target document not named in the Deprecation",
+    "  Phase edits list (do not rewrite Description, Acceptance",
+    "  Criteria, Open Items, or any other section)",
+    "- The templates at `<TEMPLATES_ROOT>`",
+    "- Review reports under `<REVIEW_REPORTS_ROOT>` (the review phase",
+    "  owns those)",
+    "",
     "---",
     "",
     "## Iterating on Reviews",
@@ -11079,16 +11332,204 @@ var requirementsReviewerSubAgent = {
     "",
     "---",
     "",
+    "## Deprecation Phase",
+    "",
+    "The deprecation phase is how requirement documents transition to",
+    "`Deprecated` or `Superseded`. None of the other requirements",
+    "bundles owns this transition \u2014 the writer only ships new documents,",
+    "and the reviewer's `req:review` mode can *detect* stale status but",
+    "has no mechanism to fix it. This phase fills that gap.",
+    "",
+    "Deprecation never deletes files. It leaves the document in place",
+    "with a clearly updated `Status`, a Deprecation reason, a",
+    "`Superseded-by` link when applicable, and a matching index row so",
+    "readers who arrive via old links can follow the trail forward.",
+    "",
+    "### Input",
+    "",
+    "One `req:deprecate` issue with the following body sections:",
+    "",
+    "- **Targets** \u2014 one or more requirement IDs or paths to deprecate",
+    "  (for example, `ADR-007-auth-provider.md` or",
+    "  `docs/requirements/architecture/ADR-007-auth-provider.md`).",
+    "- **Transition** \u2014 per target, either `Deprecated` (no successor)",
+    "  or `Superseded-by: <path>` (where `<path>` is the relative path",
+    "  or requirement ID of the replacement document). When the",
+    "  transition is `Superseded`, the replacement must already exist",
+    "  under `<REQUIREMENTS_ROOT>` \u2014 verify before proceeding.",
+    "- **Reason** \u2014 a one-paragraph rationale that becomes the",
+    "  Deprecation reason recorded on the target document.",
+    "- **Confirmation** (optional) \u2014 the body may include",
+    "  `Pre-approved: yes` to skip the human pause below. If omitted,",
+    "  pause and request confirmation.",
+    "",
+    "If the issue is missing any of the first three fields, comment on",
+    "the issue requesting the missing input, apply",
+    "`status:needs-attention`, and stop. Do not guess.",
+    "",
+    "### Required Human Confirmation",
+    "",
+    "Deprecation is irreversible in practice. Before writing any",
+    "status change, comment on the `req:deprecate` issue with:",
+    "",
+    "- The target paths that will be edited",
+    "- The exact `Status` value each will receive",
+    "- Any `Superseded-by` links that will be written",
+    "- The list of back-references that will receive `req:write`",
+    "  follow-ups",
+    "",
+    "Then pause and wait for the issue author (or a maintainer) to reply",
+    "with an affirmative confirmation (e.g., `approved`, `confirmed`, or",
+    "`yes`). If the issue body already contains `Pre-approved: yes`, the",
+    "pause is skipped \u2014 record that fact in the final summary comment.",
+    "The human decision is what authorizes the edit; never self-approve.",
+    "",
+    "### Edits Performed",
+    "",
+    "For each target document, make the following **narrow** edits in a",
+    "single commit per target (or one commit for the full batch when the",
+    "targets are tightly related). All other edits \u2014 description",
+    "rewrites, acceptance-criteria tweaks, introduction of new sections \u2014",
+    "are out of scope and flow through `req:write` follow-ups.",
+    "",
+    "1. **Frontmatter `Status`.** Set the YAML frontmatter `Status`",
+    "   field to `Deprecated` or `Superseded`.",
+    "2. **Metadata table `Status` row.** Update the `Status` row inside",
+    "   the Metadata table at the top of the document to match.",
+    "3. **`## Revision History`.** Append a new row/entry recording the",
+    "   date, the new status, the deprecating agent (this reviewer), and",
+    "   the issue number. Use the project's existing Revision History",
+    "   format \u2014 do not introduce a new format.",
+    "4. **`## Traceability` Superseded-by line.** When the transition is",
+    "   `Superseded`, insert (or update) a",
+    "   `- **Superseded-by:** [<ID>](<relative-path>.md)` line under the",
+    "   existing Traceability section. When the transition is plain",
+    "   `Deprecated`, no Traceability edit is required.",
+    "5. **Deprecation reason.** Add a `- **Deprecation reason:** <one",
+    "   paragraph>` line directly below the Superseded-by line (or at",
+    "   the top of the Traceability section when no successor exists).",
+    "   The paragraph must be the reason from the issue, verbatim.",
+    "6. **Category index row.** Open the category directory's",
+    "   `README.md` (or `index.md`) and update the target's row:",
+    "   change its `Status` column to the new status, and, when",
+    "   applicable, append `\u2014 superseded by [<ID>](<relative-path>.md)`",
+    "   to the title cell. Do not delete the row.",
+    "",
+    "Do **not** edit any section or field on the target document that is",
+    "not named in the six steps above. Do not retitle, do not rewrite",
+    "Description, do not change acceptance criteria, do not touch Open",
+    "Items. Every other edit belongs to the `requirements-writer`.",
+    "",
+    "### Back-Reference Sweep",
+    "",
+    "After the target document edits land, sweep `<REQUIREMENTS_ROOT>`",
+    "for every markdown link or inline reference to the deprecated",
+    "document. Use the same resolution discipline as Check 4: resolve",
+    "each link against the filesystem, do not eyeball. For every",
+    "document that still references the deprecated target:",
+    "",
+    "- File one `req:write` follow-up issue per referencing document",
+    "  (not one per link \u2014 a single document may carry multiple",
+    "  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 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`, 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.",
+    "",
+    "If the sweep surfaces references from non-requirement documents",
+    "(for example, research notes, meeting insights, or capability",
+    "models), do **not** open `req:write` for them. Instead, list them",
+    "in the summary comment on the `req:deprecate` issue so a human can",
+    "triage them into the appropriate bundle. This keeps the bundle",
+    "boundary clean.",
+    "",
+    "### Output",
+    "",
+    "- One or more edited requirement documents under",
+    "  `<REQUIREMENTS_ROOT>` (narrow edits per the list above).",
+    "- An updated category `README.md` / `index.md` per affected",
+    "  category.",
+    "- One `req:write` follow-up issue per referencing requirement",
+    "  document.",
+    "- A summary comment on the `req:deprecate` issue recording the",
+    "  edits made, the follow-ups opened, any non-requirement",
+    "  references surfaced, and whether the human confirmation was",
+    "  received interactively or via a `Pre-approved: yes` marker.",
+    "- A single commit (or tightly-scoped batch) per target, with a",
+    "  `chore(requirements): deprecate <ID>` or",
+    "  `chore(requirements): supersede <ID> by <new-ID>` message.",
+    "",
+    "### Filesystem Durability",
+    "",
+    "As with the review phase, write edits to disk **before** opening",
+    "follow-up issues. The edited documents and the updated index are",
+    "the durable record; the `req:write` follow-ups are pointers into",
+    "that state. If the session is interrupted after follow-ups are",
+    "filed but before the commit lands, subsequent runs cannot",
+    "reconstruct the rewrite context.",
+    "",
+    "Sequence:",
+    "",
+    "1. Read the `req:deprecate` issue and verify required inputs.",
+    "2. Verify every successor document referenced in `Superseded-by`",
+    "   exists on disk.",
+    "3. Pause for human confirmation (unless `Pre-approved: yes` is in",
+    "   the body).",
+    "4. Apply the six narrow edits to each target document.",
+    "5. Update the category index row(s).",
+    "6. Commit the deprecation changes.",
+    "7. Run the back-reference sweep.",
+    "8. File one `req:write` follow-up per referencing requirement",
+    "   document.",
+    "9. Comment on the `req:deprecate` issue with the summary.",
+    "",
+    "---",
+    "",
     "## Working Rules",
     "",
-    "- **One review per session.** Stop after the report is written,",
-    "  follow-up issues are filed, and the summary comment is posted.",
-    "- **Audit only.** Never edit requirement documents, category",
-    "  indexes, or templates. Findings flow through follow-up issues.",
-    "- **Resolve, do not eyeball.** Cross-reference findings only count",
-    "  when the target path is verified missing on disk.",
-    "- **Cite every finding.** Every entry in the report must cite the",
-    "  file path and the numbered check that produced it.",
+    "- **One phase per session.** In `req:review`, stop after the report",
+    "  is written, follow-up issues are filed, and the summary comment is",
+    "  posted. In `req:deprecate`, stop after the edits commit, the",
+    "  back-reference sweep runs, follow-ups are filed, and the summary",
+    "  comment is posted.",
+    "- **Audit-only in `req:review`.** Never edit requirement documents,",
+    "  category indexes, or templates from the review phase. Findings flow",
+    "  through follow-up issues.",
+    "- **Narrow-write in `req:deprecate`.** Only the six edits listed in",
+    "  the Deprecation Phase section are allowed. Every other edit flows",
+    "  through `req:write` follow-ups.",
+    "- **Deprecation requires human confirmation.** Never self-approve a",
+    "  status transition. Either pause on the issue and wait for an",
+    "  explicit reply, or verify that the body carries",
+    "  `Pre-approved: yes` before editing.",
+    "- **Resolve, do not eyeball.** Cross-reference findings and",
+    "  back-reference sweeps only count when the target path is verified",
+    "  on disk.",
+    "- **Cite every finding.** Every entry in the review report must cite",
+    "  the file path and the numbered check that produced it. Every",
+    "  deprecation follow-up must cite the referencing document path and",
+    "  the line(s) that mention the deprecated ID.",
     "- **Do not invent traceability rules.** Use the defaults documented",
     "  above unless the project's `docs/project-context.md` declares a",
     "  different traceability shape.",
@@ -11184,40 +11625,189 @@ var reviewRequirementsSkill = {
     "- A summary comment on the originating `req:review` issue"
   ].join("\n")
 };
+var deprecateRequirementSkill = {
+  name: "deprecate-requirement",
+  description: "Transition one or more requirement documents to `Deprecated` or `Superseded`. Creates a `req:deprecate` issue and dispatches the requirements-reviewer agent's deprecation phase, which edits the target document's Status, Revision History, Superseded-by traceability link, and category index row, then files `req:write` follow-ups for every back-reference so the requirements-writer can rewrite them. The deprecation phase pauses for explicit human confirmation before editing (unless the issue body pre-approves the change).",
+  disableModelInvocation: true,
+  userInvocable: true,
+  context: "fork",
+  agent: "requirements-reviewer",
+  platforms: { cursor: { exclude: true } },
+  instructions: [
+    "# Deprecate Requirement",
+    "",
+    "Transition one or more requirement documents to `Deprecated` or",
+    "`Superseded`. Creates a `req:deprecate` issue and dispatches the",
+    "`requirements-reviewer` agent's deprecation phase. The agent pauses",
+    "for explicit human confirmation before writing any status change.",
+    "",
+    "## When to use",
+    "",
+    "- An ADR is superseded by a newer decision and the old decision",
+    "  should no longer be referenced.",
+    "- A functional requirement has been removed from the roadmap and",
+    "  should carry `Status: Deprecated` so downstream documents stop",
+    "  linking to it as if it were active.",
+    "- A reviewer run (via `/review-requirements`) surfaced a stale",
+    "  `Accepted` status that should transition to `Deprecated` or",
+    "  `Superseded`.",
+    "",
+    "## Usage",
+    "",
+    "/deprecate-requirement <target> [--superseded-by <path>]",
+    "",
+    "Where `<target>` is either a requirement ID (e.g. `ADR-007`) or a",
+    "path relative to `<REQUIREMENTS_ROOT>` (e.g.",
+    "`architecture/ADR-007-auth-provider.md`). Pass",
+    "`--superseded-by <path>` to record a replacement document; omit it",
+    "for a plain deprecation with no successor.",
+    "",
+    "Multiple targets may be passed by repeating the skill invocation or",
+    "by editing the issue body before the agent runs.",
+    "",
+    "## Required issue body fields",
+    "",
+    "The `req:deprecate` issue body must include:",
+    "",
+    "- **Targets** \u2014 the requirement IDs or paths to deprecate",
+    "- **Transition** \u2014 `Deprecated` or `Superseded-by: <path>` per",
+    "  target (when `Superseded-by` is given, the replacement document",
+    "  must already exist on disk)",
+    "- **Reason** \u2014 a one-paragraph rationale that becomes the",
+    "  Deprecation reason recorded on the target document",
+    "- **Pre-approved: yes** *(optional)* \u2014 include this line to skip",
+    "  the interactive human-confirmation pause. Omit it to force the",
+    "  agent to comment on the issue and wait for an affirmative",
+    "  reply before editing.",
+    "",
+    "Issues that are missing any of the first three fields are flagged",
+    "`status:needs-attention` and the agent stops without editing",
+    "anything.",
+    "",
+    "## Steps",
+    "",
+    "1. Create a `req:deprecate` issue with `type:requirement`,",
+    "   `priority:medium`, and `status:ready`. Body must include the",
+    "   Targets, Transition, and Reason sections above (optionally",
+    "   `Pre-approved: yes`).",
+    "2. Execute the deprecation phase of the requirements-reviewer",
+    "   agent.",
+    "3. The agent verifies inputs, pauses for human confirmation (or",
+    "   skips the pause when `Pre-approved: yes` is set), edits each",
+    "   target document's `Status`, Revision History, Superseded-by,",
+    "   and Deprecation reason, updates the matching category index",
+    "   row, commits the changes, sweeps `<REQUIREMENTS_ROOT>` for",
+    "   inbound references, files one `req:write` follow-up per",
+    "   referencing document, and comments on the `req:deprecate`",
+    "   issue with the summary.",
+    "",
+    "## Output",
+    "",
+    "- Narrow edits to each target requirement document (Status,",
+    "  Metadata row, Revision History, Traceability Superseded-by,",
+    "  Deprecation reason)",
+    "- Updated category index row(s)",
+    "- One `req:write` follow-up issue per requirement document that",
+    "  still references the deprecated target, so the",
+    "  `requirements-writer` can rewrite those references",
+    "- A summary comment on the originating `req:deprecate` issue",
+    "",
+    "## What this skill does NOT do",
+    "",
+    "- It does not delete files. Deprecated documents stay on disk with",
+    "  updated status so readers following old links can follow the",
+    "  trail forward.",
+    "- It does not rewrite the body of the target document beyond the",
+    "  narrow fields listed above. Description, acceptance criteria,",
+    "  open items, and other sections are left unchanged. If the",
+    "  deprecation implies a rewrite of other sections, the issue",
+    "  author should open a separate `req:write` issue for the writer.",
+    "- It does not rewrite references in the referencing documents.",
+    "  That work is handed off to the `requirements-writer` through",
+    "  the `req:write` follow-ups."
+  ].join("\n")
+};
 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) for structural compliance, categorization, traceability, cross-reference integrity, sequence integrity, content quality, registry sync, decision-authority compliance, tier classification, and cross-referencing conventions. 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 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.",
   appliesWhen: () => true,
   rules: [
     {
       name: "requirements-reviewer-workflow",
-      description: "Describes the requirements-reviewer pipeline, the req:review phase label, the four review scopes, the soft dependency on the requirements-writer bundle's templates, and the boundary with the writer and analyst bundles.",
+      description: "Describes the requirements-reviewer pipeline, the req:review and req:deprecate phase labels, the four review scopes, the deprecation-phase contract, the soft dependency on the requirements-writer bundle's templates, and the boundary with the writer and analyst bundles.",
       scope: AGENT_RULE_SCOPE.ALWAYS,
       content: [
         "# Requirements Reviewer Workflow",
         "",
-        "Use `/review-requirements <scope>` to audit existing requirement",
-        "documents. The reviewer runs in a single phase tracked by a",
-        "GitHub issue labeled `req:review`. Issues also carry",
-        "`type:requirement` (declared by the upstream",
-        "`requirements-analyst` bundle).",
-        "",
-        "The pipeline produces **review reports and follow-up issues** \u2014",
-        "it never edits requirement documents, capability models, or",
-        "research notes. Authoring is the responsibility of the",
-        "`requirements-writer` (requirement docs) and `bcm-writer`",
-        "(capability models) bundles; gap discovery is the responsibility",
-        "of the `requirements-analyst` bundle. The reviewer never opens",
-        "`req:scan`, `req:draft`, `req:trace`, `req:write`, or `bcm:*`",
-        "issues directly \u2014 instead it files follow-up issues with the",
-        "appropriate phase label (`req:write`, `req:trace`, or",
-        "`req:scan`) for the downstream agent to pick up.",
+        "The requirements-reviewer agent runs in one of two phases per",
+        "session, each tracked by its own GitHub issue label. Issues in",
+        "both phases also carry `type:requirement` (declared by the",
+        "upstream `requirements-analyst` bundle).",
+        "",
+        "| Phase | Skill | Label | Writes requirement docs? |",
+        "|-------|-------|-------|--------------------------|",
+        "| Review | `/review-requirements <scope>` | `req:review` | No \u2014 audit only |",
+        "| Deprecate | `/deprecate-requirement <target>` | `req:deprecate` | Narrow writes (Status, Revision History, Superseded-by, index row) |",
         "",
-        "Four review scopes are supported: `full` (every document),",
+        "## Review phase",
+        "",
+        "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",
         "checks across the documents in scope).",
         "",
+        "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.",
+        "",
+        "For audits covering more than 10 documents, the reviewer writes",
+        "a read-only Python verification script alongside the report and",
+        "uses its output as the basis for findings \u2014 manual review of",
+        "large document sets always misses broken links.",
+        "",
+        "## Deprecation phase",
+        "",
+        "Use `/deprecate-requirement <target> [--superseded-by <path>]`",
+        "to transition one or more requirement documents to `Deprecated`",
+        "or `Superseded`. The deprecation phase is the only path by",
+        "which this agent mutates requirement documents, and it is",
+        "narrowly scoped to:",
+        "",
+        "- The frontmatter `Status` field and the Metadata table",
+        "  `Status` row",
+        "- A new entry in the target document's `## Revision History`",
+        "- A `Superseded-by` line in the target's `## Traceability`",
+        "  section (when applicable) plus a Deprecation reason line",
+        "- The matching row in the category `README.md` / `index.md`",
+        "",
+        "The agent pauses for explicit human confirmation on the",
+        "`req:deprecate` issue before editing \u2014 deprecation is",
+        "irreversible in practice. Issue authors can skip the pause by",
+        "adding `Pre-approved: yes` to the issue body. After the edits",
+        "commit, the agent sweeps `<REQUIREMENTS_ROOT>` for inbound",
+        "references and files one `req:write` follow-up per referencing",
+        "requirement document so the `requirements-writer` can rewrite",
+        "those references. Documents are never deleted; the deprecated",
+        "file stays on disk with updated status.",
+        "",
+        "The deprecation phase never authors new requirement documents,",
+        "never rewrites the body of a target document beyond the narrow",
+        "fields listed above, and never rewrites references in the",
+        "referencing documents \u2014 that work is handed off to the",
+        "`requirements-writer`.",
+        "",
+        "## Cross-bundle boundaries",
+        "",
+        "Authoring remains the responsibility of the `requirements-writer`",
+        "(requirement docs) and `bcm-writer` (capability models) bundles.",
+        "Gap discovery is the responsibility of the `requirements-analyst`",
+        "bundle. The reviewer never opens `req:scan`, `req:draft`,",
+        "`req:trace`, `req:review`, or `bcm:*` issues \u2014 only `req:write`",
+        "follow-ups from either phase.",
+        "",
         "**Soft dependency on the `requirements-writer` bundle.** The",
         "reviewer reads category templates from",
         `\`${REQUIREMENTS_WRITER_PATHS.templatesRoot}\`,`,
@@ -11225,14 +11815,10 @@ var requirementsReviewerBundle = {
         "that disable the writer bundle but keep the reviewer must",
         "supply equivalent templates at the same path.",
         "",
-        "For audits covering more than 10 documents, the reviewer writes",
-        "a read-only Python verification script alongside the report and",
-        "uses its output as the basis for findings \u2014 manual review of",
-        "large document sets always misses broken links.",
-        "",
         "See the `requirements-reviewer` agent definition for full",
         "workflow details, configurable paths, the 11-check catalog, the",
-        "severity ladder, and reporting format."
+        "severity ladder, the deprecation-phase edit contract, and the",
+        "back-reference sweep rules."
       ].join("\n"),
       platforms: {
         cursor: { exclude: true }
@@ -11240,13 +11826,18 @@ var requirementsReviewerBundle = {
       tags: ["workflow"]
     }
   ],
-  skills: [reviewRequirementsSkill],
+  skills: [reviewRequirementsSkill, deprecateRequirementSkill],
   subAgents: [requirementsReviewerSubAgent],
   labels: [
     {
       name: "req:review",
       color: "FBCA04",
       description: "Phase: audit existing requirement documents using the requirements-reviewer skill"
+    },
+    {
+      name: "req:deprecate",
+      color: "D93F0B",
+      description: "Phase: transition existing requirement documents to Deprecated or Superseded using the requirements-reviewer skill"
     }
   ]
 };