@entelligentsia/forgecli 0.3.0 → 0.7.6

package/dist/forge-payload/.base-pack/workflows/_fragments/store-cli-verbs.md

@@ -0,0 +1,23 @@
+# Fragment: store-cli Verb Cheat-Sheet
+
+<!-- Canonical store-cli verb list. Referenced by meta workflows that issue
+     store-cli calls. Surface it inline near the first store-cli invocation
+     so subagents stop inventing REST-style verbs (`get`, `set`, `delete`)
+     when they have to improvise a follow-up call. See forge#95. -->
+
+store-cli verbs: `read` | `list` | `write` | `emit` | `update-status` | `set-summary` | `set-bug-summary` | `describe` | `template` | `nlp` | `query` | `delete`
+
+Notes for subagents:
+
+- **`read`** is the canonical "fetch one record" verb. There is no `get`.
+- **`list`** filters by entity (`sprint`, `task`, `bug`, `event`, `feature`)
+  and optional flags. There is no `find` or `search` — use `nlp` for
+  natural-language lookup.
+- **`update-status`** is the ONLY supported task/bug status mutation path.
+  Do not `write` a task back with a new `status` field; the FSM is enforced
+  by `update-status`.
+- **`emit`** appends an event. There is no `append-event` / `add-event`.
+- **`set-summary`** / **`set-bug-summary`** write summary sidecars referenced
+  from the entity record. Do not inline summaries into the entity via `write`.
+- If you need a verb not on this list, run
+  `node "$FORGE_ROOT/tools/store-cli.cjs" --help` before improvising.

package/dist/forge-payload/.base-pack/workflows/architect_approve.md

@@ -21,6 +21,24 @@ deps:
 ---
 
 # Approve Task
+## Iron Laws
+
+- Approve only when the implementation is consistent with the project's architecture and the deployment posture is understood. Architectural sign-off is not a rubber stamp — it is the last point at which cross-cutting concerns can be caught cheaply.
+- Read `.forge/personas/architect.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
+## Store-Write Verification
+
+Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
+non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error (names the offending field + schema file).
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times.
+4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
 ## Algorithm
 
 ```
@@ -43,13 +61,17 @@ deps:
    - Assess operational impact (deployment changes, migrations)
 
 3. Sign Off:
-   - Write ARCHITECT_APPROVAL.md with:
-     - Approval status
+   - Write ARCHITECT_APPROVAL.md containing:
+     - A canonical verdict line for human readers, on its own line, in this exact form:
+       ```
+       **Verdict:** [Approved | Revision Required]
+       ```
+     - Approval status rationale
      - Deployment notes
      - Follow-up items for future sprints
+   - The downstream commit-phase preflight gate does NOT read this markdown; it reads `task.status === "approved"` set in step 4. The `**Verdict:**` line is a human breadcrumb only.
 
 4. Finalize:
-   - Update task status via `/forge:store update-status task {taskId} status approved`
-   - Emit the complete event via `/forge:store emit {sprintId} '{event-json}'`
-   - Execute Token Reporting (see `_fragments/finalize.md`)
+   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status approved`
+   - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```

package/dist/forge-payload/.base-pack/workflows/architect_review_sprint_completion.md

@@ -33,7 +33,14 @@ deps:
      - If Approved: confirm sprint is ready for retrospective
 
 4. Finalize:
-   - Update sprint status via `/forge:store update-status sprint {sprintId} status completed`
-   - Emit the complete event via `/forge:store emit {sprintId} '{event-json}'`
-   - Execute Token Reporting (see `_fragments/finalize.md`)
+   - If step-3 verdict is `Approved`:
+     - Update sprint status to `completed` via
+       `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status completed`
+   - If step-3 verdict is `Revision Required` and orchestrator passed `mode=partial`:
+     - Update sprint status to `partially-completed` via
+       `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status partially-completed`
+   - If step-3 verdict is `Revision Required` and orchestrator passed `mode=complete`:
+     - Do NOT transition status. Leave the sprint at its current status and exit;
+       the orchestrator will surface the verdict to the user.
+   - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```

package/dist/forge-payload/.base-pack/workflows/architect_sprint_intake.md

@@ -16,27 +16,34 @@ deps:
 ## Algorithm
 
 ```
-0. Pre-flight Gate Check:
-   - Run `/cost` to verify token reporting available
-   - If `/cost` succeeds → note for later (will use reported data)
-   - If `/cost` fails or unavailable → note for later (will use estimates)
+0. Project Orientation:
+   - Your current working directory is the project root.
+   - Forge config lives at `.forge/config.json` (relative to cwd); the `forge_config` MCP tool returns canonical values.
+   - Engineering knowledge lives under `engineering/` (relative to cwd) — `MASTER_INDEX.md`, `architecture/`, `business-domain/`, `sprints/`, `features/`.
+   - Paths in subsequent steps resolve against this cwd.
 
-1. Load Context:
-   - Read project vision and current MASTER_INDEX.md
-   - Read any pending feature requests or bug reports
+1. Pre-flight Gate Check:
+   - Probe token reporting: if the host runtime exposes a `/cost` slash command
+     (Claude Code), invoke it; on any other runtime treat as unavailable and
+     proceed. Do NOT search for or invent a `cost-cli.cjs` — there is no such tool.
+   - If the probe succeeds → note for later (will use reported data)
+   - If the probe fails or is unavailable → note for later (will use estimates)
 
-2. Requirements Interview:
+2. Load Context:
+   - Read `engineering/MASTER_INDEX.md` (relative to cwd)
+   - Read any pending feature requests or bug reports under `engineering/`
+
+3. Requirements Interview:
    - Conduct a structured interview with the user
    - Capture: Objectives, Constraints, Deliverables, and Success Criteria
    - Clarify ambiguous requirements through iterative questioning
 
-3. Document Requirements:
-   - Generate SPRINT_REQUIREMENTS.md
+4. Document Requirements:
+   - Generate `engineering/sprints/<SPRINT_ID>/SPRINT_REQUIREMENTS.md`
    - Map requirements to existing Features if applicable
    - Ensure all deliverables are measurable and testable
 
-4. Finalize:
-   - Update sprint status via `/forge:store update-status sprint {sprintId} status planning`
-   - Emit the complete event via `/forge:store emit {sprintId} '{event-json}'`
-   - Execute Token Reporting (see `_fragments/finalize.md`)
+5. Finalize:
+   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status planning`
+   - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```

package/dist/forge-payload/.base-pack/workflows/architect_sprint_plan.md

@@ -17,9 +17,11 @@ deps:
 
 ```
 0. Pre-flight Gate Check:
-   - Run `/cost` to verify token reporting available
-   - If `/cost` succeeds → note for later (will use reported data)
-   - If `/cost` fails or unavailable → note for later (will use estimates)
+   - Probe token reporting: if the host runtime exposes a `/cost` slash command
+     (Claude Code), invoke it; on any other runtime treat as unavailable. Do
+     NOT search for or invent a `cost-cli.cjs` — there is no such tool.
+   - If the probe succeeds → note for later (will use reported data)
+   - If the probe fails or is unavailable → note for later (will use estimates)
 
 1. Load Context:
    - Query the store to orient on current project state before reading docs:
@@ -45,11 +47,11 @@ deps:
 
 4. Documentation:
    - Write SPRINT_PLAN.md to `engineering/sprints/{sprintId}/SPRINT_PLAN.md`
-   - Create each task via `/forge:store write task '{task-json}'`.
+   - Create each task via `node "$FORGE_ROOT/tools/store-cli.cjs" write task '{task-json}'`.
      If the command exits non-zero or the PreToolUse hook blocks the write:
      parse the error, correct the JSON, and retry (see Store-Write Verification).
      Do not proceed to the next task until this write succeeds.
-   - Update the sprint record with all new task IDs via `/forge:store write sprint '{updated-sprint-json}'` (the sprint JSON must include the complete `taskIds` array with all newly created task IDs).
+   - Update the sprint record with all new task IDs via `node "$FORGE_ROOT/tools/store-cli.cjs" write sprint '{updated-sprint-json}'` (the sprint JSON must include the complete `taskIds` array with all newly created task IDs).
      If the command exits non-zero or the PreToolUse hook blocks the write:
      parse the error, correct the JSON, and retry (see Store-Write Verification).
      Do not proceed until this write succeeds.
@@ -57,16 +59,12 @@ deps:
      * Folder: `engineering/sprints/{sprintId}/{taskId}/`
      * File: `TASK_PROMPT.md` — populate from `.forge/templates/TASK_PROMPT_TEMPLATE.md`
        filling in title, objective, acceptance criteria, entities, DSL/CLI changes, and operational impact
-   - Update sprint status via `/forge:store update-status sprint {sprintId} status active`.
+   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status active`.
      If the command exits non-zero, parse the error and retry
      (see Store-Write Verification). Do not proceed until this write succeeds.
 
 5. Finalize:
-   - Emit the complete event via `/forge:store emit {sprintId} '{event-json}'`.
-     If the command exits non-zero or the PreToolUse hook blocks the write:
-     parse the error, correct the JSON, and retry (see Store-Write Verification).
-     Do not proceed until this write succeeds.
-   - Execute Token Reporting (see `_fragments/finalize.md`)
+   - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```
 
 ## Anti-Pattern Guard

package/dist/forge-payload/.base-pack/workflows/collator_agent.md

@@ -13,6 +13,25 @@ deps:
 ---
 
 # Collate
+## Iron Laws
+
+- Collation is a read-and-rewrite of generated markdown. Do not mutate any JSON record under `.forge/store/`; the store is the source of truth and collation flows downstream from it.
+- Read `.forge/personas/collator.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store reads via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
+## Store-Write Verification
+
+Collation typically writes markdown views, not JSON records. If a remediation
+step does call `forge_store` and the call exits non-zero or the `PreToolUse`
+write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error (names the offending field + schema file).
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times.
+4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
 ## Algorithm
 
 ```
@@ -42,8 +61,7 @@ deps:
    - On exit 1 (architecture directory absent), skip silently.
 
 4. Finalize:
-   - Emit the complete event via `/forge:store emit {sprintId} '{event-json}'`
-   - Execute Token Reporting (see `_fragments/finalize.md`)
+   - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
    - Invoke Tomoshibi via Skill tool to refresh KB and workflow links in agent
      instruction files:
      ```

package/dist/forge-payload/.base-pack/workflows/commit_task.md

@@ -21,6 +21,24 @@ deps:
 ---
 
 # Commit Task
+## Iron Laws
+
+- Commit only the artifacts produced for this task; do not sweep unrelated working-tree changes into the commit. The commit boundary mirrors the task boundary.
+- Read `.forge/personas/engineer.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
+## Store-Write Verification
+
+Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
+non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error (names the offending field + schema file).
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times.
+4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
 ## Algorithm
 
 ```
@@ -43,12 +61,12 @@ deps:
 3. Commit:
    - Create a commit with a message following project conventions
    - Include task ID in the commit message
-   - Co-author with "Claude Opus 4.6 <noreply@anthropic.com>"
+   - Append a `Co-authored-by:` trailer crediting the AI assistant that actually ran the session. Resolve the identity from the host runtime: on Claude Code use `Co-authored-by: Claude <noreply@anthropic.com>`; on pi / Ollama / any other runtime use `Co-authored-by: {modelId} <noreply@{provider}.ai>` derived from the session's `provider` and `modelId` (e.g. `Co-authored-by: glm-5.1:cloud <noreply@ollama.ai>`); if neither is resolvable, omit the trailer rather than guess. Do NOT hardcode `Claude Opus 4.6 <noreply@anthropic.com>` — that literal is rejected as a regression of forge#82 (commits authored under the wrong model).
+   - Let git's configured `user.name` / `user.email` own the commit author; never pass `--author` to override it.
 
 4. Store Finalization:
-   - Update task status via `/forge:store update-status task {taskId} status committed`
+   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status committed`
 
 5. Finalize:
-   - Emit the complete event via `/forge:store emit {sprintId} '{event-json}'`
-   - Execute Token Reporting (see `_fragments/finalize.md`)
+   - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```

package/dist/forge-payload/.base-pack/workflows/enhance.md

@@ -0,0 +1,274 @@
+---
+requirements:
+  reasoning: High
+  context: High
+  speed: Low
+audience: orchestrator-only
+deps:
+  personas: [engineer]
+  skills: [engineer, generic]
+  templates: []
+  sub_workflows: []
+  kb_docs: []
+  config_fields: [paths.engineering, paths.forgeRoot]
+---
+
+# Enhancement Agent
+
+## Iron Laws
+
+- Orchestrator-only: this workflow runs with full tool access in the orchestrator session. NEVER delegate it to a subagent.
+- Read `.forge/personas/engineer.md` first; print the persona identity line to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+- Phase 1 only touches `{{KEY}}` token text; never rewrite persona prose, algorithm steps, or role definitions.
+
+## Store-Write Verification
+
+Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
+non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error.
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times. After 3 failures, halt and escalate.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+## Note on `.forge/enhancement-proposals/` directory
+
+Phases 2 and 3 write proposal artifacts to `.forge/enhancement-proposals/`. This directory is
+distinct from `.forge/enhancements/` (FR-007, S14 scope). This workflow uses `mkdir -p` before
+writing the first proposal artifact to avoid assuming the directory exists. No conflict with S14.
+
+## Confidence gating (Phase 1)
+
+A key substitution is **high-confidence** when there is exactly one unambiguous signal source
+(e.g., `scripts.test` in `package.json` is the sole candidate for `{{TEST_COMMAND}}`). It is
+**low-confidence** when multiple candidates exist or no signal is found. Only high-confidence
+fills are applied automatically. Low-confidence keys are listed in the Phase 1 report and left
+unsubstituted for the user to fill manually.
+
+## Phase routing
+
+Receive the phase flag from the command invocation:
+
+| Flag | Mode |
+|------|------|
+| `--phase 1` or `--auto` | Auto-apply: placeholder fills only |
+| `--phase 2` | Propose-diffs: sprint artifact + friction scan |
+| `--phase 3` | Drift detection: full codebase vs structural-element comparison |
+
+Default to `--phase 3` if no phase flag is given.
+
+---
+
+## Step 0 — Resolve roots
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+Read `.forge/config.json`. Resolve:
+- `PROJECT_ROOT` = current working directory (absolute).
+- `ENGINEERING_PATH` = `paths.engineering` from config (default `engineering`).
+
+---
+
+## Phase 1 — Auto-apply placeholder fills
+
+### When to run
+
+Invoked by T09 post-init hook (`--auto`) or manually via `/forge:enhance --phase 1`.
+
+### Algorithm
+
+1. **Scan structural elements** for `{{KEY}}` patterns:
+   ```sh
+   grep -r '{{' "$PROJECT_ROOT/.forge/personas/" "$PROJECT_ROOT/.forge/skills/" \
+        "$PROJECT_ROOT/.forge/workflows/" "$PROJECT_ROOT/.forge/templates/" \
+        --include="*.md" -l 2>/dev/null
+   ```
+   Collect each unique `{{KEY}}` token found.
+
+2. **Skip runtime passthrough keys** — keys used at runtime (e.g., `{{TASK_ID}}`, `{{SPRINT_ID}}`,
+   `{{ARGUMENTS}}`) are intentional and must not be substituted. Read
+   `$FORGE_ROOT/tools/substitute-placeholders.cjs` to identify the RUNTIME_PASSTHROUGH_KEYS list.
+   Exclude them from the fill candidates.
+
+3. **Derive values from codebase signals** — for each remaining `{{KEY}}`, attempt to derive a
+   value with high confidence:
+
+   | Key | Signal source |
+   |-----|--------------|
+   | `{{STACK_SUMMARY}}` | `package.json` dependencies field (list top-level frameworks); or dominant file extension survey |
+   | `{{BRANCHING_CONVENTION}}` | `git branch -a` output pattern or `.git/config` |
+   | `{{TEST_COMMAND}}` | `package.json` → `scripts.test` |
+   | `{{BUILD_COMMAND}}` | `package.json` → `scripts.build` |
+   | `{{ENTITY_MODEL}}` | Scan source for ORM model files or type definitions |
+   | `{{KEY_DIRECTORIES}}` | Top-level directory listing (exclude `.git`, `node_modules`, `.forge`) |
+   | `{{IMPACT_CATEGORIES}}` | Derive from project type (web app → UI/API/DB/Infra; library → API/Docs/Tests) |
+
+   Any key without a single unambiguous signal → mark as **low-confidence** (skip auto-fill).
+
+4. **Apply high-confidence fills** — for each high-confidence key, perform in-place substitution
+   in all structural element files that contain the key. Use `substitute-placeholders.cjs` if it
+   supports a targeted single-key mode; otherwise apply the substitution directly with a read/write
+   cycle per file.
+
+   **Minimal modification principle**: Phase 1 only touches `{{KEY}}` token text. It never rewrites
+   persona prose, algorithm steps, or role definitions.
+
+5. **Update `project-context.json`** — write the newly discovered values into
+   `$PROJECT_ROOT/.forge/project-context.json` so that future invocations of
+   `substitute-placeholders.cjs` use the derived values.
+
+6. **Snapshot gate** — if at least one fill was applied:
+   ```sh
+   node "$FORGE_ROOT/tools/manage-versions.cjs" add-snapshot \
+     --source post-init \
+     --enhanced-elements "<comma-separated list of relative .forge/ paths that were modified>"
+   ```
+   If no fills were applied, skip the snapshot call entirely.
+
+7. **Emit enhancement event** to the store:
+   ```sh
+   node "$FORGE_ROOT/tools/store-cli.cjs" emit enhancement '{
+     "eventId": "<ISO timestamp slug>_enhance_phase1",
+     "taskId": "enhancement",
+     "sprintId": "enhancement",
+     "role": "enhancement-agent",
+     "action": "enhancement-completed",
+     "phase": "post-init",
+     "iteration": 1,
+     "notes": "{\"phase\":1,\"fillCount\":<N>,\"snapshotCreated\":<true|false>}"
+   }'
+   ```
+
+8. **Report**:
+   ```
+   ## Phase 1 Enhancement Complete
+
+   Fills applied: N key(s) — {{KEY1}}, {{KEY2}}, ...
+   Uncertain keys (not filled): M — {{KEY3}}, ...  (manual intervention needed)
+   Snapshot: [written as snap-{index}] | [skipped — no fills]
+   ```
+
+---
+
+## Phase 2 — Propose enrichment diffs (post-sprint)
+
+### When to run
+
+Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
+
+### Algorithm
+
+1. **Collect friction events**:
+   ```sh
+   node -e "
+   const fs = require('fs'), path = require('path');
+   const eventsDir = '.forge/store/events';
+   const allFiles = fs.readdirSync(eventsDir, { withFileTypes: true })
+     .flatMap(d => d.isDirectory()
+       ? fs.readdirSync(path.join(eventsDir, d.name)).map(f => path.join(eventsDir, d.name, f))
+       : [path.join(eventsDir, d.name)]
+     )
+     .filter(f => f.endsWith('.json'));
+   const friction = allFiles
+     .map(f => { try { return JSON.parse(fs.readFileSync(f,'utf8')); } catch { return null; } })
+     .filter(e => e && e.type === 'friction');
+   console.log(JSON.stringify(friction));
+   "
+   ```
+
+2. **Deduplicate** friction events by composite key `workflow + persona + issue`. Keep the most
+   recent occurrence of each composite key.
+
+3. **Read most recent completed sprint** from `.forge/store/sprints/` (status `done` or
+   `retrospective-done`), sorted by completion date. Read its task records from
+   `.forge/store/tasks/` filtered by the sprint ID.
+
+4. **Synthesize enrichment proposals** — for each friction event:
+   - Identify which persona or skill file it references.
+   - Propose a targeted addition: e.g., "architect persona lacks routing pattern knowledge —
+     suggest adding `{{KB_PATH}}/routing.md` reference to deps.kb_docs."
+   - For large committed file sets (> 5 files in the sprint), also check whether
+     `engineer-skills.md` or `architect-skills.md` should reference new patterns.
+
+5. **Write proposal artifact**:
+   ```sh
+   mkdir -p "$PROJECT_ROOT/.forge/enhancement-proposals"
+   ```
+   Write to `$PROJECT_ROOT/.forge/enhancement-proposals/phase2-<timestamp>.md`. Format:
+   one section per proposed change, with a fenced diff block showing before/after text.
+
+6. **Present to user**:
+   ```
+   ## Phase 2 Enhancement Proposals
+
+   N change(s) proposed — review: .forge/enhancement-proposals/phase2-<timestamp>.md
+
+   [A] Apply all  [r] Review individually  [n] Skip
+   ```
+
+7. **On approval** — for each approved change:
+   - Apply the edit in-place.
+   - Call `manage-versions.cjs add-snapshot --source post-sprint:<SPRINT_ID> --enhanced-elements <list>`.
+
+8. **Emit enhancement event** (same schema as Phase 1, with `"phase": "post-sprint"`).
+
+9. **Report**: N changes applied, M skipped, snapshot written or skipped.
+
+---
+
+## Phase 3 — Drift detection (on-demand / delegated from calibrate)
+
+### When to run
+
+Invoked by `/forge:enhance --phase 3` (default when no phase given), or delegated by
+`/forge:calibrate` after its Step 4 drift categorization.
+
+### Algorithm
+
+1. **Read codebase state** from `$PROJECT_ROOT/.forge/project-context.json`:
+   key directories, entities, commands, stack summary, test command, build command.
+
+2. **Read all structural elements** from `.forge/personas/`, `.forge/skills/`,
+   `.forge/workflows/`, `.forge/templates/`.
+
+3. **Compare**: for each structural element, verify:
+   - It correctly references known entities and key directories.
+   - It uses valid `{{KB_PATH}}` references (paths that exist in `engineering/`).
+   - Its `deps.kb_docs` list includes docs referenced in its body.
+
+4. **Read friction events** (same collection as Phase 2 Step 1).
+
+5. **Read `calibrationBaseline`** from `$PROJECT_ROOT/.forge/config.json` to understand what
+   was last confirmed correct.
+
+6. **Write drift report**:
+   ```sh
+   mkdir -p "$PROJECT_ROOT/.forge/enhancement-proposals"
+   ```
+   Write to `$PROJECT_ROOT/.forge/enhancement-proposals/phase3-<timestamp>.md`.
+
+7. **Present to user**:
+   ```
+   ## Phase 3 Drift Report
+
+   N discrepancy(ies) found — review: .forge/enhancement-proposals/phase3-<timestamp>.md
+
+   [A] Apply all  [r] Review individually  [n] Skip
+   ```
+
+8. **On approval** — apply changes and call `manage-versions.cjs add-snapshot --source on-demand`.
+
+9. **Emit enhancement event** (`"phase": "on-demand"`).
+
+10. **Report**: N changes applied, snapshot written or skipped.
+
+---
+
+## On error
+
+If any step fails unexpectedly, describe what went wrong and offer:
+
+> "This looks like a Forge bug. Would you like to file a report? Run `/forge:report-bug`."

package/dist/forge-payload/.base-pack/workflows/fix_bug.md

@@ -47,6 +47,11 @@ deps:
             node "$FORGE_ROOT/tools/store-cli.cjs" read bug {BUG_ID} --json
    - Reproduce the bug: create a failing test case or a reproduction script
    - Confirm the root cause via codebase research
+   - After creating the bug record, transition to in-progress:
+     ```sh
+     node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug {BUG_ID} status triaged
+     node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug {BUG_ID} status in-progress
+     ```
 
 2. Plan:
    - Generate BUG_FIX_PLAN.md following the plan template
@@ -75,10 +80,12 @@ deps:
    - **After Implement phase:**
      Write `IMPLEMENTATION-SUMMARY.json` with `key_changes` and `verdict: "n/a"`.
      Then: `node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bug_id} implementation ...SUMMARY.json`
+   - **After Approve phase:**
+     Write `APPROVE-SUMMARY.json` with `objective`, `verdict` (approved|revision), and `artifact_ref`.
+     Then: `node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bug_id} approve ...APPROVE-SUMMARY.json`
    - If set-bug-summary exits non-zero, fix the JSON and retry before proceeding.
 
 6. Finalize:
-   - Execute Token Reporting (see `_fragments/finalize.md`) — do this
      first so the sidecar is written before the event directory is purged
    - Summarise accumulated cost data into the bug artifact:
      read all events from `.forge/store/events/{bugId}/`, aggregate
@@ -101,8 +108,8 @@ deps:
      INDEX.md — do NOT mark the bug as fixed. Escalate to the human
      with the missing artifacts listed on stderr.
      If exit 2 (misconfiguration), escalate immediately.
-   - Update bug status via `/forge:store update-status bug {bugId} status fixed`
-   - Emit the complete event via `/forge:store emit {bugId} '{event-json}'`
+   - Update bug status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug {bugId} status fixed`
+   - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
      (tombstone — written after the purge; the only event that will remain)
 ```
 ## Announcement Algorithm
@@ -246,6 +253,8 @@ identical to `meta-orchestrate.md` — see that file's "Phase Gates" section
 for the directive reference.
 
 ```gates phase=plan-fix
+forbid bug.status == blocked
+forbid bug.status == escalated
 forbid bug.status == fixed
 forbid bug.status == abandoned
 ```
@@ -255,6 +264,8 @@ artifact {engineering}/bugs/{bug}/BUG_FIX_PLAN.md min=200
 ```
 
 ```gates phase=implement
+forbid bug.status == blocked
+forbid bug.status == escalated
 artifact {engineering}/bugs/{bug}/BUG_FIX_PLAN.md min=200
 after review-plan = approved
 forbid bug.status == fixed
@@ -276,6 +287,22 @@ after approve = approved
 artifact {engineering}/bugs/{bug}/INDEX.md
 ```
 
+## Friction Emit
+
+When the Bug Fixer detects skill friction during fix-bug — a referenced skill is unused, fails on invocation, is missing from the registry, has gone stale relative to current architecture, or is redundant with another skill — emit a `friction` event so `/forge:enhance --phase 2` can act on the signal. This is the writer side of the channel whose reader landed in S13-T08; the reader is empty without these emits.
+
+**Trigger conditions** (set `issue` to the matching token):
+
+| Token              | When to emit                                                                     |
+|--------------------|----------------------------------------------------------------------------------|
+| `skill_unused`     | A skill listed in the persona's skill block was loaded but never consulted.      |
+| `skill_failed`     | A skill was consulted but its guidance produced an error or required correction. |
+| `skill_missing`    | The workflow needed guidance the available skills did not cover.                 |
+| `skill_stale`      | A skill's guidance contradicts current architecture / supersedes its own advice. |
+| `skill_redundant`  | Two skills provided overlapping or conflicting guidance for the same decision.   |
+
+**Recording friction (subagent side):** call `node "$FORGE_ROOT/tools/friction-emit.cjs` `--workflow {workflow} --persona {persona-noun} --issue {token} [--subkind {token}] [--evidence '{...}']`. The tool appends one judgement-only record to `.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator drains the file at phase-end, stamps runtime attribution (model, provider, usage, wall times, eventId) onto each record, and emits the events via `store-cli emit` as event type `"friction"`. The schema enforces `{workflow, persona, issue}` as required when `type === "friction"`; `subkind` is the frozen enum `skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant` or experimental `^x_[a-z_]+$`. Emit one record per distinct friction signal — do not coalesce.
+
 ## Progress Reporting
 
 <!-- See _fragments/progress-reporting.md for canonical definition -->