@entelligentsia/forgecli 1.0.3 → 1.0.10

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

@@ -32,14 +32,29 @@ Notes for subagents:
   The three-arg form `update-status task {taskId} {value}` is WRONG and will
   error. Always include `status` between the id and the value.
 - **`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`.
+- **`set-summary <id> <phase>`** / **`set-bug-summary <id> <phase>`** link a
+  phase summary onto the entity record. The JSON-file argument is **optional**:
+  when omitted, the sidecar is auto-resolved from the record's `path` plus the
+  canonical phase→filename map (so `set-summary {taskId} validation` just works).
+  Never pass a hand-built `engineering/sprints/.../…-SUMMARY.json` path. Do not
+  inline summaries into the entity via `write`.
 - **Artifact I/O:** Use `forge_artifact` for ALL phase artifact reads and writes
   (PLAN.md, PROGRESS.md, *-SUMMARY.json, CODE_REVIEW.md, etc.). Never construct
   artifact file paths manually — the tool resolves paths from entity IDs and
   validates JSON summary schemas on write. After writing a summary JSON via
-  `forge_artifact`, link it to the store record via `forge_store set-summary`.
+  `forge_artifact`, link it to the store record via `forge_store set-summary {id} {phase}` (no path).
   Example: `forge_artifact({ command:"write", entity:"task", entityId:"{taskId}", artifact:"progress", content:"..." })`
+- **Artifact addressing (canonical) — never reconstruct a path.** Address an
+  artifact by `(entity, entityId, kind)` via `forge_artifact`, or read the
+  entity's `path` field from the store record. The on-disk directory is owned by
+  the record's `path`, NOT by any id template. Token glossary:
+  - `{sprintId}` / `{taskId}` / `{bugId}` — the **store record filenames**
+    (`.forge/store/<kind>s/<id>.json`); deterministic and safe to use as IDs.
+  - `{sprint}` / `{task}` / `{bug}` — runtime path-template substitutions used by
+    the **preflight gate**, derived from the record's `path` (not the bare ID).
+  - The engineering artifact directory always comes from `record.path`.
+  These spellings are parsed literally by tools (`preflight-gate.cjs`,
+  `collate.cjs`) — do not invent new spellings or rename them in prose.
 - 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,

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

@@ -98,15 +98,14 @@ deps:
        "artifact_ref":"ARCHITECT_APPROVAL.md"
      }
      ```
-   - Call (task mode) — optional for tasks, since `task.status` is the canonical signal:
+   - Call (task mode) — optional for tasks, since `task.status` is the canonical signal.
+     The sidecar path is auto-resolved from the record's `path` — never pass it:
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} approve \
-       engineering/sprints/{sprint}/{task}/APPROVE-SUMMARY.json
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} approve
      ```
      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
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} approve
      ```
    - 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.
 ```

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

@@ -67,7 +67,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 4. Finalize:
    - **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.
-   - Write `WRITEBACK-SUMMARY.json` to the sprint directory (`engineering/sprints/{sprintId}/`) with the following shape:
+   - Write `WRITEBACK-SUMMARY.json` to the sprint's artifact directory — use the sprint record's `path` field (read it from the store), not a reconstructed `engineering/sprints/{sprintId}/` template — with the following shape:
      ```json
      {
        "objective":   "<one sentence — what views were regenerated>",

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

@@ -57,9 +57,8 @@ deps:
 
 1. Load Context:
    - Read the record manifest (task or bug, per entity_kind).
-   - Read ARCHITECT_APPROVAL.md from the record's artifact directory:
-     - Task mode: `engineering/sprints/{sprint}/{task}/ARCHITECT_APPROVAL.md`
-     - Bug mode:  `engineering/bugs/{bugDir}/ARCHITECT_APPROVAL.md`
+   - Read ARCHITECT_APPROVAL.md by kind — never construct the path:
+     `forge_artifact({ command:"read", entity:"{entity_kind}", entityId:"{record_id}", artifact:"architect-approval" })`
 
 2. Staging:
    - Stage all record-related artifacts and the code changes:

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

@@ -92,9 +92,10 @@ deps:
      JSON shape: `{"objective":"<one sentence>", "key_changes":["<up to 12 bullets>"], "verdict":"n/a", "written_at":"<ISO 8601>", "artifact_ref":"PROGRESS.md"}`
      The tool validates required fields automatically — fix and retry if it rejects.
    - Then link sidecar to store (task mode):
-     `forge_store({ command:"set-summary", args:["{taskId}", "implementation", "engineering/sprints/{sprint}/{task}/IMPLEMENTATION-SUMMARY.json"] })`
+     `forge_store({ command:"set-summary", args:["{taskId}", "implementation"] })`
      Or (bug mode):
-     `forge_store({ command:"set-bug-summary", args:["{bugId}", "implementation", "engineering/bugs/{bugDir}/IMPLEMENTATION-SUMMARY.json"] })`
+     `forge_store({ command:"set-bug-summary", args:["{bugId}", "implementation"] })`
+     The sidecar path is auto-resolved from the record's `path` — never pass it.
 ```
 
 <!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->

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

@@ -561,28 +561,32 @@ for each task in dependency_sorted(tasks):
       /compact
       continue
 
-    # --- Review phase: detect verdict via parse-verdict.cjs (see Verdict Detection below) ---
-    # The CLI returns exit 0/1/2 for approved/revision/unknown. Never pattern-match
-    # the **Verdict:** line manually — the closed vocabulary lives in the tool.
+    # --- Review phase: detect verdict via read-verdict.cjs (see Verdict Detection below) ---
+    # Verdicts come from the STORE record (phase summaries / task.status), NOT from a
+    # markdown review artifact — the orchestrator never constructs an artifact path.
+    # stdout is one of: approved | revision | n/a | unknown. Never pattern-match a
+    # **Verdict:** line — the closed vocabulary lives in the tool.
     verdict_result = run_bash(
-      f'node "$FORGE_ROOT/tools/parse-verdict.cjs" {review_artifact_path(phase, task)}'
+      f'node "$FORGE_ROOT/tools/read-verdict.cjs" --phase {phase.role} --task {task_id}'
     )
-    if verdict_result.exit_code == 0:
+    verdict_token = verdict_result.stdout.strip()
+    if verdict_token == "approved":
       verdict = "Approved"
-    elif verdict_result.exit_code == 1:
+    elif verdict_token == "revision":
       verdict = "Revision Required"
     else:
-      # exit 2: malformed, missing verdict line, or missing artifact. Never guess.
+      # "n/a" / "unknown" (no verdict recorded) or exit 2 (record not found / bad args).
+      # Never guess.
       print(f"  ⚠ {task_id}  {phase.role}  — verdict_malformed, escalating\n")
       emit_event(task, phase, action="verdict_malformed",
-                 notes=f"parse-verdict exit={verdict_result.exit_code}")
+                 notes=f"read-verdict stdout='{verdict_token}' exit={verdict_result.exit_code}")
       # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
       run_bash(f'node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {task_id} status escalated')
       emit_event(task, phase, eventId=event_id, iteration=iteration,
                  action="escalated", verdict="escalated",
-                 notes="verdict_malformed: review artifact missing or verdict line unparseable")
-      print(f"  ⚠ Task {task_id} escalated: verdict_malformed — review artifact missing or verdict line unparseable\n")
-      print(f"  Review artifact: {review_artifact_path(phase, task)}\n")
+                 notes="verdict_malformed: no verdict recorded in the phase summary / record")
+      print(f"  ⚠ Task {task_id} escalated: verdict_malformed — no verdict recorded for {phase.role}\n")
+      print(f"  Inspect with: node \"$FORGE_ROOT/tools/read-verdict.cjs\" --phase {phase.role} --task {task_id}\n")
       print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
       break
 
@@ -604,7 +608,7 @@ for each task in dependency_sorted(tasks):
                    action="escalated", verdict="escalated",
                    notes="max iterations reached")
         print(f"  ⚠ Task {task_id} escalated: max iterations reached\n")
-        print(f"  Review artifact: {review_artifact_path(phase, task)}\n")
+        print(f"  Inspect with: node \"$FORGE_ROOT/tools/read-verdict.cjs\" --phase {phase.role} --task {task_id}\n")
         print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
         break
         break                               # stop processing this task
@@ -616,7 +620,7 @@ for each task in dependency_sorted(tasks):
       print(f"[checkpoint] task={task_id} sprint={sprint_id} phase_index={i} iterations={iteration_counts}")
       /compact
 
-    # No `else:` branch needed — parse-verdict.cjs already exhausts the
+    # No `else:` branch needed — read-verdict.cjs already exhausts the
     # possibilities (approved | revision | verdict_malformed), and the
     # malformed case is handled above before this if/elif chain.
 ```
@@ -676,45 +680,35 @@ Examples:
 ## Verdict Detection
 
 After each review phase completes, the orchestrator MUST read the verdict
-before branching. Do not infer the verdict from conversation context alone —
-always read the artifact.
+before branching. Do not infer the verdict from conversation context alone, and
+**never construct or read a markdown artifact path** to find it — the verdict
+lives in the **store record** (the phase summary written by `set-summary`, or
+`task.status` for the approve phase).
 
-| Phase role    | Artifact to read                                                          | Verdict field                |
-|---------------|---------------------------------------------------------------------------|------------------------------|
-| `review-plan` | `{engineering}/sprints/{sprintDir}/{taskDir}/PLAN_REVIEW.md`              | Line matching `**Verdict:**` |
-| `review-code` | `{engineering}/sprints/{sprintDir}/{taskDir}/CODE_REVIEW.md`              | Line matching `**Verdict:**` |
-| `validate`    | `{engineering}/sprints/{sprintDir}/{taskDir}/VALIDATION_REPORT.md`        | Line matching `**Verdict:**` |
-
-The verdict line format is:
-
-```
-**Verdict:** Approved
-```
-or
-```
-**Verdict:** Revision Required
-```
-
-**Parse the verdict via `parse-verdict.cjs`** — do NOT pattern-match the
-line manually. The tool enforces a closed verdict vocabulary so typos, case
-drift, and reviewer prose cannot cause silent misclassification:
+**Read the verdict via `read-verdict.cjs`** — addressed by entity ID and phase
+role, never by file path. The tool sources the verdict from the record and
+enforces a closed vocabulary so typos, case drift, and reviewer prose cannot
+cause silent misclassification:
 
 ```
 FORGE_ROOT = resolve_forge_root()
-result = run_bash(f'node "$FORGE_ROOT/tools/parse-verdict.cjs" {artifact_path}')
-# exit 0 → approved   (stdout "approved")
-# exit 1 → revision   (stdout "revision")
-# exit 2 → unknown/malformed/missing (stdout "unknown")
+result = run_bash(f'node "$FORGE_ROOT/tools/read-verdict.cjs" --phase {phase.role} --task {task_id}')
+# stdout "approved" → approved
+# stdout "revision" → revision
+# stdout "n/a" | "unknown" → no verdict recorded (treat as malformed; do NOT guess)
+# exit 2 → record not found / invalid args (treat as malformed)
 ```
 
-Recognised values (case-insensitive):
+Branch on the **stdout token** (exit 1 bundles both `revision` and the
+no-verdict cases, so the token is authoritative). Recognised verdict values:
 
-- **approved** — `Approved`, `Approve`, `[Approved]`
-- **revision** — `Revision Required`, `Revision`, `Needs Revision`, `Changes Requested`
+- **approved** — written as `verdict: "approved"` in the phase summary (or `task.status == approved` for the approve phase).
+- **revision** — `verdict: "revision"`.
 
-Anything else — including free-form prose, missing bold markers, a missing
-verdict line, or a missing artifact — yields exit 2. Do NOT treat unknown
-as approved or revision; halt the loop and escalate via `verdict_malformed`.
+Anything else — `n/a`, `unknown`, a missing summary, or a missing record —
+must NOT be treated as approved or revision; halt the loop and escalate via
+`verdict_malformed`. (In bug mode pass `--bug {bug_id}`; `read-verdict.cjs`
+applies the bug-specific phase→summary map.)
 
 ## Escalation Procedure
 
@@ -750,8 +744,8 @@ Grammar (one directive per line):
   `in [v1, v2, ...]`. Fields are dotted paths against the store record, e.g.
   `task.status`.
 - `forbid <field> <op> <value>` — predicate must NOT hold.
-- `after <phase> = <approved|revision>` — predecessor phase's review artifact
-  must carry the stated verdict (parsed by `parse-verdict.cjs`).
+- `after <phase> = <approved|revision>` — predecessor phase's stored verdict
+  must match (read from the record by `read-verdict.cjs`, not from markdown).
 
 ```gates phase=plan
 forbid task.status == committed
@@ -849,7 +843,7 @@ is a violation of the Iron Laws.
 - Subagent empty/crash/timeout response: retry once with simplified prompt
   (strip summary and architecture blocks). Escalate on second failure.
   See Subagent Response Validation in the Execution Algorithm.
-- Subagent non-zero exit code (not parse-verdict): same as above — retry
+- Subagent non-zero exit code (not read-verdict): same as above — retry
   once, escalate on second failure. The crash reason is captured in the
   escalation event notes.
 - Verdict malformed or missing: escalate to human immediately. Never guess.

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

@@ -130,8 +130,8 @@ deps:
    - Call:
      ```
      forge_store({ command:"set-bug-summary", entity:"bug",
-                   id:"{bugId}", phase:"triage",
-                   file:"engineering/bugs/{bugDir}/TRIAGE-SUMMARY.json" })
+                   id:"{bugId}", phase:"triage" })
+     // sidecar path auto-resolved from the bug record's `path` — never pass it
      ```
    - If the set-bug-summary call exits non-zero, fix the sidecar JSON
      and retry (up to 3 attempts per the Store-Write Verification rule).

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

@@ -110,10 +110,9 @@ deps:
        "artifact_ref":"VALIDATION_REPORT.md"
      }
      ```
-   - Call:
+   - Call (the sidecar path is auto-resolved from the task record's `path` — never pass it):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {task_id} validation \
-       engineering/sprints/{sprint}/{task}/VALIDATION-SUMMARY.json
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {task_id} validation
      ```
    - If set-summary exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```

package/dist/forge-payload/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "forge",
-  "version": "1.0.3",
+  "version": "1.0.10",
   "description": "Self-enhancing AI software development lifecycle — generates project-specific SDLC instances from meta-definitions",
   "license": "MIT",
   "author": {

package/dist/forge-payload/.schemas/_defs/locator.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/_defs/locator.schema.json",
+  "title": "ArtifactLocator",
+  "description": "Backend-agnostic artifact locator (ADR doc/decisions/artifact-resolution-abstraction.md, issue #111 Phase 3). Single-sourced under _defs/ and $ref'd from task/bug/sprint schemas. `record.path` remains the required back-compat alias during migration; `locator` is the forward-looking form so a non-fs backend (s3/cms/db) is a drop-in. `ref` is an opaque, backend-specific reference (a URI is a fine encoding): fs → 'engineering/sprints/<dir>/<task>/', s3 → 's3://bucket/key', cms → 'cms://collection/<id>', db → 'blob:<uuid>'.",
+  "type": "object",
+  "required": ["backend", "ref"],
+  "properties": {
+    "backend": { "type": "string", "description": "Storage backend identifier — e.g. fs, s3, gcs, azure, cms, db." },
+    "ref":     { "type": "string", "description": "Opaque backend-specific reference (URI-encodable)." }
+  },
+  "additionalProperties": false
+}

package/dist/forge-payload/.schemas/bug.schema.json

@@ -11,6 +11,7 @@
     "severity":            { "type": "string", "enum": ["critical", "major", "minor"] },
     "status":              { "type": "string", "enum": ["reported", "triaged", "in-progress", "fixed"] },
     "path":                { "type": "string" },
+    "locator":             { "$ref": "_defs/locator.schema.json" },
     "rootCauseCategory": {
       "type": "string",
       "enum": ["validation", "auth", "business-rule", "data-integrity", "race-condition", "integration", "configuration", "regression"]

package/dist/forge-payload/.schemas/enum-catalog.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.0.2",
-  "generated": "2026-05-28",
+  "version": "1.0.10",
+  "generated": "2026-05-31",
   "note": "Authoritative enum catalog. Source: build-enum-catalog.cjs. Regenerate via node forge/tools/build-manifest.cjs.",
   "enums": {
     "task.status": [

package/dist/forge-payload/.schemas/migrations.json

@@ -1,4 +1,67 @@
 {
+  "1.0.9": {
+    "version": "1.0.10",
+    "date": "2026-05-31",
+    "notes": "v1.0.10 — set-summary self-resolve hardening. When the JSON file is omitted, set-summary/set-bug-summary resolve the CANONICAL sidecar name (e.g. VALIDATION-SUMMARY.json) from the phase→kind map. If that file is missing but a near-name summary sidecar exists in the same dir (e.g. an agent wrote VALIDATE-SUMMARY.json via the Write tool instead of forge_artifact's canonical name), the error now surfaces the near-name file and points at the canonical write path (forge_artifact artifact:\"<kind>\"), instead of a silent 'file not found' dead-end. Surfaced by cartographer CART-S01-T01 validate, where the QA subagent wrote a non-canonical sidecar and the verdict never reached the store (orchestrator then correctly escalated via read-verdict). No behavior change when the canonical file is present.",
+    "target": "tools:store-cli",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": ["Run /forge:update to copy the updated tools into your project."]
+  },
+  "1.0.8": {
+    "version": "1.0.9",
+    "date": "2026-05-31",
+    "notes": "v1.0.9 — store-cli suggestion drift-map: add create→write. Agents reach for REST-style `create <entity>`, but store-cli has no `create` verb (records are written with `write`), and create→write is beyond Levenshtein ≤2 so only the curated drift-map can surface it. `store-cli create sprint` now emits `Unknown command: create (Did you mean \"write\"?)`. Pure error-message UX improvement; no behavior change for valid commands. Observed on cartographer sprint-init dogfooding.",
+    "target": "tools:store-cli",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": ["Run /forge:update to copy the updated tools into your project."]
+  },
+  "1.0.7": {
+    "version": "1.0.8",
+    "date": "2026-05-31",
+    "notes": "v1.0.8 — artifact-resolution Phase 4 (issue #111). ArtifactStore gains a backend registry: artifactStore.register(backend, impl) and per-call routing by the handle's `backend` (default 'fs'). Adding a storage backend is now implementing the six-method interface and registering it — no prompt or call-site changes (the acceptance criterion). Ships MemArtifactImpl, a complete synchronous in-memory reference backend, as the canonical template for real S3/CMS/DB providers. Per the ADR sync constraint, a networked impl is sync-bound for in-process callers and reachable async-internally only through the forge-cli subprocess surface — so no live remote backend is bundled. tools-only; no schema, workflow, or store-layout changes.",
+    "target": "tools:artifact-store",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": ["Run /forge:update to copy the updated tools into your project."]
+  },
+  "1.0.6": {
+    "version": "1.0.7",
+    "date": "2026-05-31",
+    "notes": "v1.0.7 — artifact-resolution Phase 3 (issue #111). Introduces the ArtifactStore/FsArtifactImpl provider seam (tools/artifact-store.cjs), mirroring the store.cjs Store/FSImpl pattern: a backend-agnostic, synchronous facade (read/write/exists/url/list/delete) delegating to a swappable impl, default-wired to the filesystem. artifact.cjs is now a thin CLI over the facade and gains exists/url/delete subcommands; entity-dir resolution moved into artifact-store.cjs (re-exported for back-compat). Records gain an optional backend-agnostic locator {backend,ref} (schemas/_defs/locator.schema.json, $ref'd from task/bug/sprint); record.path stays REQUIRED as the read-time alias (the resolver derives {backend:'fs',ref:path} when locator is absent), so legacy records work unchanged and no store rewrite is forced. Concepts docs (task.md/bug.md) updated. Materialization of locator into stored records is deferred — the alias covers it. No FSM/lifecycle or store-layout changes.",
+    "target": "tools:artifact,tools:artifact-store,schemas:task,schemas:bug,schemas:sprint",
+    "regenerate": ["tools", "schemas"],
+    "breaking": false,
+    "manual": ["Run /forge:update to copy the updated tools and schemas into your project."]
+  },
+  "1.0.5": {
+    "version": "1.0.6",
+    "date": "2026-05-31",
+    "notes": "v1.0.6 — artifact-resolution Phase 2 (issue #111). (1) The orchestrator's Verdict Detection no longer reads a markdown review artifact via the removed parse-verdict.cjs — meta-orchestrate.md was the last reference to that deleted tool, which would have crashed the verdict step. It now reads the verdict from the store record via read-verdict.cjs (--phase <role> --task|--bug <id>), branching on the stdout token; no artifact path is constructed. (2) Removed the stale verdict-source table that hard-coded {sprintDir}/{taskDir} markdown paths. (3) meta-commit reads ARCHITECT_APPROVAL by kind via forge_artifact instead of a built path; meta-collate anchors WRITEBACK-SUMMARY on the sprint record's path. (4) Documented canonical artifact addressing + the placeholder-token glossary in the store-cli-verbs fragment (rename-unsafe: tools parse the literal tokens). No schema or store-layout changes.",
+    "target": "workflows:orchestrate_task,workflows:commit,workflows:collate",
+    "regenerate": ["workflows:orchestrate_task", "workflows:commit", "workflows:collate"],
+    "breaking": false,
+    "manual": ["Run /forge:update to copy the updated workflows into your project."]
+  },
+  "1.0.4": {
+    "version": "1.0.5",
+    "date": "2026-05-31",
+    "notes": "v1.0.5 — artifact-resolution Phase 1 (issue #111). set-summary / set-bug-summary now self-resolve the phase-summary sidecar from the store record's path: the JSON file argument is optional and the call collapses to `set-summary <id> <phase>`. This fixes the 2-arg arity failure (plan-phase set-summary previously exited 1 with Usage) and removes the hand-built `engineering/sprints/{sprint}/{task}/…-SUMMARY.json` paths from the implement/validate/approve/bug-triage workflows, which broke on non-default on-disk layouts. New canonical kind registry tools/lib/artifact-kinds.cjs (ARTIFACT_CATALOG + bug-mode overrides + phase→kind map) is now the single source consumed by artifact.cjs and store-cli.cjs. No schema or store-layout changes; the explicit jsonFile form remains accepted for back-compat.",
+    "target": "tools:store-cli,tools:artifact,tools:artifact-kinds,workflows:implement_plan,workflows:validate_task,workflows:approve_task,workflows:triage",
+    "regenerate": ["tools", "workflows:implement_plan", "workflows:validate_task", "workflows:approve_task", "workflows:triage"],
+    "breaking": false,
+    "manual": ["Run /forge:update to copy the updated tools and workflows into your project."]
+  },
+  "1.0.3": {
+    "version": "1.0.4",
+    "date": "2026-05-30",
+    "notes": "v1.0.4 — two store/path tool fixes. (1) preflight-gate.cjs now derives {sprint}/{task} from the store record's task.path instead of reconstructing sprints/{sprintId}/{taskId}/, fixing false 'artifact missing' halts on projects whose on-disk layout differs from the default (legacy sprint_NN_*/tasks/ trees and tasks/-nested dirs). (2) The store-query NLP path no longer degrades an explicit-ID query into a full-store scan: the parser keeps primary=tasks when a follow-word ('with sprint'/'with feature') accompanies an anchored task ID, and the engine re-routes a stripped anchored ID to its entity and applies a default result cap (new 'truncated' flag) so unbounded listings never dump the whole store. No schema, workflow, or store-layout changes.",
+    "target": "tools:preflight-gate,tools:store-query",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": ["Run /forge:update to copy the updated tools into your project."]
+  },
   "1.0.2": {
     "version": "1.0.3",
     "date": "2026-05-28",

package/dist/forge-payload/.schemas/sprint.schema.json

@@ -20,6 +20,7 @@
     "createdAt":      { "type": "string", "format": "date-time" },
     "completedAt":    { "type": "string", "format": "date-time" },
     "path":           { "type": "string" },
+    "locator":        { "$ref": "_defs/locator.schema.json" },
     "humanEstimates": { "type": "object" },
     "features":       { "type": "array", "items": { "type": "string" } }
   },

package/dist/forge-payload/.schemas/task.schema.json

@@ -19,6 +19,7 @@
       ]
     },
     "path":                 { "type": "string" },
+    "locator":              { "$ref": "_defs/locator.schema.json" },
     "estimate":             { "type": "string", "enum": ["S", "M", "L", "XL"] },
     "dependencies":         { "type": "array", "items": { "type": "string" } },
     "knowledgeUpdates":     { "type": "array" },

package/dist/forge-payload/integrity.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.0.3",
-  "generated": "2026-05-28",
+  "version": "1.0.10",
+  "generated": "2026-05-31",
   "note": "Tamper-evident only. Authoritative source: /forge:update from remote.",
   "files": {
     "commands/add-pipeline.md": "529a2fc01be49815efa2cf1147528827ff1bfc12ce2ac8663b5a3a9781f8682e",
@@ -29,7 +29,7 @@
     "schemas/transitions/bug.json": "27b17da42d1cebffbd4f61ab3dcd432a0017aa71997d548ed80d22c2fc3fad6a",
     "schemas/transitions/sprint.json": "2e0a629396e687b0ca88e1814ac3e35d84533a5d55b25237ab67feddce3c9deb",
     "schemas/transitions/task.json": "4c71849747baa0d585756e57c56325ff6219c078178374e60815dff91e25e3e7",
-    "schemas/enum-catalog.json": "93dc3d1656d9d638c8eaecc14ce66554b63149a4779869e6536cf0e620e5b37b",
+    "schemas/enum-catalog.json": "fe6c4b9d0b326a22ccbe2d2e6b8ea81c4f81ea827b9b46507a214cbeffcd45d3",
     "tools/verify-integrity.cjs": "3ec3c970dd3d7c3001f8f373bcc40556803eadd2fc2afafb14f1c232cba4cc3f"
   }
 }

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

@@ -32,14 +32,29 @@ Notes for subagents:
   The three-arg form `update-status task {taskId} {value}` is WRONG and will
   error. Always include `status` between the id and the value.
 - **`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`.
+- **`set-summary <id> <phase>`** / **`set-bug-summary <id> <phase>`** link a
+  phase summary onto the entity record. The JSON-file argument is **optional**:
+  when omitted, the sidecar is auto-resolved from the record's `path` plus the
+  canonical phase→filename map (so `set-summary {taskId} validation` just works).
+  Never pass a hand-built `engineering/sprints/.../…-SUMMARY.json` path. Do not
+  inline summaries into the entity via `write`.
 - **Artifact I/O:** Use `forge_artifact` for ALL phase artifact reads and writes
   (PLAN.md, PROGRESS.md, *-SUMMARY.json, CODE_REVIEW.md, etc.). Never construct
   artifact file paths manually — the tool resolves paths from entity IDs and
   validates JSON summary schemas on write. After writing a summary JSON via
-  `forge_artifact`, link it to the store record via `forge_store set-summary`.
+  `forge_artifact`, link it to the store record via `forge_store set-summary {id} {phase}` (no path).
   Example: `forge_artifact({ command:"write", entity:"task", entityId:"{taskId}", artifact:"progress", content:"..." })`
+- **Artifact addressing (canonical) — never reconstruct a path.** Address an
+  artifact by `(entity, entityId, kind)` via `forge_artifact`, or read the
+  entity's `path` field from the store record. The on-disk directory is owned by
+  the record's `path`, NOT by any id template. Token glossary:
+  - `{sprintId}` / `{taskId}` / `{bugId}` — the **store record filenames**
+    (`.forge/store/<kind>s/<id>.json`); deterministic and safe to use as IDs.
+  - `{sprint}` / `{task}` / `{bug}` — runtime path-template substitutions used by
+    the **preflight gate**, derived from the record's `path` (not the bare ID).
+  - The engineering artifact directory always comes from `record.path`.
+  These spellings are parsed literally by tools (`preflight-gate.cjs`,
+  `collate.cjs`) — do not invent new spellings or rename them in prose.
 - 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,

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

@@ -103,15 +103,14 @@ The Architect gives final sign-off on a completed task after Supervisor approval
        "artifact_ref":"ARCHITECT_APPROVAL.md"
      }
      ```
-   - Call (task mode) — optional for tasks, since `task.status` is the canonical signal:
+   - Call (task mode) — optional for tasks, since `task.status` is the canonical signal.
+     The sidecar path is auto-resolved from the record's `path` — never pass it:
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} approve \
-       engineering/sprints/{sprint}/{task}/APPROVE-SUMMARY.json
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} approve
      ```
      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
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} approve
      ```
    - 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.
 ```

package/dist/forge-payload/meta/workflows/meta-bug-triage.md

@@ -139,8 +139,8 @@ and the only phase that records the route decision read by the orchestrator
    - Call:
      ```
      forge_store({ command:"set-bug-summary", entity:"bug",
-                   id:"{bugId}", phase:"triage",
-                   file:"engineering/bugs/{bugDir}/TRIAGE-SUMMARY.json" })
+                   id:"{bugId}", phase:"triage" })
+     // sidecar path auto-resolved from the bug record's `path` — never pass it
      ```
    - If the set-bug-summary call exits non-zero, fix the sidecar JSON
      and retry (up to 3 attempts per the Store-Write Verification rule).

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

@@ -72,7 +72,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 4. Finalize:
    - **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.
-   - Write `WRITEBACK-SUMMARY.json` to the sprint directory (`engineering/sprints/{sprintId}/`) with the following shape:
+   - Write `WRITEBACK-SUMMARY.json` to the sprint's artifact directory — use the sprint record's `path` field (read it from the store), not a reconstructed `engineering/sprints/{sprintId}/` template — with the following shape:
      ```json
      {
        "objective":   "<one sentence — what views were regenerated>",

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

@@ -62,9 +62,8 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 1. Load Context:
    - Read the record manifest (task or bug, per entity_kind).
-   - Read ARCHITECT_APPROVAL.md from the record's artifact directory:
-     - Task mode: `engineering/sprints/{sprint}/{task}/ARCHITECT_APPROVAL.md`
-     - Bug mode:  `engineering/bugs/{bugDir}/ARCHITECT_APPROVAL.md`
+   - Read ARCHITECT_APPROVAL.md by kind — never construct the path:
+     `forge_artifact({ command:"read", entity:"{entity_kind}", entityId:"{record_id}", artifact:"architect-approval" })`
 
 2. Staging:
    - Stage all record-related artifacts and the code changes:

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

@@ -96,9 +96,10 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
      JSON shape: `{"objective":"<one sentence>", "key_changes":["<up to 12 bullets>"], "verdict":"n/a", "written_at":"<ISO 8601>", "artifact_ref":"PROGRESS.md"}`
      The tool validates required fields automatically — fix and retry if it rejects.
    - Then link sidecar to store (task mode):
-     `forge_store({ command:"set-summary", args:["{taskId}", "implementation", "engineering/sprints/{sprint}/{task}/IMPLEMENTATION-SUMMARY.json"] })`
+     `forge_store({ command:"set-summary", args:["{taskId}", "implementation"] })`
      Or (bug mode):
-     `forge_store({ command:"set-bug-summary", args:["{bugId}", "implementation", "engineering/bugs/{bugDir}/IMPLEMENTATION-SUMMARY.json"] })`
+     `forge_store({ command:"set-bug-summary", args:["{bugId}", "implementation"] })`
+     The sidecar path is auto-resolved from the record's `path` — never pass it.
 ```
 
 <!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->