@entelligentsia/forgecli 0.10.0 → 0.11.2

package/dist/forge-payload/meta/tool-specs/validate-store.spec.md

@@ -0,0 +1,191 @@
+# Tool Spec: validate-store
+
+## Purpose
+
+Check store integrity: required fields present, referential integrity
+between sprints/tasks/bugs/events, no orphaned records.
+
+## Inputs
+
+- `.forge/config.json` — paths
+- `.forge/schemas/` — JSON Schema files (task, event, sprint, bug, feature); written during init Phase 8
+- `.forge/store/` — all JSON files including `features/`
+
+## Outputs
+
+- Validation report to stdout (text or JSON)
+- Exit 0 if valid, 1 if errors found
+
+## CLI Interface
+
+```
+<tool> validate-store                     # full validation (text output)
+<tool> validate-store --dry-run           # same checks, just report (text)
+<tool> validate-store --fix               # auto-fix where possible
+<tool> validate-store --fix --dry-run     # preview fixes without writing
+<tool> validate-store --json              # JSON structured output
+<tool> validate-store --dry-run --json    # JSON diagnosis, no fixes
+<tool> validate-store --fix --dry-run --json  # JSON preview of fixes, no writes
+<tool> validate-store --fix --json        # JSON output with fixes applied
+```
+
+## JSON Output Mode (`--json`)
+
+When `--json` is present, the tool emits a single JSON object to stdout instead
+of human-readable text. The JSON structure:
+
+```json
+{
+  "ok": true,
+  "errors": [
+    {
+      "entity": "sprint",
+      "id": "FORGE-S07",
+      "category": "invalid-enum",
+      "field": "status",
+      "message": "field \"status\": value \"in-progress\" not in [planning, active, ...]",
+      "value": "in-progress",
+      "expected": ["planning", "active", "completed", ...]
+    }
+  ],
+  "warnings": [
+    {
+      "entity": "sprint",
+      "id": "FORGE-S03",
+      "category": "orphan-directory",
+      "field": null,
+      "message": "directory \"FORGE-S03-lean-migration\" has no sprint record in store"
+    }
+  ],
+  "fixes": [
+    {
+      "entity": "sprint",
+      "id": "FORGE-S01",
+      "category": "backfill",
+      "field": "createdAt",
+      "message": "backfilled \"createdAt\" = \"2026-01-15T10:00:00.000Z\"",
+      "applied": true
+    }
+  ],
+  "summary": {
+    "sprints": 7,
+    "tasks": 50,
+    "bugs": 4,
+    "features": 1,
+    "errors": 3,
+    "warnings": 2,
+    "fixes": 1
+  }
+}
+```
+
+### Error Categories
+
+| Category | Description |
+|----------|-------------|
+| `missing-required` | Required field is null, undefined, or empty string |
+| `type-mismatch` | Field value has wrong JSON type (e.g., string where number expected) |
+| `invalid-enum` | Field value is not in the declared enum set |
+| `undeclared-field` | Field not in schema with `additionalProperties: false` |
+| `orphaned-fk` | Foreign key references a non-existent entity |
+| `filename-mismatch` | Event filename does not match its eventId |
+| `minimum-violation` | Numeric value below declared minimum |
+| `orphan-directory` | Filesystem directory has no corresponding store record |
+| `stale-path` | `path` field references a nonexistent directory |
+| `missing-optional` | Optional field is absent (warning, not error) |
+
+### Fix Categories
+
+| Category | Description |
+|----------|-------------|
+| `backfill` | Missing field filled with a derived default |
+| `orphaned-fk` | Orphaned foreign key nullified |
+| `filename-mismatch` | Event file renamed or eventId corrected |
+
+The `applied` field on fixes is `true` when the fix was actually written to disk,
+`false` when `--dry-run` is active (preview only).
+
+### `--fix --dry-run` Combination
+
+When both `--fix` and `--dry-run` are specified, the tool previews what fixes
+*would* be applied without writing anything. Each fix in the JSON output has
+`applied: false`. This is useful for the `/forge:store:repair` skill to assess
+what auto-fixes are available before applying them.
+
+## Validation Rules
+
+### Required Fields
+
+Load the JSON Schema files from `.forge/schemas/` at runtime and derive required
+fields from each schema's `"required"` array. Do NOT hardcode field names.
+
+If a schema file is missing, fall back to these defaults and warn:
+- Sprint: `sprintId`, `title`, `status`
+- Task: `taskId`, `sprintId`, `title`, `status`, `path`
+- Bug: `bugId`, `title`, `severity`, `status`, `path`, `reportedAt`
+- Event: `eventId`, `sprintId`, `role`, `action`, `startTimestamp`, `endTimestamp`, `durationMinutes`
+
+When schemas are present, also validate field types and enum values per the
+schema definitions — not just field presence.
+
+### Nullable Foreign Keys
+
+`sprintId` and `taskId` are nullable foreign keys — `null` means "not associated"
+(e.g. standalone bug fix with no sprint, sprint-level event with no task).
+The validator must accept `null` for these fields without reporting an error.
+
+`feature_id` on sprint and task records is a nullable FK pointing to
+`.forge/store/features/{FEATURE_ID}.json`. A `null` value is valid (the record is
+not associated with any feature). A non-null value must match the `id` field of an
+existing feature record.
+
+### Referential Integrity
+- Every task.sprintId references an existing sprint (when non-null)
+- Every event.taskId references an existing task OR bug (when non-null)
+- Every event.sprintId references an existing sprint OR matches the parent directory name (virtual sprint dirs like `events/bugs/`, `events/ops/`)
+- Every bug.similarBugs[] references existing bugs
+- Every sprint.feature_id and task.feature_id references an existing feature (when non-null)
+
+### Orphan Detection
+- Task directories in `engineering/sprints/` without corresponding store JSON
+- Store JSON without corresponding artifact directory
+
+### Status Consistency
+- Task status matches artifact presence (e.g., `committed` tasks should have all artifacts)
+- Sprint status consistent with task statuses
+
+### Undeclared Fields
+
+When a schema has `additionalProperties: false`, any field not in the schema's
+`properties` is reported as an error with category `undeclared-field`. This
+catches fields that were valid in older schema versions but are no longer accepted.
+
+## Error Handling
+
+- Wrap the entire entry point in a top-level exception handler.
+- On unexpected errors (missing files, JSON parse failures, unhandled
+  exceptions), print a clear one-line message to stderr and exit 1.
+- Never let the tool crash with an unhandled exception or stack trace visible
+  to the caller — all errors are caught and reported cleanly.
+- Python pattern:
+  ```python
+  if __name__ == "__main__":
+      try:
+          sys.exit(main())
+      except Exception as e:
+          print(f"Error: {e}", file=sys.stderr)
+          sys.exit(1)
+  ```
+- JS/TS pattern:
+  ```js
+  process.on('uncaughtException', (e) => {
+      process.stderr.write(`Error: ${e.message}\n`);
+      process.exit(1);
+  });
+  ```
+
+## Auto-Fix Rules (--fix mode)
+- Add missing optional fields with defaults
+- Create missing `.gitkeep` files in empty directories
+- Nullify orphaned `feature_id` references on sprint and task records (log each fix)
+- Do NOT delete orphaned records — only report them

package/dist/forge-payload/meta/workflows/_fragments/context-injection.md

@@ -0,0 +1,75 @@
+# Fragment: Context Injection
+
+<!-- Canonical definition of architecture_block + summary_block assembly patterns.
+     Referenced by meta-orchestrate.md and meta-fix-bug.md. -->
+
+## Architecture Context Block
+
+Read `.forge/cache/context-pack.md` (if it exists) and inject into the subagent prompt
+under the heading `### Architecture context (summary — full docs available at paths listed below)`.
+If the pack is absent, omit this block silently — the subagent falls back to reading
+architecture docs directly.
+
+```python
+context_pack_path = ".forge/cache/context-pack.md"
+context_pack_json_path = ".forge/cache/context-pack.json"
+if file_exists(context_pack_path):
+  context_pack_md = read_file(context_pack_path)
+  try:
+    context_pack_json = read_json(context_pack_json_path)
+    full_doc_paths = "\n".join(f"- {s['path']}" for s in context_pack_json.get("sources", []))
+  except:
+    full_doc_paths = "engineering/architecture/ (see context-pack.json for full list)"
+  architecture_block = (
+    "### Architecture context (summary — full docs available at paths listed below)\n\n"
+    + context_pack_md
+    + "\n\nRead full architecture docs only if the summary above is insufficient for "
+    + "your decision. Full docs:\n"
+    + full_doc_paths
+    + "\n\n"
+  )
+else:
+  architecture_block = ""
+```
+
+## Prior Phase Summary Block
+
+Re-read the record from disk after each phase so summaries accumulate.
+For bugs, pass `record_type="bug"` to read from the bugs store path.
+
+```python
+# record_type: "task" (default) or "bug"
+if record_type == "bug":
+  record_fresh = read_json(f".forge/store/bugs/{record_id}.json")
+else:
+  record_fresh = read_json(f".forge/store/tasks/{record_id}.json")
+summaries = (record_fresh or {}).get("summaries", {})
+
+SUMMARY_PHASE_LABELS = {
+  "plan": "Plan", "review_plan": "Plan review",
+  "implementation": "Implementation", "code_review": "Code review",
+  "validation": "Validation", "approve": "Approve", "triage": "Triage"
+}
+summary_lines = []
+for phase_key, label in SUMMARY_PHASE_LABELS.items():
+  s = summaries.get(phase_key)
+  if s:
+    summary_lines.append(f"- {label}: {s.get('objective', '(no objective)')}")
+    if s.get('key_changes'):
+      for c in s['key_changes'][:3]:
+        summary_lines.append(f"    • {c}")
+    if s.get('findings'):
+      for f_ in s['findings'][:3]:
+        summary_lines.append(f"    • {f_}")
+    if s.get('verdict') and s['verdict'] != 'n/a':
+      summary_lines.append(f"    Verdict: {s['verdict']}  Full: {s.get('artifact_ref', '(unknown)')}")
+
+if summary_lines:
+  summary_block = (
+    "### Prior phase summaries (fast path — read full artifacts if you need more detail)\n\n"
+    + "\n".join(summary_lines)
+    + "\n\nIf any summary above is missing or insufficient, read the corresponding full artifact from disk before proceeding.\n\n"
+  )
+else:
+  summary_block = ""
+```

package/dist/forge-payload/meta/workflows/_fragments/event-emission-schema.md

@@ -0,0 +1,73 @@
+# Fragment: Event Emission Schema
+
+<!-- Canonical contract: subagents write judgement-only SUMMARY files; the
+     orchestrator stitches runtime telemetry + judgement into the canonical
+     event and emits it. Referenced by meta-orchestrate.md and meta-fix-bug.md.
+
+     PLAN-11 / SLICE-2 (2026-05-14): the LLM no longer hand-builds event JSON.
+     Runtime facts (model, provider, eventId, timestamps, iteration, tokens)
+     are owned by the orchestrator, never the subagent. The subagent only
+     produces judgement and lets the orchestrator complete the record. -->
+
+## Who writes what
+
+| Actor              | Owns (writes)                                                                                   | Never touches |
+|--------------------|-------------------------------------------------------------------------------------------------|---------------|
+| **Subagent (LLM)** | judgement fields: `verdict`, `notes`, `findings`, `objective`, `type`                           | `eventId`, `model`, `provider`, `startTimestamp`, `endTimestamp`, `durationMinutes`, `iteration`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `tokenSource` |
+| **Orchestrator**   | everything else — composes the canonical event from runtime telemetry + the subagent's SUMMARY  | the judgement fields themselves (copies them through unchanged) |
+
+The LLM is the wrong actor for runtime facts: it has no privileged access to
+the model/provider it ran under, the wall clock at spawn time, or the token
+counts reported by the runtime stream. Every LLM guess at these fields is
+wrong by construction.
+
+## What the subagent does
+
+After completing its phase, the subagent writes one file:
+
+```
+.forge/cache/{PHASE}-SUMMARY.json
+```
+
+Examples: `PLAN-SUMMARY.json`, `REVIEW-PLAN-SUMMARY.json`,
+`IMPLEMENT-SUMMARY.json`, `REVIEW-CODE-SUMMARY.json`, `COMMIT-SUMMARY.json`.
+
+The SUMMARY contains judgement only. Required keys are phase-specific
+(see `forge/schemas/phase-summary.schema.json` for the exact shape per
+phase) but typically include `verdict`, `notes`, and any `findings`
+the phase produces. The subagent **must not** include runtime fields —
+adding `model`, `provider`, timestamps, or token counts to the SUMMARY is
+ignored at best and rejected at worst.
+
+The subagent **does not** call `store-cli emit` for phase events. That
+shell-out is reserved for the orchestrator.
+
+## What the orchestrator does
+
+After the subagent returns, the orchestrator constructs the event from:
+
+1. **Runtime telemetry** captured during the subagent run:
+   `model`, `provider`, token usage (`inputTokens`, `outputTokens`,
+   `cacheReadTokens`, `cacheWriteTokens`, `tokenSource: "reported"`).
+2. **Known task context** the orchestrator already tracks for run-task:
+   `taskId`, `sprintId`, `phase`, `iteration`.
+3. **Bracketed wall times** the orchestrator records around the subagent
+   call: `startTimestamp`, `endTimestamp`, `durationMinutes`.
+4. **Judgement blob** read from `{PHASE}-SUMMARY.json`: `verdict`, `notes`,
+   `findings`, etc.
+
+The orchestrator then emits via:
+
+```
+node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{complete-event-json}'
+```
+
+## Why no example record here
+
+This fragment intentionally contains **no hardcoded example model strings,
+provider names, or timestamps**. Such examples were the historical source of
+LLM hallucination — subagents would copy the example verbatim ("the model
+is claude-sonnet-4-6 because the workflow says so") even when running on a
+completely different runtime. The schema lives at
+`.forge/schemas/event.schema.json`; consult it directly when verifying a
+field set.

package/dist/forge-payload/meta/workflows/_fragments/finalize.md

@@ -0,0 +1,13 @@
+## Finalize: Subagent Closure
+
+Before returning, every subagent MUST:
+
+1. Write any phase-specific summary the workflow body requires (e.g. PLAN.md, CODE_REVIEW.md).
+2. Confirm `task.status` reflects the phase outcome (via `store-cli update-status` if applicable).
+3. Return cleanly.
+
+**Subagents MUST NOT write token-usage sidecars.** Token telemetry is owned by the orchestrator, which captures provider-reported usage from the runtime as the subagent runs and emits the canonical event (with `provider`, `model`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `tokenSource: "reported"`) on the subagent's behalf.
+
+If the runtime does not surface usage (rare), the orchestrator emits the event **without** the token fields — never with placeholder zeros or a `"missing"` marker. Honest absence beats misleading presence.
+
+The `eventId` is passed by the orchestrator in the subagent prompt and is used only for non-token writes (e.g. `set-summary`, `update-status` history).

package/dist/forge-payload/meta/workflows/_fragments/friction-emit.md

@@ -0,0 +1,73 @@
+<!-- Canonical Friction Emit fragment.
+     Referenced from meta-implement.md, meta-fix-bug.md, meta-validate.md,
+     meta-plan-task.md, and meta-orchestrate.md. /forge:enhance --phase 2
+     greps generated workflows for `## Friction Emit` to discover the channel.
+
+     PLAN-11 / SLICE-2 (2026-05-14): friction is now recorded via the
+     `friction-emit.cjs` tool which appends judgement-only records to
+     `.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator drains this
+     file at phase-end, stamps runtime attribution (model/provider/usage/
+     timestamps/eventId) onto each record, and emits the events. The LLM
+     never hand-builds a friction event JSON. -->
+
+# Friction Emit (Fragment)
+
+When the persona detects skill friction during the workflow — 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 —
+record a judgement-only friction signal. The orchestrator drains the
+signals and emits the corresponding events so `/forge:enhance --phase 2`
+can act on them.
+
+## Trigger conditions
+
+Set `--issue` on the emitted record to one of the following tokens:
+
+| 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.   |
+
+Emit one record per distinct friction signal — do not coalesce multiple
+findings into a single record.
+
+## Judgement-only contract
+
+The friction recorder accepts only judgement fields. Runtime-attribution
+fields (`model`, `provider`, `eventId`, timestamps, token counts) are
+**rejected** if passed — they belong to the orchestrator and are stamped on
+at drain time.
+
+```sh
+node "$FORGE_ROOT/tools/friction-emit.cjs" \
+  --workflow {workflow-key} \
+  --persona  {persona-noun} \
+  --issue    skill_unused \
+  [--subkind  skill_unused] \
+  [--evidence '{"trajectory_excerpt":"...","tool_errors":["..."],"retrieval_score":0.0,"skillId":"..."}']
+```
+
+Required flags: `--workflow`, `--persona`, `--issue`.
+Optional flags: `--subkind` (frozen enum
+`skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant`
+or experimental `^x_[a-z_]+$`), `--evidence` (JSON object with
+`trajectory_excerpt`, `tool_errors`, `retrieval_score` (0..1), `skillId`).
+
+The tool appends one line of judgement-only JSON to
+`.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator reads this file
+after the phase completes, stamps each record with the captured runtime
+attribution (model, provider, usage, wall times, eventId), and emits the
+resulting events via `store-cli emit`.
+
+## Per-workflow values
+
+| Workflow         | `workflow` | `persona`     | `phase`      |
+|------------------|------------|---------------|--------------|
+| meta-implement   | implement  | engineer      | implement    |
+| meta-fix-bug     | fix-bug    | bug-fixer     | fix-bug      |
+| meta-validate    | validate   | qa-engineer   | validate     |
+| meta-plan-task   | plan-task  | architect     | plan         |
+| meta-orchestrate | orchestrate| orchestrator  | orchestrate  |

package/dist/forge-payload/meta/workflows/_fragments/progress-reporting.md

@@ -0,0 +1,38 @@
+# Fragment: Progress Reporting
+
+<!-- Canonical progress log format and store-cli commands for orchestrator subagents.
+     Referenced by meta-orchestrate.md and meta-fix-bug.md. -->
+
+Each subagent writes progress entries to a transient log file that the
+orchestrator monitors in real time.
+
+**Log path:** `.forge/store/events/{sprintId}/progress.log`
+
+**Format per line:**
+
+```
+{ISO_TIMESTAMP}|{agent_name}|{banner_key}|{status}|{detail}
+```
+
+| Field | Format | Example |
+|-------|--------|---------|
+| `ISO_TIMESTAMP` | ISO 8601 UTC | `2026-04-16T14:15:23Z` |
+| `agent_name` | `{taskId}:{persona_noun}:{phase.role}:{iteration}` | `FORGE-S09-T01:engineer:plan:1` |
+| `banner_key` | Banner identity key from BANNER_MAP | `forge` |
+| `status` | One of: `start`, `progress`, `done`, `error` | `progress` |
+| `detail` | Free text (no pipe characters) | `Reading codebase` |
+
+**Writing entries:** Use `store-cli progress`:
+
+```
+node "$FORGE_ROOT/tools/store-cli.cjs" progress {sprintId} {agentName} {bannerKey} {status} "detail text"
+```
+
+**Monitoring:** The orchestrator starts a Monitor on the progress log before
+spawning each subagent and stops it after the subagent returns.
+
+**Clearing:** The orchestrator clears the progress log at task start:
+
+```
+node "$FORGE_ROOT/tools/store-cli.cjs" progress-clear {sprintId}
+```

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

@@ -0,0 +1,39 @@
+# 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 and
+     FORGE-S22-T02 (read-aliases). -->
+
+store-cli verbs: `read` | `list` | `write` | `emit` | `update-status` | `set-summary` | `set-bug-summary` | `describe` | `template` | `nlp` | `query` | `delete`
+
+Read-aliases (FORGE-S22-T02): `get` | `get-task` | `get-bug` | `get-sprint` | `get-summary` | `get-bug-summary`
+
+Notes for subagents:
+
+- **`read`** is the canonical "fetch one record" verb. The aliases
+  `get <entity> <id>`, `get-task <id>`, `get-bug <id>`, `get-sprint <id>`
+  are accepted and delegate byte-equally to `read`. Prefer the canonical
+  `read` form in new code; aliases exist to reduce friction when an agent
+  reaches for REST-style verbs.
+- **`get-summary <taskId> <phase>`** and **`get-bug-summary <bugId> <phase>`**
+  are direct summary readers — they extract `record.summaries[phase]` and
+  exit 1 if the phase is absent. They are NOT write verbs (do not confuse
+  with `set-summary` / `set-bug-summary`).
+- **`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.
+- If you supply an unknown verb, entity type, enum value, or field name,
+  store-cli appends a **Did you mean?** suggestion to the error message.
+  Suggestions use Levenshtein distance (≤ 2) and a curated drift map for
+  common agent misconceptions (e.g., `completed` → `committed`,
+  `task` → `taskId`, `set` → `set-summary`). See FORGE-S22-T03.

package/dist/forge-payload/meta/workflows/meta-approve.md

@@ -0,0 +1,119 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+audience: subagent
+phase: approve
+context:
+  architecture: true
+  prior_summaries: all
+  persona: summary
+  master_index: false
+  diff_mode: false
+deps:
+  personas: [architect]
+  skills: [architect, generic]
+  templates: []
+  sub_workflows: []
+  kb_docs: [architecture/stack.md]
+  config_fields: [paths.engineering]
+---
+
+# 🗻 Meta-Workflow: Approve Task
+
+## Purpose
+
+The Architect gives final sign-off on a completed task after Supervisor approval. This is the last gate before commit.
+
+## 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
+
+```
+
+0. Pre-flight Gate Check:
+   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
+   - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase approve --{entity_kind} {record_id}`
+   - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
+   - Exit 2 (misconfiguration) → print stderr and HALT.
+   - Exit 0 → continue.
+1. Load Context:
+   - Read task prompt
+   - Read final PLAN.md
+   - Read approved CODE_REVIEW.md
+   - Read PROGRESS.md
+
+2. Architectural Review:
+   - Verify implementation aligns with project architecture
+   - Check for cross-cutting concerns (impact on other modules)
+   - Assess operational impact (deployment changes, migrations)
+
+3. Sign Off:
+   - 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. **Task mode:** it reads `task.status === "approved"` set in step 4. **Bug mode:** it reads `bug.summaries.approve.verdict === "approved"` set in step 5. The `**Verdict:**` line is a human breadcrumb only.
+
+4. Finalize:
+   - Transitions:
+     - **Task mode** — Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status approved`. The status IS the verdict signal for task-mode commit gate (`STATUS_SOURCE` in `read-verdict.cjs`).
+     - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.approve.verdict` written in step 5 below (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`). Writing `bug.status` here — especially writing `approved` or `verified` — violates `meta-fix-bug.md § Iron Laws #2` and is the trap that produced the FORGE-BUG-002 regression.
+   - **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.
+
+5. Emit Summary Sidecar:
+   - Write `APPROVE-SUMMARY.json` to the record's directory with the following shape:
+     ```json
+     {
+       "objective":   "<one sentence — what this approval covered>",
+       "findings":    ["<up to 12 bullets, 200 chars each — architectural notes, deployment concerns>"],
+       "verdict":     "<approved | revision>",
+       "written_at":  "<current ISO 8601 timestamp>",
+       "artifact_ref":"ARCHITECT_APPROVAL.md"
+     }
+     ```
+   - Call (task mode) — optional for tasks, since `task.status` is the canonical signal:
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} approve \
+       engineering/sprints/{sprint}/{task}/APPROVE-SUMMARY.json
+     ```
+     Or (bug mode) — REQUIRED for bugs, this is the canonical verdict signal:
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} approve \
+       engineering/bugs/{bugDir}/APPROVE-SUMMARY.json
+     ```
+   - In bug mode, if the set-bug-summary call exits non-zero, fix the sidecar JSON and retry. Do not return without a valid summary — the downstream commit gate has no other way to read the approval verdict.
+```
+
+## Generation Instructions
+
+- **Workflow Structure:** The generated `approve_task.md` must follow the strict "Algorithm" block format.
+- **Verdict Detection:** Instruct the architect to write a literal `**Verdict:** [Approved | Revision Required]` line in ARCHITECT_APPROVAL.md for human readability. Downstream gates read `task.status` via read-verdict.cjs, not this markdown — but the line remains a useful breadcrumb for operators reviewing artifacts.
+- **Context Isolation:** Forbid inline execution of complex architectural analysis; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Reference project's architecture docs.
+  - Include project-specific deployment concerns.
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.