@codedrifters/configulator 0.0.234 → 0.0.235

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",
@@ -10992,7 +11107,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,6 +11130,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",
@@ -11190,15 +11355,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.",