@entelligentsia/forgecli 1.0.3 → 1.0.14

package/dist/forge-payload/skills/refresh-kb-links/SKILL.md

@@ -89,14 +89,21 @@ Personas live in `.forge/personas/`.
 
 Only include rows for workflow files that actually exist on disk. Check each:
 
+Atomic workflows (LLM-generated markdown in `.forge/workflows/`):
+
 - `.forge/workflows/plan_task.md` → "Research codebase → implementation plan"
 - `.forge/workflows/implement_plan.md` → "Execute approved plan → code changes"
-- `.forge/workflows/fix_bug.md` → "Triage → fix → verify"
-- `.forge/workflows/orchestrate_task.md` → "Full task pipeline (plan → implement → review → commit)"
-- `.forge/workflows/run_sprint.md` → "Full sprint orchestration"
 - `.forge/workflows/architect_sprint_plan.md` → "Sprint planning and task decomposition"
 - `.forge/workflows/architect_sprint_intake.md` → "Sprint intake and requirements elicitation"
 
+Orchestration is deterministic JS, not prose. The LLM orchestration workflows
+(`orchestrate_task` / `run_sprint` / `fix_bug`) are **retired** — link the JS
+drivers in `.claude/workflows/` instead (only include rows where the file exists):
+
+- `.claude/workflows/wfl-run-task.js` → "Full task pipeline (plan → implement → review → approve → commit)"
+- `.claude/workflows/wfl-run-sprint.js` → "Full sprint orchestration"
+- `.claude/workflows/wfl-fix-bug.js` → "Triage → fix → verify"
+
 ```markdown
 <!-- forge-workflow-links: managed by Forge — do not edit manually -->
 ## Forge Workflows
@@ -105,13 +112,13 @@ Only include rows for workflow files that actually exist on disk. Check each:
 |----------|---------|
 | [Plan](.forge/workflows/plan_task.md) | Research codebase → implementation plan |
 | [Implement](.forge/workflows/implement_plan.md) | Execute approved plan → code changes |
-| [Fix bug](.forge/workflows/fix_bug.md) | Triage → fix → verify |
-| [Run task](.forge/workflows/orchestrate_task.md) | Full task pipeline (plan → implement → review → commit) |
-| [Run sprint](.forge/workflows/run_sprint.md) | Full sprint orchestration |
+| [Run task](.claude/workflows/wfl-run-task.js) | Full task pipeline (plan → implement → review → approve → commit) |
+| [Run sprint](.claude/workflows/wfl-run-sprint.js) | Full sprint orchestration |
+| [Fix bug](.claude/workflows/wfl-fix-bug.js) | Triage → fix → verify |
 <!-- /forge-workflow-links -->
 ```
 
-(Only include rows where the referenced `.forge/workflows/` file exists on disk.)
+(Only include rows where the referenced file exists on disk.)
 
 ## KB Integrity Check
 

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;

package/dist/forge-payload/tools/artifact.cjs

@@ -14,59 +14,26 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
 const { findProjectRoot } = require('./lib/project-root.cjs');
 
 // ── Artifact catalog ─────────────────────────────────────────────────────────
-
-const ARTIFACT_CATALOG = {
-  'plan':                   { filename: 'PLAN.md',                    type: 'md' },
-  'plan-review':            { filename: 'PLAN_REVIEW.md',             type: 'md' },
-  'progress':               { filename: 'PROGRESS.md',                type: 'md' },
-  'code-review':            { filename: 'CODE_REVIEW.md',             type: 'md' },
-  'validation-report':      { filename: 'VALIDATION_REPORT.md',       type: 'md' },
-  'architect-approval':     { filename: 'ARCHITECT_APPROVAL.md',      type: 'md' },
-  'triage':                 { filename: 'TRIAGE.md',                  type: 'md' },
-  'bug-report':             { filename: 'BUG_REPORT.md',              type: 'md' },
-  'index':                  { filename: 'INDEX.md',                   type: 'md' },
-  'task-prompt':            { filename: 'TASK_PROMPT.md',             type: 'md' },
-  'sprint-requirements':    { filename: 'SPRINT_REQUIREMENTS.md',     type: 'md' },
-  'sprint-completion-review': { filename: 'SPRINT_COMPLETION_REVIEW.md', type: 'md' },
-  'cost-report':            { filename: 'COST_REPORT.md',             type: 'md' },
-  'timesheet':              { filename: 'TIMESHEET.md',               type: 'md' },
-  'plan-summary':           { filename: 'PLAN-SUMMARY.json',          type: 'json' },
-  'review-plan-summary':    { filename: 'REVIEW-PLAN-SUMMARY.json',   type: 'json' },
-  'implementation-summary': { filename: 'IMPLEMENTATION-SUMMARY.json', type: 'json' },
-  'review-code-summary':    { filename: 'REVIEW-CODE-SUMMARY.json',   type: 'json' },
-  'review-impl-summary':    { filename: 'REVIEW-IMPL-SUMMARY.json',   type: 'json' },
-  'validation-summary':     { filename: 'VALIDATION-SUMMARY.json',    type: 'json' },
-  'approve-summary':        { filename: 'APPROVE-SUMMARY.json',       type: 'json' },
-  'commit-summary':         { filename: 'COMMIT-SUMMARY.json',        type: 'json' },
-  'triage-summary':         { filename: 'TRIAGE-SUMMARY.json',        type: 'json' },
-  'writeback-summary':      { filename: 'WRITEBACK-SUMMARY.json',     type: 'json' },
-  'collation-summary':      { filename: 'COLLATION-SUMMARY.json',     type: 'json' },
-};
-
-// Per-entity filename overrides. Bug-mode plans and plan-summaries use the
-// BUG_FIX_PLAN prefix to match the long-standing forge convention and the
-// preflight-gate.cjs expectations for review-plan in bug mode. Without this
-// override, plan-fix (routed via plan_task.md post FORGE-BUG-040) writes
-// PLAN.md and review-plan preflight then fails "artifact missing:
-// BUG_FIX_PLAN.md" — see FORGE-BUG-041.
-const ARTIFACT_FILENAME_OVERRIDES = {
-  bug: {
-    'plan':         'BUG_FIX_PLAN.md',
-    'plan-summary': 'BUG-FIX-PLAN-SUMMARY.json',
-  },
-};
-
-function resolveArtifactFilename(entity, artifactName) {
-  const override = ARTIFACT_FILENAME_OVERRIDES[entity];
-  if (override && override[artifactName]) return override[artifactName];
-  return ARTIFACT_CATALOG[artifactName].filename;
-}
-
-const ARTIFACT_NAMES = Object.keys(ARTIFACT_CATALOG).sort();
+//
+// The catalog, bug-mode overrides, and filename resolution now live in the
+// canonical registry at lib/artifact-kinds.cjs (ADR artifact-resolution Phase 1),
+// consumed here and by store-cli.cjs so there is ONE source of truth.
+const {
+  ARTIFACT_CATALOG,
+  ARTIFACT_FILENAME_OVERRIDES,
+  ARTIFACT_NAMES,
+  resolveArtifactFilename,
+} = require('./lib/artifact-kinds.cjs');
+
+// The provider seam (ArtifactStore/FsArtifactImpl) and entity-dir resolution
+// live in artifact-store.cjs (ADR Phase 3). This CLI is a thin layer over the
+// facade: it owns arg parsing, @-file expansion, JSON validation, and display;
+// all filesystem access goes through the provider.
+const artifactStore = require('./artifact-store.cjs');
+const { ArtifactStore, FsArtifactImpl, resolveEntityDir } = artifactStore;
 
 // ── Summary JSON validation ──────────────────────────────────────────────────
 
@@ -88,66 +55,6 @@ function validateSummaryJson(content) {
   return null;
 }
 
-// ── Entity path resolution ───────────────────────────────────────────────────
-
-/** Read a store record via store-cli and return its `path` field, or null on failure. */
-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);
-    if (typeof record.path === 'string' && record.path.length > 0) {
-      // Defensive: if the path ends with a file extension, the store record
-      // was written with a filename (e.g. "…/PROGRESS.md") instead of the
-      // directory. Strip the trailing filename to get the entity directory.
-      const p = record.path;
-      if (/\.(md|json)$/i.test(p)) return path.dirname(p);
-      return p;
-    }
-  } catch (_) {
-    // Store unavailable or record not found — fall through.
-  }
-  return null;
-}
-
-/**
- * Resolve entity directory using the store record's `path` field when available,
- * falling back to ID-only construction.
- */
-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;
-      // Fallback: derive from sprint prefix + sprint record path.
-      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;
-  }
-}
-
 // ── CLI ───────────────────────────────────────────────────────────────────────
 
 if (require.main === module) {
@@ -163,6 +70,9 @@ if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
     '  read <entity> <entityId> <artifact>         Read artifact content',
     '  write <entity> <entityId> <artifact> <content|@file>',
     '                                              Write artifact (content or @/path/to/file)',
+    '  exists <entity> <entityId> <artifact>       Exit 0 if present, 2 if absent',
+    '  url <entity> <entityId> <artifact>          Print the backend URL (file:// for fs)',
+    '  delete <entity> <entityId> <artifact>       Delete an artifact',
     '',
     'Entities: task, bug, sprint',
     `Known artifacts: ${ARTIFACT_NAMES.join(', ')}`,
@@ -211,6 +121,14 @@ if (!entityDir) {
 
 const absDir = path.resolve(projectRoot, entityDir);
 
+// Provider instance — all filesystem access for read/write/exists/url/delete
+// goes through the facade (ADR Phase 3). Wired with the already-resolved dir so
+// the CLI and the provider agree on location without a second store read.
+const store = new ArtifactStore(new FsArtifactImpl({
+  projectRoot, engineeringPath, toolDir,
+  resolveDir: () => entityDir,
+}));
+
 // ── list ────────────────────────────────────────────────────────────────────
 
 if (subcmd === 'list') {
@@ -262,16 +180,41 @@ if (!catalogEntry) {
 }
 
 const resolvedFilename = resolveArtifactFilename(entity, artifactName);
-const filePath = path.join(absDir, resolvedFilename);
+const displayPath = path.join(entityDir, resolvedFilename);
+const handle = { entity, entityId, kind: artifactName };
 
 // ── read ─────────────────────────────────────────────────────────────────────
 
 if (subcmd === 'read') {
-  if (!fs.existsSync(filePath)) {
-    process.stderr.write(`Artifact not found: ${path.join(entityDir, resolvedFilename)}\n`);
+  if (!store.exists(handle)) {
+    process.stderr.write(`Artifact not found: ${displayPath}\n`);
     process.exit(2);
   }
-  process.stdout.write(fs.readFileSync(filePath, 'utf8'));
+  process.stdout.write(store.read(handle));
+  process.exit(0);
+}
+
+// ── exists ─────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'exists') {
+  // Boolean check: always exit 0 with a "true"/"false" token so callers
+  // (including the forge-cli subprocess surface) never treat absence as an error.
+  process.stdout.write(store.exists(handle) ? 'true\n' : 'false\n');
+  process.exit(0);
+}
+
+// ── url ────────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'url') {
+  process.stdout.write(store.url(handle) + '\n');
+  process.exit(0);
+}
+
+// ── delete ─────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'delete') {
+  const removed = store.delete(handle);
+  process.stdout.write(removed ? `Deleted ${displayPath}\n` : `Nothing to delete: ${displayPath}\n`);
   process.exit(0);
 }
 
@@ -308,15 +251,12 @@ if (subcmd === 'write') {
     }
   }
 
-  fs.mkdirSync(absDir, { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(
-    `Wrote ${Buffer.byteLength(content, 'utf8')} bytes to ${path.join(entityDir, resolvedFilename)}\n`
-  );
+  const res = store.write(handle, content);
+  process.stdout.write(`Wrote ${res.bytes} bytes to ${displayPath}\n`);
   process.exit(0);
 }
 
-process.stderr.write(`Unknown subcommand: ${subcmd}. Valid: list, read, write\n`);
+process.stderr.write(`Unknown subcommand: ${subcmd}. Valid: list, read, write, exists, url, delete\n`);
 process.exit(1);
 
 } // end if (require.main === module)

package/dist/forge-payload/tools/banners.cjs

@@ -32,6 +32,7 @@
 //   node banners.cjs --subtitle "Forging your SDLC"
 //   node banners.cjs --progress 5 12 "Templates"
 //   node banners.cjs --phase 7 12 "Workflows" ember
+//   node banners.cjs --badge forge --quiet    (automated/orchestrator use: zero stdout)
 
 // ─── Plain-mode detection ─────────────────────────────────────────────────────
 // Resolved at call-time so tests can flip env vars dynamically.
@@ -51,6 +52,12 @@ function stripAnsi(s) {
 // Soft override — set by `--plain` CLI flag to force plain mode for one run.
 let FORCE_PLAIN = false;
 
+// Quiet mode — set by `--quiet` CLI flag to suppress all stdout output.
+// Used by the orchestrator loop so banner output does not enter the LLM context
+// window (output remains visible on a real TTY via the human's terminal but is
+// not fed back as tool-call response text).
+let QUIET_MODE = false;
+
 // ─── ANSI helpers ─────────────────────────────────────────────────────────────
 const R = '\x1b[0m';
 const B = '\x1b[1m';
@@ -376,6 +383,7 @@ function _maybePlain(s) {
 
 // ─── CLI ───────────────────────────────────────────────────────────────────────
 // node banners.cjs [<name>] [--gallery] [--badge <name>] [--mark <name>] [--list]
+// node banners.cjs --badge <name> --quiet   (suppress all stdout; orchestrator use)
 
 if (require.main === module) {
   let args = process.argv.slice(2);
@@ -387,38 +395,49 @@ if (require.main === module) {
     args = args.slice(0, plainIdx).concat(args.slice(plainIdx + 1));
   }
 
+  // --quiet may appear anywhere; consume it before dispatch.
+  // When set, all stdout is suppressed (exit 0 still guaranteed on success).
+  const quietIdx = args.indexOf('--quiet');
+  if (quietIdx !== -1) {
+    QUIET_MODE = true;
+    args = args.slice(0, quietIdx).concat(args.slice(quietIdx + 1));
+  }
+
+  // Helper: write to stdout only when not in quiet mode.
+  const emit = (s) => { if (!QUIET_MODE) process.stdout.write(s); };
+
   try {
     if (!args.length || args[0] === '--gallery') {
-      process.stdout.write(gallery() + '\n');
+      emit(gallery() + '\n');
     } else if (args[0] === '--list') {
-      console.log(list().map(n => {
+      emit(list().map(n => {
         const b = BANNERS[n];
         return `${b.emoji}  ${n.padEnd(8)} — ${b.tagline}`;
-      }).join('\n'));
+      }).join('\n') + '\n');
     } else if (args[0] === '--badge') {
-      console.log(badge(args[1] || ''));
+      emit(badge(args[1] || '') + '\n');
     } else if (args[0] === '--mark') {
-      console.log(mark(args[1] || ''));
+      emit(mark(args[1] || '') + '\n');
     } else if (args[0] === '--subtitle') {
-      console.log(subtitle(args.slice(1).join(' ')));
+      emit(subtitle(args.slice(1).join(' ')) + '\n');
     } else if (args[0] === '--progress') {
       const n = Number(args[1]);
       const total = Number(args[2]);
       const label = args.slice(3).join(' ') || undefined;
-      console.log(progressBar(n, total, { label }));
+      emit(progressBar(n, total, { label }) + '\n');
     } else if (args[0] === '--phase') {
       const n = Number(args[1]);
       const total = Number(args[2]);
       const name = args[3] || '';
       const bannerKey = args[4] || 'forge';
       const mode = args[5];   // optional 'fast' | 'full'
-      console.log(phaseHeader(n, total, name, bannerKey, mode ? { mode } : undefined));
+      emit(phaseHeader(n, total, name, bannerKey, mode ? { mode } : undefined) + '\n');
     } else if (args[0] === '--rule') {
       // --rule [text]   Zen-blue em-dash horizontal rule (with optional label)
       const text = args.slice(1).join(' ') || undefined;
-      console.log(ruleLine(text));
+      emit(ruleLine(text) + '\n');
     } else {
-      process.stdout.write(render(args[0]) + '\n');
+      emit(render(args[0]) + '\n');
     }
   } catch (e) {
     console.error(e.message);