@entelligentsia/forgecli 1.0.3 → 1.0.10

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

@@ -566,28 +566,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
 
@@ -609,7 +613,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
@@ -621,7 +625,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.
 ```
@@ -681,45 +685,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
 
@@ -755,8 +749,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
@@ -854,7 +848,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/meta/workflows/meta-validate.md

@@ -115,10 +115,9 @@ The Supervisor performs a final validation of the implementation against the acc
        "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/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/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/structure-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.0.2",
-  "generatedAt": "2026-05-28T05:59:32.606Z",
+  "version": "1.0.10",
+  "generatedAt": "2026-05-31T03:19:45.318Z",
   "generatedByTool": "build-manifest.cjs",
   "namespaces": {
     "personas": {
@@ -110,6 +110,7 @@
       "logicalKey": "schemas",
       "dir": ".forge/schemas",
       "files": [
+        "_defs/locator.schema.json",
         "_defs/phaseSummary.schema.json",
         "bug.schema.json",
         "collation-state.schema.json",

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/tools/artifact-store.cjs

@@ -0,0 +1,242 @@
+'use strict';
+
+// ── ArtifactStore — backend-agnostic artifact provider ───────────────────────
+//
+// Mirrors the store.cjs `Store`/`FSImpl` pattern (ADR
+// `doc/decisions/artifact-resolution-abstraction.md`, issue #111 Phase 3):
+// a backend-agnostic facade delegating to a swappable, SYNCHRONOUS impl,
+// default-wired to the filesystem, impl exported for substitution.
+//
+//   class ArtifactStore { read|write|exists|url|list|delete(handle) → impl }
+//   class FsArtifactImpl { engineering/ files }
+//   module.exports = new ArtifactStore(new FsArtifactImpl())
+//   module.exports.FsArtifactImpl = FsArtifactImpl   // swap for S3Impl / CmsImpl / DbBlobImpl
+//
+// A `handle` is the logical address (entityType, entityId, artifactKind) — never
+// a path. The fs impl resolves it from the store record's `path` (the locator)
+// plus the canonical kind registry, so callers never construct paths.
+//
+// SYNC CONSTRAINT (load-bearing): in-process callers (store-cli.cjs,
+// preflight-gate.cjs, collate.cjs) invoke this without `await`, so every method
+// is synchronous — same constraint that blocks the store's async InstantDbImpl
+// (see doc/decisions/instantdb-store-backend.md). A future remote impl must
+// either stay sync or be reached only through the forge-cli subprocess surface.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { resolveArtifactFilename } = require('./lib/artifact-kinds.cjs');
+
+// ── Locator helpers ({ backend, ref }) ───────────────────────────────────────
+
+// Derive the backend-agnostic locator from a store record. Prefers an explicit
+// `record.locator`; otherwise treats the legacy `record.path` as an fs locator
+// (the back-compat alias maintained during migration).
+function toLocator(record) {
+  if (record && record.locator && record.locator.backend) return record.locator;
+  if (record && typeof record.path === 'string' && record.path.length > 0) {
+    return { backend: 'fs', ref: record.path };
+  }
+  return null;
+}
+
+// For an fs locator ref, return the entity *directory* (strip a trailing filename).
+function fsRefToDir(ref) {
+  const norm = String(ref).replace(/\\/g, '/').replace(/\/+$/, '');
+  return /\.[a-zA-Z0-9]+$/.test(norm) ? norm.replace(/\/[^/]*$/, '') : norm;
+}
+
+// ── Default dir resolution (store record path) ───────────────────────────────
+// Reads a record's `path` via store-cli (out-of-process) so this module has no
+// hard dependency on store internals. Returns the entity directory or null.
+function readStorePath(entity, entityId, toolDir, projectRoot) {
+  const cliPath = path.join(toolDir, 'store-cli.cjs');
+  try {
+    const result = execFileSync('node', [cliPath, 'read', entity, entityId, '--json'], {
+      cwd: projectRoot, encoding: 'utf8', timeout: 10_000,
+    });
+    const record = JSON.parse(result);
+    const loc = toLocator(record);
+    if (loc && loc.backend === 'fs') return fsRefToDir(loc.ref);
+  } catch (_) { /* store unavailable / record not found — fall through */ }
+  return null;
+}
+
+// Resolve entity directory from the store record's path, falling back to
+// ID-only construction. (Moved verbatim from artifact.cjs; re-exported there.)
+function resolveEntityDir(entity, entityId, engineeringPath, toolDir, projectRoot) {
+  switch (entity) {
+    case 'bug': {
+      const storePath = readStorePath('bug', entityId, toolDir, projectRoot);
+      if (storePath) return storePath;
+      return path.join(engineeringPath, 'bugs', entityId);
+    }
+    case 'sprint': {
+      const storePath = readStorePath('sprint', entityId, toolDir, projectRoot);
+      if (storePath) return storePath;
+      return path.join(engineeringPath, 'sprints', entityId);
+    }
+    case 'task': {
+      const storePath = readStorePath('task', entityId, toolDir, projectRoot);
+      if (storePath) return storePath;
+      const match = entityId.match(/^(.+-S\d+)-T\d+$/);
+      if (!match) return null;
+      const sprintId = match[1];
+      const sprintPath = readStorePath('sprint', sprintId, toolDir, projectRoot);
+      if (sprintPath) return path.join(sprintPath, entityId);
+      return path.join(engineeringPath, 'sprints', sprintId, entityId);
+    }
+    default:
+      return null;
+  }
+}
+
+// ── Facade ───────────────────────────────────────────────────────────────────
+
+class ArtifactStore {
+  // The constructor impl is the default backend (`fs`). Additional backends are
+  // added with register(name, impl) — Phase 4. Each call routes to the impl for
+  // the handle's `backend` (default 'fs'), so adding a backend requires
+  // implementing the method surface only — no call-site or prompt changes.
+  constructor(impl) {
+    this.impl = impl;                 // default (fs) backend
+    this._backends = new Map([['fs', impl]]);
+  }
+
+  // Register an additional backend impl (e.g. an S3/CMS/DB provider). Returns
+  // `this` for chaining; re-registering the same name replaces the impl.
+  register(backend, impl) {
+    this._backends.set(backend, impl);
+    return this;
+  }
+
+  _implFor(handle) {
+    const backend = (handle && handle.backend) || 'fs';
+    const impl = this._backends.get(backend);
+    if (!impl) {
+      throw new Error(
+        `No ArtifactStore backend registered for "${backend}". ` +
+        `Registered: ${[...this._backends.keys()].join(', ')}. ` +
+        `Add one with artifactStore.register("${backend}", impl).`
+      );
+    }
+    return impl;
+  }
+
+  read(handle)            { return this._implFor(handle).read(handle); }
+  write(handle, content)  { return this._implFor(handle).write(handle, content); }
+  exists(handle)          { return this._implFor(handle).exists(handle); }
+  url(handle)             { return this._implFor(handle).url(handle); }
+  list(handle)            { return this._implFor(handle).list(handle); }
+  delete(handle)          { return this._implFor(handle).delete(handle); }
+}
+
+// ── Filesystem impl ───────────────────────────────────────────────────────────
+
+class FsArtifactImpl {
+  // opts: { projectRoot, engineeringPath, toolDir, resolveDir }
+  //   resolveDir(entity, entityId) → dir (relative to projectRoot) | null.
+  //   Injectable for testing; defaults to the store-record resolver above.
+  constructor(opts = {}) {
+    this.projectRoot = opts.projectRoot || process.cwd();
+    this.engineeringPath = opts.engineeringPath || 'engineering';
+    this.toolDir = opts.toolDir || __dirname;
+    this._resolveDir = opts.resolveDir
+      || ((entity, entityId) => resolveEntityDir(entity, entityId, this.engineeringPath, this.toolDir, this.projectRoot));
+  }
+
+  _absDir(handle) {
+    const dir = this._resolveDir(handle.entity, handle.entityId);
+    if (!dir) {
+      throw new Error(
+        `Cannot resolve ${handle.entity} directory for "${handle.entityId}". ` +
+        `Expected ID pattern: task=PREFIX-SNN-TNN, bug=PREFIX-BNN[-slug], sprint=PREFIX-SNN.`
+      );
+    }
+    return path.resolve(this.projectRoot, dir);
+  }
+
+  _absFile(handle) {
+    return path.join(this._absDir(handle), resolveArtifactFilename(handle.entity, handle.kind));
+  }
+
+  read(handle) {
+    const file = this._absFile(handle);
+    if (!fs.existsSync(file)) {
+      const err = new Error(`Artifact not found: ${path.relative(this.projectRoot, file)}`);
+      err.code = 'ENOENT';
+      throw err;
+    }
+    return fs.readFileSync(file, 'utf8');
+  }
+
+  write(handle, content) {
+    const dir = this._absDir(handle);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, resolveArtifactFilename(handle.entity, handle.kind));
+    fs.writeFileSync(file, content, 'utf8');
+    return { bytes: Buffer.byteLength(content, 'utf8'), ref: path.relative(this.projectRoot, file) };
+  }
+
+  exists(handle) {
+    try { return fs.existsSync(this._absFile(handle)); }
+    catch (_) { return false; }
+  }
+
+  url(handle) {
+    return 'file://' + this._absFile(handle);
+  }
+
+  // Entity-level listing: handle without `kind`. Returns existing filenames.
+  list(handle) {
+    const dir = this._absDir(handle);
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.md') || f.endsWith('.json'));
+  }
+
+  delete(handle) {
+    const file = this._absFile(handle);
+    if (fs.existsSync(file)) { fs.unlinkSync(file); return true; }
+    return false;
+  }
+}
+
+// ── Reference non-fs backend (Phase 4) ───────────────────────────────────────
+//
+// A complete, synchronous, in-memory implementation of the ArtifactStore method
+// surface. It exists as the canonical *reference* for adding a backend: a real
+// S3/CMS/DB provider implements these same six methods and is wired with
+// `artifactStore.register('<backend>', new XxxArtifactImpl(...))` — no prompt or
+// call-site changes. (A networked impl is sync-bound for in-process callers per
+// the ADR; it is reachable async-internally only through the forge-cli
+// subprocess surface. This in-memory impl is fully functional and dependency-free.)
+class MemArtifactImpl {
+  constructor() { this.files = new Map(); }
+  _key(h) { return `${h.entity}/${h.entityId}/${resolveArtifactFilename(h.entity, h.kind)}`; }
+  read(handle) {
+    const k = this._key(handle);
+    if (!this.files.has(k)) { const e = new Error(`Artifact not found: mem:${k}`); e.code = 'ENOENT'; throw e; }
+    return this.files.get(k);
+  }
+  write(handle, content) {
+    const k = this._key(handle);
+    this.files.set(k, content);
+    return { bytes: Buffer.byteLength(content, 'utf8'), ref: `mem:${k}` };
+  }
+  exists(handle) { return this.files.has(this._key(handle)); }
+  url(handle)    { return `mem://${this._key(handle)}`; }
+  list(handle)   {
+    const prefix = `${handle.entity}/${handle.entityId}/`;
+    return [...this.files.keys()].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+  }
+  delete(handle) { return this.files.delete(this._key(handle)); }
+}
+
+module.exports = new ArtifactStore(new FsArtifactImpl());
+module.exports.ArtifactStore = ArtifactStore;
+module.exports.FsArtifactImpl = FsArtifactImpl;
+module.exports.MemArtifactImpl = MemArtifactImpl;
+module.exports.toLocator = toLocator;
+module.exports.fsRefToDir = fsRefToDir;
+module.exports.resolveEntityDir = resolveEntityDir;
+module.exports.readStorePath = readStorePath;