olympus-ai 4.5.13 → 4.5.14

package/resources/rules/construction/bolt-planning.md

@@ -1,153 +1,153 @@
-# Bolt Planning - Decomposing Units into Bolts
-
-## Overview
-
-The Bolt Planning stage runs after unit design is complete. The BoltPlanner decomposes each construction unit into one or more bolts — scoped execution packages that a code-generation agent can implement in a focused session.
-
-Bolts are the smallest execution loop in the AIDLC construction pipeline. Each bolt has a clear scope, acceptance criteria, and target files. Together, all bolts for a unit must provide >=95% story coverage.
-
----
-
-## Bolt Spec Artifact
-
-Each bolt is described by a spec file written during this stage.
-
-**Path**: `{workflowId}/construction/{parent_unit_id}/bolts/BOLT-NNN-slug/spec.md`
-
-Example: `{workflowId}/construction/UNIT-001-foundation/bolts/BOLT-001-data-model/spec.md`
-
-### Spec Template
-
-The canonical bolt spec template is defined at:
-
-**Template file**: `resources/templates/construction/bolt-spec-template.md`
-
-When creating bolt specs, agents MUST read this template file and follow its structure exactly. The template defines all required frontmatter fields (including runtime state fields), all required body sections, status values, and stage status symbols.
-
-> **CRITICAL**: Do NOT invent your own spec format. Read and follow the template.
-
-### Required Body Sections
-
-Every bolt spec must contain ALL of the following sections (10 total):
-
-1. **Scope** — What this bolt implements
-2. **Stories Included** — Checkbox list of stories with priorities (`- [ ] **S-001**: title -- Priority: Must`)
-3. **Acceptance Criteria** — Checkbox list of verifiable criteria (`- [ ] criterion`)
-4. **Expected Outputs** — Concrete deliverables this bolt produces
-5. **Target Files** — Files to create or modify (backtick-wrapped paths)
-6. **Stages** — 4-stage execution checklist (elaboration, code_generation, build_and_test, review)
-7. **Dependencies** — Three subsections: Bolt Dependencies (within unit), Unit Dependencies (cross-unit), Enables (bolts waiting on this)
-8. **Success Criteria** — Completion checklist (all stories implemented, tests passing, code reviewed)
-9. **Traceability** — Requirement and story ID references
-
----
-
-## Naming Convention
-
-Bolt IDs use global sequential numbering across ALL units — not per-unit numbering.
-
-Format: `BOLT-NNN-slug`
-
-- `NNN` is zero-padded to three digits: `001`, `002`, `003`, ...
-- `slug` is a short kebab-case description of the bolt's scope
-- Numbers do NOT reset when moving to a new unit
-
-Examples:
-- `BOLT-001-data-model`
-- `BOLT-002-repository-layer`
-- `BOLT-015-admin-dashboard`
-
----
-
-## Bolt Count Guardrails
-
-| Scope | Limit |
-|-------|-------|
-| Max bolts per unit | 8 |
-| Max bolts total (all units) | 50 |
-
-If a unit's scope exceeds 8 bolts, it must be re-scoped or split into multiple units before bolt planning can proceed.
-
----
-
-## Traceability Rules
-
-Every bolt MUST satisfy the following traceability requirements:
-
-- **Requirement reference is mandatory**: Every bolt must reference at least one requirement ID in its `requirements` frontmatter field and its `## Traceability` section. Requirement IDs come from `requirements.md` (e.g., `FR-1`, `FR-3`). A bolt with no requirement reference is invalid and must be revised before execution.
-- **Story reference is recommended but optional**: Not all bolts map directly to user stories (infrastructure, scaffolding, and cross-cutting bolts often do not). Include story IDs when they exist; leave the `stories` field as an empty array `[]` when none apply.
-- **Planner responsibility**: The planner agent is responsible for reading the inception `requirements.md` and `stories.md` artifacts and populating these fields for every bolt it generates. Do not leave them as placeholder values.
-- **Coverage check at plan completion**: After all bolts for a unit are planned, a coverage check verifies that every requirement with `must` priority in `requirements.md` is addressed by at least one bolt. Unaddressed `must` requirements must be resolved before bolt execution begins (either by revising an existing bolt's scope or adding a new bolt).
-
----
-
-## Documentation Impact Assessment
-
-The planner MUST assess `docs_impact` for every bolt based on what the bolt changes. Apply these rules:
-
-- **User-facing features** (new UI, new CLI commands, new API endpoints): include `user-guide`
-- **Configuration changes** (new env vars, new settings, new options): include `config-reference`
-- **CLI changes** (new commands, new flags, changed usage): include `cli-reference`
-- **Breaking changes** (removed features, changed APIs, migration needed): include `migration-guide`
-- **README-worthy changes** (new capabilities, changed project setup): include `readme`
-- **Architectural changes** (new services, new data flows, new components): include `architecture`
-- **Complex internal logic** (non-obvious algorithms, intricate state machines): include `code-comments`
-- **Internal-only changes** (refactoring, test fixes, minor tweaks with no user impact): use `none`
-
-A bolt may have multiple `docs_impact` values (e.g., `["user-guide", "config-reference"]`). Only use `none` when the bolt has zero documentation impact.
-
----
-
-## Coverage Validation
-
-After bolt decomposition, the BoltPlanner validates that the bolt set covers all unit stories and requirements.
-
-| Coverage | Result |
-|----------|--------|
-| >= 95% | Pass — proceed to execution |
-| 80-94% | Warning — user must explicitly acknowledge the gap before proceeding |
-| < 80% | Hard block — bolt planning rejected, must revise decomposition |
-
-Story coverage is measured as: (stories with at least one covering bolt) / (total unit stories).
-
-Requirement coverage (must-priority only): all `must`-priority requirements in `requirements.md` must be referenced by at least one bolt. Any uncovered `must` requirement is treated as a hard block regardless of story coverage score.
-
----
-
-## Bolt Lifecycle States
-
-Each bolt progresses through the following states:
-
-| State | Meaning |
-|-------|---------|
-| `planned` | Spec written, not yet started |
-| `in_progress` | Code generation agent is actively working |
-| `built` | Code generation complete, pending review |
-| `in_review` | BoltReviewer is evaluating the bolt |
-| `done` | Reviewed and accepted |
-| `failed` | Review rejected; requires re-scope or split |
-
----
-
-## Express Bolt Eligibility
-
-A bolt is eligible for express mode (skips the elaboration stage) if either condition is met:
-
-- `depth_target` <= 4 (low-complexity bolt)
-- Parent unit's pathway is `bugfix`
-
-Express bolts go directly from `planned` to code generation. The `express_mode: true` flag must be set in the bolt spec frontmatter.
-
----
-
-## Checkpoint Fields
-
-The workflow checkpoint tracks bolt state under the unit entry:
-
-| Field | Description |
-|-------|-------------|
-| `construction_bolts` | Map of bolt IDs to `ConstructionBoltProgress` objects |
-| `active_bolt_id` | ID of the bolt currently in execution (or `null`) |
-| `active_bolt_stage` | Current execution stage of the active bolt |
-
-The `active_bolt_stage` values correspond to execution stages: `elaboration`, `code_generation`, `build_and_test`, `review`.
+# Bolt Planning - Decomposing Units into Bolts
+
+## Overview
+
+The Bolt Planning stage runs after unit design is complete. The BoltPlanner decomposes each construction unit into one or more bolts — scoped execution packages that a code-generation agent can implement in a focused session.
+
+Bolts are the smallest execution loop in the AIDLC construction pipeline. Each bolt has a clear scope, acceptance criteria, and target files. Together, all bolts for a unit must provide >=95% story coverage.
+
+---
+
+## Bolt Spec Artifact
+
+Each bolt is described by a spec file written during this stage.
+
+**Path**: `{workflowId}/construction/{parent_unit_id}/bolts/BOLT-NNN-slug/spec.md`
+
+Example: `{workflowId}/construction/UNIT-001-foundation/bolts/BOLT-001-data-model/spec.md`
+
+### Spec Template
+
+The canonical bolt spec template is defined at:
+
+**Template file**: `resources/templates/construction/bolt-spec-template.md`
+
+When creating bolt specs, agents MUST read this template file and follow its structure exactly. The template defines all required frontmatter fields (including runtime state fields), all required body sections, status values, and stage status symbols.
+
+> **CRITICAL**: Do NOT invent your own spec format. Read and follow the template.
+
+### Required Body Sections
+
+Every bolt spec must contain ALL of the following sections (10 total):
+
+1. **Scope** — What this bolt implements
+2. **Stories Included** — Checkbox list of stories with priorities (`- [ ] **S-001**: title -- Priority: Must`)
+3. **Acceptance Criteria** — Checkbox list of verifiable criteria (`- [ ] criterion`)
+4. **Expected Outputs** — Concrete deliverables this bolt produces
+5. **Target Files** — Files to create or modify (backtick-wrapped paths)
+6. **Stages** — 4-stage execution checklist (elaboration, code_generation, build_and_test, review)
+7. **Dependencies** — Three subsections: Bolt Dependencies (within unit), Unit Dependencies (cross-unit), Enables (bolts waiting on this)
+8. **Success Criteria** — Completion checklist (all stories implemented, tests passing, code reviewed)
+9. **Traceability** — Requirement and story ID references
+
+---
+
+## Naming Convention
+
+Bolt IDs use global sequential numbering across ALL units — not per-unit numbering.
+
+Format: `BOLT-NNN-slug`
+
+- `NNN` is zero-padded to three digits: `001`, `002`, `003`, ...
+- `slug` is a short kebab-case description of the bolt's scope
+- Numbers do NOT reset when moving to a new unit
+
+Examples:
+- `BOLT-001-data-model`
+- `BOLT-002-repository-layer`
+- `BOLT-015-admin-dashboard`
+
+---
+
+## Bolt Count Guardrails
+
+| Scope | Limit |
+|-------|-------|
+| Max bolts per unit | 8 |
+| Max bolts total (all units) | 50 |
+
+If a unit's scope exceeds 8 bolts, it must be re-scoped or split into multiple units before bolt planning can proceed.
+
+---
+
+## Traceability Rules
+
+Every bolt MUST satisfy the following traceability requirements:
+
+- **Requirement reference is mandatory**: Every bolt must reference at least one requirement ID in its `requirements` frontmatter field and its `## Traceability` section. Requirement IDs come from `requirements.md` (e.g., `FR-1`, `FR-3`). A bolt with no requirement reference is invalid and must be revised before execution.
+- **Story reference is recommended but optional**: Not all bolts map directly to user stories (infrastructure, scaffolding, and cross-cutting bolts often do not). Include story IDs when they exist; leave the `stories` field as an empty array `[]` when none apply.
+- **Planner responsibility**: The planner agent is responsible for reading the inception `requirements.md` and `stories.md` artifacts and populating these fields for every bolt it generates. Do not leave them as placeholder values.
+- **Coverage check at plan completion**: After all bolts for a unit are planned, a coverage check verifies that every requirement with `must` priority in `requirements.md` is addressed by at least one bolt. Unaddressed `must` requirements must be resolved before bolt execution begins (either by revising an existing bolt's scope or adding a new bolt).
+
+---
+
+## Documentation Impact Assessment
+
+The planner MUST assess `docs_impact` for every bolt based on what the bolt changes. Apply these rules:
+
+- **User-facing features** (new UI, new CLI commands, new API endpoints): include `user-guide`
+- **Configuration changes** (new env vars, new settings, new options): include `config-reference`
+- **CLI changes** (new commands, new flags, changed usage): include `cli-reference`
+- **Breaking changes** (removed features, changed APIs, migration needed): include `migration-guide`
+- **README-worthy changes** (new capabilities, changed project setup): include `readme`
+- **Architectural changes** (new services, new data flows, new components): include `architecture`
+- **Complex internal logic** (non-obvious algorithms, intricate state machines): include `code-comments`
+- **Internal-only changes** (refactoring, test fixes, minor tweaks with no user impact): use `none`
+
+A bolt may have multiple `docs_impact` values (e.g., `["user-guide", "config-reference"]`). Only use `none` when the bolt has zero documentation impact.
+
+---
+
+## Coverage Validation
+
+After bolt decomposition, the BoltPlanner validates that the bolt set covers all unit stories and requirements.
+
+| Coverage | Result |
+|----------|--------|
+| >= 95% | Pass — proceed to execution |
+| 80-94% | Warning — user must explicitly acknowledge the gap before proceeding |
+| < 80% | Hard block — bolt planning rejected, must revise decomposition |
+
+Story coverage is measured as: (stories with at least one covering bolt) / (total unit stories).
+
+Requirement coverage (must-priority only): all `must`-priority requirements in `requirements.md` must be referenced by at least one bolt. Any uncovered `must` requirement is treated as a hard block regardless of story coverage score.
+
+---
+
+## Bolt Lifecycle States
+
+Each bolt progresses through the following states:
+
+| State | Meaning |
+|-------|---------|
+| `planned` | Spec written, not yet started |
+| `in_progress` | Code generation agent is actively working |
+| `built` | Code generation complete, pending review |
+| `in_review` | BoltReviewer is evaluating the bolt |
+| `done` | Reviewed and accepted |
+| `failed` | Review rejected; requires re-scope or split |
+
+---
+
+## Express Bolt Eligibility
+
+A bolt is eligible for express mode (skips the elaboration stage) if either condition is met:
+
+- `depth_target` <= 4 (low-complexity bolt)
+- Parent unit's pathway is `bugfix`
+
+Express bolts go directly from `planned` to code generation. The `express_mode: true` flag must be set in the bolt spec frontmatter.
+
+---
+
+## Checkpoint Fields
+
+The workflow checkpoint tracks bolt state under the unit entry:
+
+| Field | Description |
+|-------|-------------|
+| `construction_bolts` | Map of bolt IDs to `ConstructionBoltProgress` objects |
+| `active_bolt_id` | ID of the bolt currently in execution (or `null`) |
+| `active_bolt_stage` | Current execution stage of the active bolt |
+
+The `active_bolt_stage` values correspond to execution stages: `elaboration`, `code_generation`, `build_and_test`, `review`.

package/resources/rules/construction/bolt-review.md

@@ -1,143 +1,143 @@
-# Bolt Review - Mandatory Quality Gate
-
-## Overview
-
-The Bolt Review stage is a mandatory quality gate that runs after every bolt's code generation is complete. The BoltReviewer evaluates whether the generated code meets the bolt's acceptance criteria and aligns with the approved spec.
-
-Review is performed by the `momus` agent via a review callback. BoltReviewer returns structured decision objects — it does not interact with users directly. User interaction (acknowledgment prompts, escalation notices) is handled by the orchestrator based on the decision returned.
-
----
-
-## Two-Tier Alignment Model
-
-The BoltReviewer scores each bolt on a 0-100% alignment scale and maps the score to one of three tiers:
-
-| Score | Tier | Action |
-|-------|------|--------|
-| >= 70% | Auto-approve | Bolt accepted automatically; no user interaction required |
-| 50-69% | Advisory | Bolt proceeds with mandatory user acknowledgment |
-| < 50% | Hard block | Bolt rejected; must be re-scoped or split before retrying |
-
-### Auto-Approve (>= 70%)
-
-The bolt is accepted. The orchestrator transitions the bolt state from `in_review` to `done` without prompting the user.
-
-### Advisory (50-69%)
-
-The orchestrator presents the review findings to the user and requires explicit acknowledgment before the bolt proceeds. The user must confirm they understand the concerns and accept the bolt as-is.
-
-Acknowledgment is recorded in the bolt's `ConstructionBoltProgress` entry:
-- `acknowledged_by`: identifier of the user who acknowledged
-- `acknowledged_at`: ISO 8601 timestamp of acknowledgment
-
-### Hard Block (< 50%)
-
-The bolt is rejected. The orchestrator transitions the bolt state to `failed`. The user must re-scope the bolt (narrow scope, reduce complexity) or split it into smaller bolts before code generation can be retried.
-
-Hard blocks are never overridden, regardless of trust level.
-
----
-
-## Trust-Based Auto-Approval
-
-When the trust level for the workflow is >= 2, the advisory tier (50-69%) is upgraded to auto-approve. This means:
-
-- Trust level 0-1: advisory tier requires user acknowledgment
-- Trust level >= 2: advisory tier auto-approves (treated as >= 70%)
-- Hard block (< 50%): **never overridden** by trust level
-
-The trust level is stored in the workflow checkpoint and reflects the user's established confidence in the AI agent for this workflow.
-
----
-
-## Escalation
-
-If a bolt accumulates 2 consecutive review failures (2 reviews both scoring < 50%), an escalation event is triggered.
-
-The escalation event includes:
-- Bolt ID and title
-- Failure count
-- Recommended actions:
-  - **Re-scope**: Narrow the bolt's scope to reduce complexity
-  - **Split**: Divide the bolt into two or more smaller bolts with tighter acceptance criteria
-
-The orchestrator surfaces the escalation to the user and halts further attempts on that bolt until the user chooses an action.
-
----
-
-## Review Artifact
-
-After each review, BoltReviewer writes a structured artifact:
-
-**Path**: `{workflowId}/construction/{parent_unit_id}/bolts/{boltId}/review.md`
-
-Example: `{workflowId}/construction/UNIT-001-foundation/bolts/BOLT-001-data-model/review.md`
-
-### Required Sections
-
-**Score** — Numeric alignment score (0-100%) with a brief rationale.
-
-**Decision** — One of: `approved`, `advisory`, `rejected`.
-
-**Feedback** — Specific, actionable observations about the generated code relative to the bolt's acceptance criteria. Each item should reference a specific criterion or target file.
-
-**Concerns** — List of issues that contributed to score reduction. May be empty for approved bolts.
-
-**Recommended Actions** _(escalation only)_ — Present only when 2 consecutive failures have occurred. Lists concrete steps the user should take (re-scope or split).
-
----
-
-## Acknowledgment Fields
-
-When a bolt is accepted at the advisory tier, the orchestrator records acknowledgment on the bolt's progress entry in the checkpoint:
-
-```json
-{
-  "acknowledged_by": "user",
-  "acknowledged_at": "2026-01-15T10:30:00Z"
-}
-```
-
-These fields are stored on the `ConstructionBoltProgress` object alongside the bolt's lifecycle state.
-
----
-
-## Traceability Check
-
-As part of evaluating each bolt, BoltReviewer performs a lightweight traceability check:
-
-- Read the `requirements` and `stories` fields from the bolt's `spec.md` frontmatter and the `## Traceability` section.
-- Verify that the generated code actually touches functionality relevant to the cited requirement IDs. If a bolt claims to satisfy `FR-3` (e.g., "user authentication") but the code contains no authentication logic, flag this as a concern.
-- Add a **Traceability** line to `review.md` under the **Feedback** section:
-  `Traceability: Requirements {ID list} addressed — Yes / Partial / No`
-- A "Partial" or "No" finding should reduce the alignment score and appear as a **Concerns** item. It does not automatically trigger a hard block, but it does lower the score and may push a bolt into the advisory or rejected tier.
-
----
-
-## Documentation Quality Check
-
-The reviewer MUST evaluate documentation aspects of the bolt:
-
-- If `docs_impact` includes `code-comments`: verify complex logic has adequate inline comments in the generated code. Flag missing comments on non-obvious algorithms, public API entry points, or intricate state management as a concern.
-- If `docs_impact` includes any user-facing type (`readme`, `user-guide`, `config-reference`, `cli-reference`, `migration-guide`): verify the code behavior is clear enough to document -- acceptance criteria are testable and descriptive, public interfaces are well-named, and usage patterns are evident from the code structure.
-- If the bolt introduces new public APIs, new CLI commands, or new configuration options but `docs_impact` is set to `none`: flag this as a likely missed assessment. Include a concern noting that documentation impact may need to be updated before the Documentation Generation stage.
-
-Include a documentation quality note in the review.md Feedback section:
-`Documentation: docs_impact [{values}] -- {assessment: adequate / concerns noted / impact likely missed}`
-
----
-
-## BoltReviewer Behavior
-
-BoltReviewer is a decision engine, not an interactive agent. It:
-
-- Reads the bolt spec (`spec.md`) and the generated code in `Target Files`
-- Evaluates alignment against each acceptance criterion
-- Performs a traceability check against the cited requirement and story IDs
-- Computes a score and selects a tier
-- Writes the `review.md` artifact
-- Returns a structured decision object to the orchestrator
-
-All user-facing communication (presenting advisory findings, requesting acknowledgment, surfacing escalations) is the orchestrator's responsibility, not BoltReviewer's.
-
-The `momus` agent is dispatched via the review callback (`reviewCallback`) to perform the evaluation.
+# Bolt Review - Mandatory Quality Gate
+
+## Overview
+
+The Bolt Review stage is a mandatory quality gate that runs after every bolt's code generation is complete. The BoltReviewer evaluates whether the generated code meets the bolt's acceptance criteria and aligns with the approved spec.
+
+Review is performed by the `momus` agent via a review callback. BoltReviewer returns structured decision objects — it does not interact with users directly. User interaction (acknowledgment prompts, escalation notices) is handled by the orchestrator based on the decision returned.
+
+---
+
+## Two-Tier Alignment Model
+
+The BoltReviewer scores each bolt on a 0-100% alignment scale and maps the score to one of three tiers:
+
+| Score | Tier | Action |
+|-------|------|--------|
+| >= 70% | Auto-approve | Bolt accepted automatically; no user interaction required |
+| 50-69% | Advisory | Bolt proceeds with mandatory user acknowledgment |
+| < 50% | Hard block | Bolt rejected; must be re-scoped or split before retrying |
+
+### Auto-Approve (>= 70%)
+
+The bolt is accepted. The orchestrator transitions the bolt state from `in_review` to `done` without prompting the user.
+
+### Advisory (50-69%)
+
+The orchestrator presents the review findings to the user and requires explicit acknowledgment before the bolt proceeds. The user must confirm they understand the concerns and accept the bolt as-is.
+
+Acknowledgment is recorded in the bolt's `ConstructionBoltProgress` entry:
+- `acknowledged_by`: identifier of the user who acknowledged
+- `acknowledged_at`: ISO 8601 timestamp of acknowledgment
+
+### Hard Block (< 50%)
+
+The bolt is rejected. The orchestrator transitions the bolt state to `failed`. The user must re-scope the bolt (narrow scope, reduce complexity) or split it into smaller bolts before code generation can be retried.
+
+Hard blocks are never overridden, regardless of trust level.
+
+---
+
+## Trust-Based Auto-Approval
+
+When the trust level for the workflow is >= 2, the advisory tier (50-69%) is upgraded to auto-approve. This means:
+
+- Trust level 0-1: advisory tier requires user acknowledgment
+- Trust level >= 2: advisory tier auto-approves (treated as >= 70%)
+- Hard block (< 50%): **never overridden** by trust level
+
+The trust level is stored in the workflow checkpoint and reflects the user's established confidence in the AI agent for this workflow.
+
+---
+
+## Escalation
+
+If a bolt accumulates 2 consecutive review failures (2 reviews both scoring < 50%), an escalation event is triggered.
+
+The escalation event includes:
+- Bolt ID and title
+- Failure count
+- Recommended actions:
+  - **Re-scope**: Narrow the bolt's scope to reduce complexity
+  - **Split**: Divide the bolt into two or more smaller bolts with tighter acceptance criteria
+
+The orchestrator surfaces the escalation to the user and halts further attempts on that bolt until the user chooses an action.
+
+---
+
+## Review Artifact
+
+After each review, BoltReviewer writes a structured artifact:
+
+**Path**: `{workflowId}/construction/{parent_unit_id}/bolts/{boltId}/review.md`
+
+Example: `{workflowId}/construction/UNIT-001-foundation/bolts/BOLT-001-data-model/review.md`
+
+### Required Sections
+
+**Score** — Numeric alignment score (0-100%) with a brief rationale.
+
+**Decision** — One of: `approved`, `advisory`, `rejected`.
+
+**Feedback** — Specific, actionable observations about the generated code relative to the bolt's acceptance criteria. Each item should reference a specific criterion or target file.
+
+**Concerns** — List of issues that contributed to score reduction. May be empty for approved bolts.
+
+**Recommended Actions** _(escalation only)_ — Present only when 2 consecutive failures have occurred. Lists concrete steps the user should take (re-scope or split).
+
+---
+
+## Acknowledgment Fields
+
+When a bolt is accepted at the advisory tier, the orchestrator records acknowledgment on the bolt's progress entry in the checkpoint:
+
+```json
+{
+  "acknowledged_by": "user",
+  "acknowledged_at": "2026-01-15T10:30:00Z"
+}
+```
+
+These fields are stored on the `ConstructionBoltProgress` object alongside the bolt's lifecycle state.
+
+---
+
+## Traceability Check
+
+As part of evaluating each bolt, BoltReviewer performs a lightweight traceability check:
+
+- Read the `requirements` and `stories` fields from the bolt's `spec.md` frontmatter and the `## Traceability` section.
+- Verify that the generated code actually touches functionality relevant to the cited requirement IDs. If a bolt claims to satisfy `FR-3` (e.g., "user authentication") but the code contains no authentication logic, flag this as a concern.
+- Add a **Traceability** line to `review.md` under the **Feedback** section:
+  `Traceability: Requirements {ID list} addressed — Yes / Partial / No`
+- A "Partial" or "No" finding should reduce the alignment score and appear as a **Concerns** item. It does not automatically trigger a hard block, but it does lower the score and may push a bolt into the advisory or rejected tier.
+
+---
+
+## Documentation Quality Check
+
+The reviewer MUST evaluate documentation aspects of the bolt:
+
+- If `docs_impact` includes `code-comments`: verify complex logic has adequate inline comments in the generated code. Flag missing comments on non-obvious algorithms, public API entry points, or intricate state management as a concern.
+- If `docs_impact` includes any user-facing type (`readme`, `user-guide`, `config-reference`, `cli-reference`, `migration-guide`): verify the code behavior is clear enough to document -- acceptance criteria are testable and descriptive, public interfaces are well-named, and usage patterns are evident from the code structure.
+- If the bolt introduces new public APIs, new CLI commands, or new configuration options but `docs_impact` is set to `none`: flag this as a likely missed assessment. Include a concern noting that documentation impact may need to be updated before the Documentation Generation stage.
+
+Include a documentation quality note in the review.md Feedback section:
+`Documentation: docs_impact [{values}] -- {assessment: adequate / concerns noted / impact likely missed}`
+
+---
+
+## BoltReviewer Behavior
+
+BoltReviewer is a decision engine, not an interactive agent. It:
+
+- Reads the bolt spec (`spec.md`) and the generated code in `Target Files`
+- Evaluates alignment against each acceptance criterion
+- Performs a traceability check against the cited requirement and story IDs
+- Computes a score and selects a tier
+- Writes the `review.md` artifact
+- Returns a structured decision object to the orchestrator
+
+All user-facing communication (presenting advisory findings, requesting acknowledgment, surfacing escalations) is the orchestrator's responsibility, not BoltReviewer's.
+
+The `momus` agent is dispatched via the review callback (`reviewCallback`) to perform the evaluation.