@dtlabs/ai-toolkit 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -1,4 +1,21 @@
 ## 0.1.4 (2026-07-21)
+## [0.14.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.1...v0.14.2) (2026-10-01)
+
+
+### Bug Fixes
+
+* **workflows:** host persists worker-declared outputs, no Write tool on the agent ([1109fc0](https://github.com/dtlab-tech/ai-toolkit/commit/1109fc0943ad21eedbbf859a185e3a49c654c06d))
+* **workflows:** host persists worker-declared outputs, no Write tool on the agent ([56f062c](https://github.com/dtlab-tech/ai-toolkit/commit/56f062c232110d2399d88ee011fa165b43336d12))
+* **workflows:** host persists worker-declared outputs, no Write tool on the agent ([7c1b8dc](https://github.com/dtlab-tech/ai-toolkit/commit/7c1b8dca4ba9715809b6417f5081bcca0edb09e3))
+
+## [0.14.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.0...v0.14.1) (2026-09-30)
+
+
+### Bug Fixes
+
+* **workflows:** make gaia-validate-feature-docs a single-pass, host-owned validator ([2721088](https://github.com/dtlab-tech/ai-toolkit/commit/27210884375c7302cfcf84433d3da3412c857cc1))
+* **workflows:** single-pass, host-owned document validator ([2b606fb](https://github.com/dtlab-tech/ai-toolkit/commit/2b606fb2d0df54e244abe473ea81b613eda30537))
+
 ## [0.14.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.13.0...v0.14.0) (2026-09-30)
 
 

package/docs/workflow-control-plane.md

@@ -89,6 +89,13 @@ calls, parallel rejection/drain, identity mismatch, cross-project cache leakage,
 negative semantic verdict, unknown scopes, paths with spaces and explicit approval.
 
 The live paid Claude model/permission flow has not been exercised by these tests.
+Document validation requires both a written Validation Report and a structured
+verdict (`valid: boolean`, `findings: string[]`). The validator performs one pass;
+the host owns revisions. A report or JSON in the plain-text result cannot replace
+`structured_output` from `--json-schema`. Missing structured output stops the
+workflow with an error naming the worker and required fields. Regression tests
+cover missing/malformed verdicts, a clean verdict without a report, and a negative
+verdict followed by host revision and a clean result; model responses are mocked.
 The subprocess adapter reuses FTR-018's existing qualification; no new cross-platform
 process-supervision guarantee is claimed. On Windows, the full executor test suite
 requires Git Bash ahead of the WSL launcher in PATH. User-level installations are

package/lib/workflow-control.js

@@ -8,6 +8,8 @@ const { spawnSync } = require('child_process');
 const registry = require('./agent-registry');
 const ledger = require('./execution-ledger');
 const { spawnClaudeAgent } = require('./task-executor/claude-process');
+const { createEvidence } = require('./workflow-worker-evidence');
+const { resolveOutputPath } = require('./workflow-worker-outputs');
 const CLI = path.join(__dirname, '..', 'bin', 'cli.js');
 
 
@@ -66,7 +68,16 @@ function deriveFeatureDir(featurePath) {
 }
 
 function createControl(options) {
-  const root = path.resolve(options.projectDir);
+  if (options.workerMaxBudgetUsd != null && (!Number.isFinite(options.workerMaxBudgetUsd) || options.workerMaxBudgetUsd <= 0)) throw new Error('Worker budget must be a positive finite number');
+  // Windows can alias any long/dotted path segment to an 8.3 short name (e.g. the
+  // TEMP env var itself is often short-form: C:\Users\TOMADA~1\...). The spawned
+  // CLI resolves a tool call's absolute path in long form regardless, so an
+  // --allowedTools pattern built from a short-form root would silently never
+  // match — confirmed empirically (tests/manual/workflow-worker-smoke.js) against
+  // a real CLI run under a short-form TEMP path. realpath.native (unlike the pure-JS
+  // fs.realpathSync) resolves 8.3 aliases on Windows, and is a harmless plain
+  // symlink-resolving realpath on every other platform.
+  const root = fs.realpathSync.native(path.resolve(options.projectDir));
   const runId = crypto.randomUUID();
   let context, spent = 0, sequence = 0;
   const tokenLedger = [];
@@ -81,6 +92,13 @@ function createControl(options) {
     try { fs.writeFileSync(tmp, content, 'utf8'); fs.renameSync(tmp, dest); }
     finally { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); }
   };
+  // Validates a worker-declared (or, for a dynamic multi-file deliverable like
+  // intervention-documentation-standard, model-declared) output path the same way
+  // worker()'s single-output contract does — inside the project, outside any tool-config
+  // directory, never through a symlink — then writes it. The one path through which any
+  // LLM response ever reaches disk in this workflow runtime; see worker()'s own comment
+  // for why that's the host's job and never the agent's.
+  const writeOutput = (p, content) => write(resolveOutputPath(root, { path: p }), content);
   async function resolve(id, kind = 'agent') {
     const record = await registry.resolveAgent({ projectDir: root, homeDir: options.home,
       agentId: id, requireVerified: true });
@@ -123,22 +141,71 @@ function createControl(options) {
     return activity(opts.label || id, async () => {
       const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName];
       if (opts.schema) cliArgs.push('--json-schema', JSON.stringify(opts.schema));
+      if (options.workerMaxBudgetUsd != null) cliArgs.push('--max-budget-usd', String(options.workerMaxBudgetUsd));
+      const outputs = opts.outputs || [];
+      for (const output of outputs) {
+        if (!output || typeof output.path !== 'string' || !Array.isArray(output.inputs || [])) throw new Error('Invalid worker output contract');
+      }
+      // Never ask an LLM to do I/O: a worker with a declared output has no Write tool at
+      // all (see its agent frontmatter) and returns the document as plain response text
+      // (or, under --json-schema, as a `report` field) instead. The host resolves and
+      // validates the real target path up front — fail before dispatch, not after paying
+      // for a model turn — and writes the file itself once the response is in hand. This
+      // sidesteps the CLI's own permission system for Write entirely, which empirically
+      // (tests/manual/workflow-worker-smoke.js) does not support a non-interactive mode
+      // that both skips prompting AND honors a scoped, per-file allow pattern: `dontAsk`
+      // ignores runtime-supplied allow rules for paths with no pre-existing persisted
+      // grant, while `acceptEdits`/`auto` grant Write (and every other tool, unscoped)
+      // anywhere in the project regardless of any allowlist passed alongside them.
+      if (outputs.length > 1) throw new Error('Worker output contract supports exactly one output today: ' + id);
+      const outputTarget = outputs.length ? resolveOutputPath(root, outputs[0]) : null;
+      const evidence = createEvidence(options, runId, identity, {
+        executable: options.claudePath || null, cwd: root, args: cliArgs, outputs,
+      });
+      (options.log || (() => {}))('Worker evidence: ' + evidence.file);
+      try {
       const result = await (options.dispatch || spawnClaudeAgent)({
         claudePath: options.claudePath, cwd: root, args: cliArgs, prompt,
         taskTimeoutMs: options.taskTimeoutMs || 1800000,
       });
+      // Count usage before any business/protocol check, including denied tools.
+      const usage = result.result?.usage;
+      const counts = usage && [usage.input_tokens, usage.output_tokens,
+        usage.cache_read_input_tokens ?? 0, usage.cache_creation_input_tokens ?? 0];
+      const tokens = counts && counts.every(n => Number.isInteger(n) && n >= 0)
+        ? counts.reduce((a, b) => a + b, 0) : null;
+      measuredTokens = Number.isSafeInteger(tokens) && tokens > 0 ? tokens : null;
+      spent += measuredTokens || 0;
+      tokenLedger.push({ agent: identity.nativeName, model: definition.model,
+        phase_delta_tokens: measuredTokens, usage: usage || null, evidence_path: evidence.file });
+      evidence.save({ response: result });
+      const denials = result.result?.permission_denials;
+      if (Array.isArray(denials) && denials.length) {
+        const tools = [...new Set(denials.map(d => d.tool_name || 'unknown'))].join(', ');
+        throw new Error('Worker permission denied: ' + id + '; tools: ' + tools);
+      }
       if (result.exitCode !== 0 || result.parseError || result.timedOut ||
           !result.result || result.result.is_error !== false) throw new Error('Worker failed: ' + id);
       const payload = opts.schema ? result.result.structured_output : result.result.result;
-      if (payload == null || (typeof payload === 'string' && !payload.trim())) throw new Error('Worker returned no result: ' + id);
+      if (payload == null || (typeof payload === 'string' && !payload.trim())) {
+        if (opts.schema) {
+          const fields = (opts.schema.required || []).join(', ') || '(see requested schema)';
+          throw new Error('Worker returned no structured output: ' + id + '; expected fields: ' + fields + '. The --json-schema response must populate structured_output; a report file or plain-text result is not sufficient.');
+        }
+        throw new Error('Worker returned no result: ' + id);
+      }
       if (opts.schema) validateSchema(payload, opts.schema);
-      const usage = result.result.usage;
-      const tokens = usage && [usage.input_tokens, usage.output_tokens].every(Number.isFinite)
-        ? usage.input_tokens + usage.output_tokens + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0) : null;
-      measuredTokens = Number.isInteger(tokens) && tokens > 0 ? tokens : null;
-      spent += measuredTokens || 0;
-      tokenLedger.push({ agent: identity.nativeName, model: definition.model, phase_delta_tokens: measuredTokens });
+      if (outputTarget) {
+        const content = opts.schema ? payload.report : payload;
+        if (typeof content !== 'string' || !content.trim()) throw new Error('Worker output content missing or empty: ' + id);
+        writeOutput(outputTarget, content);
+      }
+      evidence.save({ outcome: 'done', completedAt: new Date().toISOString() });
       return payload;
+      } catch (error) {
+        evidence.save({ outcome: 'failed', error: String(error), completedAt: new Date().toISOString() });
+        throw new Error(error.message + '; evidence: ' + evidence.file, { cause: error });
+      }
     }, definition.model, () => measuredTokens, { agentId: id, nativeAgentName: identity.nativeName, platform: 'claude', definitionHash: identity.sha256, resolutionScope: identity.scope, toolkitVersion: identity.toolkitVersion });
   }
   async function parallel(fns) {
@@ -183,13 +250,20 @@ function createControl(options) {
   }
   function feature(p) {
     if (!p) throw new Error('Feature path required');
-    const file = full(p), dir = deriveFeatureDir(file);
+    const file = full(p);
+    read(file); // confirms existence (with a clear error) before realpath.native requires it
+    // Canonicalize once, here, so every output path derived from featureDir downstream
+    // (pm-phase1.js/pm-phase2.js's `file()` helpers) shares the same 8.3-alias-free form
+    // as `root` — resolveOutputPath() can then do a plain, non-realpath string comparison
+    // instead of reconciling mismatched forms (which would have to silently follow
+    // symlinks to do so, defeating its own symlink-escape check).
+    const canonicalFile = fs.realpathSync.native(file);
+    const dir = deriveFeatureDir(canonicalFile);
     const match = path.basename(dir).match(/^([A-Z]+-\d+)(?:-|$)/);
     if (!match) throw new Error('Cannot derive canonical feature prefix');
-    read(file);
-    return { featurePath: file, featureDir: dir, prefix: match[1] };
+    return { featurePath: canonicalFile, featureDir: dir, prefix: match[1] };
   }
-  const api = { root, runId, read, exists, write, resolve, worker, parallel, run, command, activity,
+  const api = { root, runId, read, exists, write, writeOutput, resolve, worker, parallel, run, command, activity,
     feature, parseArgs, tokenLedger, spent: () => spent,
     mtime: p => fs.statSync(full(p)).mtimeMs,
     json: p => JSON.parse(read(p)),

package/lib/workflow-runner.js

@@ -26,11 +26,13 @@ async function main(argv) {
   const split = argv.indexOf('--');
   if (split < 0) throw new Error('Workflow arguments must follow --');
   const options = { projectDir: process.cwd(), log: s => process.stderr.write(s + '\n') };
-  const keys = { '--project': 'projectDir', '--home': 'home', '--claude-path': 'claudePath' };
+  const keys = { '--project': 'projectDir', '--home': 'home', '--claude-path': 'claudePath',
+    '--diagnostics-dir': 'diagnosticsDir', '--worker-max-budget-usd': 'workerMaxBudgetUsd' };
   for (let i = 2; i < split; i += 2) {
     if (!keys[argv[i]] || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error('Invalid workflow option: ' + argv[i]);
     options[keys[argv[i]]] = argv[i + 1];
   }
+  if (options.workerMaxBudgetUsd != null) options.workerMaxBudgetUsd = Number(options.workerMaxBudgetUsd);
   if (!options.claudePath && argv[1] !== 'am-phase2') throw new Error('--claude-path is required');
   const result = await runWorkflow(argv[1], argv.slice(split + 1), options);
   process.stdout.write(JSON.stringify(result) + '\n');

package/lib/workflow-worker-evidence.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+// Do not capture the parent environment or stdin prompt. Diagnostic responses
+// can contain document text; redact common credential forms before persistence.
+function redact(value) {
+  const secretKey = /^(?:authorization|proxy.authorization|.*(?:api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret|credential))$/i;
+  const secrets = Object.entries(process.env)
+    .filter(([key, val]) => secretKey.test(key) && val && val.length >= 8)
+    .map(([, val]) => val);
+  function cleanString(text) {
+    for (const secret of secrets) text = text.split(secret).join('[REDACTED]');
+    return text
+      .replace(/\b(Bearer\s+)[^\s"'<>]+/gi, '$1[REDACTED]')
+      .replace(/\b((?:api[_-]?key|token|password|secret)\s*[=:]\s*)[^\s,"'<>]+/gi, '$1[REDACTED]')
+      .replace(/\bsk-[A-Za-z0-9_-]+/g, '[REDACTED]');
+  }
+  function walk(item) {
+    if (typeof item === 'string') {
+      // stdout is often a JSON string: redact credential keys there too.
+      try { return JSON.stringify(walk(JSON.parse(item))); } catch (_) { return cleanString(item); }
+    }
+    if (Array.isArray(item)) return item.map(walk);
+    if (item && typeof item === 'object') return Object.fromEntries(Object.entries(item)
+      .map(([key, val]) => [key, secretKey.test(key) ? '[REDACTED]' : walk(val)]));
+    return item;
+  }
+  return walk(value);
+}
+
+function createEvidence(options, runId, identity, invocation) {
+  const dir = path.join(path.resolve(options.diagnosticsDir || path.join(os.tmpdir(), 'ai-toolkit-workflows')), runId);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, crypto.randomUUID() + '.json');
+  const record = { version: 1, runId, agentId: identity.agentId, definitionPath: identity.path,
+    definitionHash: identity.sha256, invocation, startedAt: new Date().toISOString(), outcome: 'running' };
+  function save(patch) {
+    Object.assign(record, patch);
+    const temp = file + '.tmp';
+    try {
+      fs.writeFileSync(temp, JSON.stringify(redact(record), null, 2) + '\n', { mode: 0o600 });
+      fs.renameSync(temp, file);
+    } finally { if (fs.existsSync(temp)) fs.unlinkSync(temp); }
+  }
+  save({});
+  return { file, save };
+}
+
+module.exports = { createEvidence, redact };

package/lib/workflow-worker-outputs.js

@@ -0,0 +1,37 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+// Validates that a worker's declared output stays inside the project, outside any
+// tool-config directory, and is never reached through a symlink/junction — then
+// returns its canonical absolute path. The workflow host (never the LLM) writes the
+// worker's returned content to this path with fs.writeFileSync; there is no CLI
+// permission surface to construct here ("Never ask an LLM to do I/O").
+//
+// Assumes `root` and `output.path` already share the same 8.3-alias form (createControl
+// realpath.native's `root` once at startup; feature() realpath.native's featurePath/
+// featureDir the same way, and every output.path in this codebase is built from
+// featureDir) — do NOT realpath-resolve anything in here to "reconcile" a mismatch: that
+// would have to follow symlinks to do it, silently defeating the symlink check below.
+function resolveOutputPath(root, output) {
+  const target = path.resolve(root, output.path);
+  const relative = path.relative(root, target);
+  if (!relative || path.isAbsolute(relative) || relative === '..' || relative.startsWith('..' + path.sep)) {
+    throw new Error('Worker output must be inside the project: ' + target);
+  }
+  const segments = relative.split(path.sep);
+  if (segments.some(s => ['.git', '.claude', '.codex'].includes(s.toLowerCase()))) {
+    throw new Error('Unsupported worker output path: ' + target);
+  }
+  // Never automatically write a target reached through a symlink/junction.
+  let cursor = root;
+  for (const segment of segments) {
+    cursor = path.join(cursor, segment);
+    try {
+      if (fs.lstatSync(cursor).isSymbolicLink()) throw new Error('Worker output traverses a symlink: ' + cursor);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return target;
+}
+
+module.exports = { resolveOutputPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/gaia-concurrency-safety-assessment.md

@@ -1,7 +1,7 @@
 ---
 name: gaia-concurrency-safety-assessment
 description: "Concurrency Safety Assessment — identifies race conditions, shared mutable state corruption, and non-deterministic behaviour in concurrent or event-driven systems. Language-agnostic; produces structured findings with severity, evidence, and mitigation patterns. Output: {ASSESS_PREFIX}-Concurrency-Assessment.md"
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 model: haiku
 ---
 
@@ -120,7 +120,7 @@ Blocking: Yes / No
 
 ## Output
 
-Write to `{ASSESS_PREFIX}-Concurrency-Assessment.md`:
+Return the assessment as your final response — you do not have a Write tool; the host persists your response verbatim to `{ASSESS_PREFIX}-Concurrency-Assessment.md`. Your entire final response must be this document's content, and nothing else (no preamble, no Markdown code fence wrapping the whole thing):
 
 ```markdown
 # Concurrency Safety Assessment — {ASSESS_PREFIX}

package/src/claude/agents/gaia-generate-requirements.md

@@ -2,7 +2,7 @@
 name: gaia-generate-requirements
 description: "Generates a functional requirements document from a feature description. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Generate Functional Requirements Document
@@ -20,21 +20,19 @@ The user provides the path to a `feature.md` file. Read it in full before procee
 3. **Identify** all functional areas described
 3. **Extract** actors, use cases, business rules, acceptance criteria
 4. **Organize** into a structured requirements document
-5. **Write** the output to a requirements file in the same directory as the input feature file
+5. **Return** the complete document as your final response — you do not have a Write tool; the host persists your response to `{PREFIX}-Requirements.md` verbatim. Do not attempt to write any file yourself.
 
-## Output Filename
+## Output Filename (for your reference only — you do not write this file)
 
 Extract the **feature prefix** from the folder name containing `feature.md`:
 - Folder: `FTR-001-user-management` → prefix: `FTR-001`
 - Folder: `FTR-042-Search-Engine` → prefix: `FTR-042`
 
-The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`).
-
-Output file: `{PREFIX}-Requirements.md` in the same directory as `feature.md`.
+The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`). Use it in the document's own "Document Info" section; the host, not you, decides the actual output filename.
 
 ## Output Structure
 
-Generate the document in **English** following this template:
+Generate the document in **English** following this template. Your entire final response must be this document's content, and nothing else (no preamble, no "here is the document", no Markdown code fence wrapping the whole thing) — the host writes your response verbatim to disk:
 
 ```markdown
 # Functional Requirements — [Feature Title]

package/src/claude/agents/gaia-generate-tech-spec.md

@@ -2,7 +2,7 @@
 name: gaia-generate-tech-spec
 description: "Generates a technical specification document from a feature description and requirements. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Generate Technical Specification
@@ -37,21 +37,19 @@ The tech spec MUST use the project's actual stack and patterns. Do not assume an
 3. **Read** `docs/features/REGISTRY.md` if it exists — identify features that touch the same entities, endpoints, or services as this feature. Note architectural dependencies and integration points in Section 5 (External Integrations) or Section 12 (Risks & Mitigations) of the output document. If a prior feature introduced shared infrastructure this feature reuses (e.g. auth middleware, base service, shared DTO), reference it explicitly.
 4. **Explore** the existing codebase areas affected (models, controllers/handlers, pages, services)
 4. **Design** the technical solution aligned with existing patterns from AGENTS.md
-5. **Write** the output to a tech-spec file in the same directory as the input feature file
+5. **Return** the complete document as your final response — you do not have a Write tool; the host persists your response to `{PREFIX}-Tech-Spec.md` verbatim. Do not attempt to write any file yourself.
 
-## Output Filename
+## Output Filename (for your reference only — you do not write this file)
 
 Extract the **feature prefix** from the folder name containing `feature.md`:
 - Folder: `FTR-001-user-management` → prefix: `FTR-001`
 - Folder: `FTR-042-Search-Engine` → prefix: `FTR-042`
 
-The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`).
-
-Output file: `{PREFIX}-Tech-Spec.md` in the same directory as `feature.md`.
+The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`). Use it in the document's own "Document Info" section; the host, not you, decides the actual output filename.
 
 ## Output Structure
 
-Generate the document in **English** following this template. Adapt section content to the project's actual tech stack (from AGENTS.md):
+Generate the document in **English** following this template. Adapt section content to the project's actual tech stack (from AGENTS.md). Your entire final response must be this document's content, and nothing else (no preamble, no "here is the spec", no Markdown code fence wrapping the whole thing) — the host writes your response verbatim to disk:
 
 ```markdown
 # Technical Specification — [Feature Title]

package/src/claude/agents/gaia-generate-work-breakdown.md

@@ -2,7 +2,7 @@
 name: gaia-generate-work-breakdown
 description: "Generates a structured work breakdown (User Stories + Tasks) from validated and approved Requirements and Tech-Spec. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Generate Work Breakdown
@@ -186,9 +186,9 @@ Duration guidance:
 
 - `estimate.tokens`: integer; rough estimate of token consumption (input + output) for the agent invocation; use project norms if available, otherwise estimate based on task complexity (small: 10 000–25 000, medium: 25 000–60 000)
 
-### Step 7 — Write the JSON Output
+### Step 7 — Return the JSON Output
 
-Write `{PREFIX}-Work-Breakdown.json` in the same directory as `feature.md`. The file must be:
+Return `{PREFIX}-Work-Breakdown.json`'s content as your final response, and nothing else (no preamble, no explanatory prose, no Markdown code fence wrapping it) — you do not have a Write tool; the host persists your response verbatim to disk. The content must be:
 - Valid JSON
 - UTF-8 encoded
 - 2-space indentation

package/src/claude/agents/gaia-generic-software-assessment.md

@@ -1,7 +1,7 @@
 ---
 name: gaia-generic-software-assessment
 description: "Generic Software Assessment — performs a broad quality analysis across architecture, code quality, security, testability, observability, and DevOps. Reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Generic-Assessment.md"
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 model: haiku
 ---
 
@@ -112,7 +112,7 @@ Report a score (1–5) for each KPI, where 5 = excellent, 1 = critical issues:
 
 ## Output
 
-Write the assessment to `{ASSESS_PREFIX}-Generic-Assessment.md` in the assessment directory.
+Return the assessment as your final response — you do not have a Write tool; the host persists your response verbatim to `{ASSESS_PREFIX}-Generic-Assessment.md` in the assessment directory. Your entire final response must be this document's content, and nothing else (no preamble, no "here is the assessment", no Markdown code fence wrapping the whole thing):
 
 ```markdown
 # Generic Software Assessment — {ASSESS_PREFIX}

package/src/claude/agents/gaia-intervention-documentation-standard.md

@@ -2,7 +2,7 @@
 name: gaia-intervention-documentation-standard
 description: "Intervention Documentation Standard — generates structured, self-contained intervention documents from assessment findings. Each document is independently actionable by an architect or developer agent. Input: assessment findings; Output: {ASSESS_PREFIX}-INT-NNN-{slug}.md per finding + Interventions-Index.md"
 model: sonnet
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 ---
 
 # Intervention Documentation Standard
@@ -117,7 +117,7 @@ References to assessment findings (`{ASSESS_PREFIX}-G-NNN`), related ADRs, relat
 
 ## Interventions Index
 
-After writing all intervention documents, produce `{ASSESS_PREFIX}-Interventions-Index.md`:
+Alongside the intervention documents, compose one more file, `{ASSESS_PREFIX}-Interventions-Index.md`:
 
 ```markdown
 # Interventions Index — {ASSESS_PREFIX}
@@ -130,3 +130,26 @@ After writing all intervention documents, produce `{ASSESS_PREFIX}-Interventions
 ```
 
 Order by criticality (CRITICAL first), then by dependency (prerequisites before dependents).
+
+---
+
+## Output Contract (MANDATORY — your final response)
+
+You do not have a Write tool. You produce a **variable number of files** (one per intervention, plus the index) whose names you yourself decide (the `{area-slug}` in each filename), so the host cannot know their paths in advance the way it does for a single fixed deliverable — you must declare each file's path and content yourself, and the host validates and persists every one of them.
+
+Return a single JSON object with exactly this shape, without Markdown fences or explanatory prose:
+
+```json
+{
+  "files": [
+    { "path": "{ASSESS_PREFIX}-INT-001-sql-injection-hardening.md", "content": "# ...full document content..." },
+    { "path": "{ASSESS_PREFIX}-INT-002-god-class-decomposition.md", "content": "# ...full document content..." },
+    { "path": "{ASSESS_PREFIX}-Interventions-Index.md", "content": "# Interventions Index — {ASSESS_PREFIX}\n\n| ID | ... |\n..." }
+  ]
+}
+```
+
+- `files` is a non-empty array. Every intervention document you decided to write, plus the index, must appear here — there is no separate Write step and nothing you do not include in this array reaches disk.
+- Each `path` is a bare filename (no directory components) — the host resolves it against the assessment output directory itself; never include `docs/`, `..`, or an absolute path.
+- Each `content` is that file's complete, final content, verbatim — exactly as the host will write it byte-for-byte.
+- The caller supplies `--json-schema`; use the runtime's structured-output mechanism to return this object in `structured_output`. Plain-text JSON alone does not satisfy that contract.

package/src/claude/agents/gaia-layered-architecture-assessment.md

@@ -1,7 +1,7 @@
 ---
 name: gaia-layered-architecture-assessment
 description: "Layered Architecture Assessment — audits a codebase for layer boundary violations, missing separation of concerns, and namespace/package misalignment. Produces a violation inventory and a recommended layer model. Language-agnostic; reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Layer-Assessment.md"
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 model: haiku
 ---
 
@@ -135,7 +135,7 @@ Report the current state and recommend the appropriate option based on team size
 
 ## Output
 
-Write to `{ASSESS_PREFIX}-Layer-Assessment.md`:
+Return the assessment as your final response — you do not have a Write tool; the host persists your response verbatim to `{ASSESS_PREFIX}-Layer-Assessment.md`. Your entire final response must be this document's content, and nothing else (no preamble, no Markdown code fence wrapping the whole thing):
 
 ```markdown
 # Layered Architecture Assessment — {ASSESS_PREFIX}

package/src/claude/agents/gaia-validate-feature-docs.md

@@ -1,13 +1,13 @@
 ---
 name: gaia-validate-feature-docs
-description: "Validates Requirements and Tech-Spec documents against feature.md. Triggers targeted revision of failing documents if gaps are found. Input: path to feature.md"
+description: "Validates Requirements and Tech-Spec documents against feature.md. Returns the validation report content and a structured verdict; the host persists the report and owns revisions. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Validate Feature Docs
 
-A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md` and `{PREFIX}-Tech-Spec.md`, identifies coverage gaps, and triggers targeted revisions until full coverage is achieved.
+A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md` and `{PREFIX}-Tech-Spec.md` and identifies coverage gaps in a single validation pass. The host workflow owns revisions and the three-cycle limit. Do not dispatch other agents or revise the input documents.
 
 ---
 
@@ -18,7 +18,7 @@ A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md`
    - `feature.md` — source of truth
    - `{PREFIX}-Requirements.md`
    - `{PREFIX}-Tech-Spec.md`
-3. If either output document is missing, abort and report: "Cannot validate: `{file}` not found. Run /implement-feature first."
+3. If an input document is missing, record a finding identifying it, skip checks that require it, and complete Phases 6 and 7 with `valid: false`. Never claim full coverage when an input could not be read.
 
 ---
 
@@ -101,33 +101,23 @@ Result: ✅ Full coverage — all feature claims addressed in both documents
 
 ---
 
-## Phase 5 — Revision Loop
+## Phase 5 — Return Findings to the Host
 
-If gaps were found, trigger targeted revisions. **Only revise the documents that have gaps** — do not touch clean documents.
+Collect all remaining gaps for the host's revision loop. Do not invoke agents, edit Requirements or Tech-Spec, or run a revision loop yourself.
 
-### Revision instructions
+Each finding must be one string prefixed with `Requirements:` or `Tech-Spec:` to identify the affected document, followed by the exact section or claim and the missing coverage. If a gap affects both documents, emit one finding per document.
 
-For each document with gaps, invoke the corresponding agent with a **targeted revision prompt** that includes:
-1. The path to the existing document to revise (not regenerate from scratch)
-2. The exact list of gaps to address
-3. The instruction to revise only the affected sections
-
-### Revision rules
-
-- **Max iterations**: 3 revision cycles. If gaps persist after 3 rounds, write the remaining gaps to the report and stop.
-- **After each revision**: re-run Phase 3 on the updated document to verify gaps are resolved
-- **Document what changed**: after each revision, note which gaps were resolved
-- **Never revise a document that has no gaps** — even if the other document is being revised
+Use the same remaining gaps in the report and the structured verdict. Record a gap as resolved only when the current documents demonstrate that it is resolved.
 
 ---
 
-## Phase 6 — Write Validation Report (MANDATORY — your final action)
+## Phase 6 — Compose the Validation Report Content (MANDATORY — before returning the verdict)
 
-**This is not optional and not the same as the Phase 4 gap report.** The coverage report you produced in Phase 4 is on-screen text; it is NOT the deliverable. Your job is not complete until the file `{PREFIX}-Validation-Report.md` exists **on disk**. You MUST call the `Write` tool to create it — even when validation is clean and zero gaps were found. Returning a summary without having called `Write` is a failure.
+**This is not optional and not the same as the Phase 4 gap report.** The coverage report you produced in Phase 4 is on-screen text; it is NOT the deliverable. You do not have a Write tool — the deliverable is the `report` field of your Phase 7 structured output, which the host persists to `{PREFIX}-Validation-Report.md` verbatim. Returning a verdict without a complete `report` field is a failure.
 
-Execute this phase **last, always**, regardless of outcome. Downstream agents read this file as a hard precondition; if it is missing, the entire pipeline aborts.
+Execute this phase regardless of the validation outcome, then complete Phase 7. Downstream agents read the persisted file as a hard precondition; if the `report` field is missing or empty, the entire pipeline aborts.
 
-Write `{PREFIX}-Validation-Report.md` in the same directory:
+Compose `{PREFIX}-Validation-Report.md`'s full content following this template:
 
 ```markdown
 # Validation Report — {PREFIX}
@@ -154,23 +144,37 @@ Write `{PREFIX}-Validation-Report.md` in the same directory:
 
 ---
 
-## Clarification Protocol
+## Phase 7 — Structured Completion (MANDATORY — your final response)
+
+Return a single JSON object with exactly these fields, without Markdown fences or explanatory prose:
+
+```json
+{"valid": true, "findings": [], "report": "# Validation Report — FTR-001\n\n## Summary\n..."}
+```
+
+For remaining gaps:
 
-When a gap is found but the correct resolution is ambiguous (e.g., the feature.md itself is contradictory, or a gap could be filled in multiple valid ways), **stop and ask the user** before revising. Use the `AskUserQuestion` tool to present:
+```json
+{"valid": false, "findings": ["Requirements: UC-01 lacks an acceptance criterion", "Tech-Spec: POST /api/users lacks a response definition"], "report": "# Validation Report — FTR-001\n\n## Summary\n..."}
+```
 
-1. A clear description of the gap and why the resolution is uncertain
-2. Concrete options (2–4) representing valid ways to address it
-3. **Always include** an option: "Leave as open point to discuss later" — which records the gap in the Validation Report as unresolved (not a failure) and skips revision for that item
+- `valid` is a boolean: `true` only when all required inputs were read, coverage is complete, and no unresolved gaps remain.
+- `findings` is an array of strings, empty only for a clean validation. Missing inputs and ambiguous claims are unresolved findings.
+- `report` is a non-empty string: the complete Phase 6 document content, verbatim, as the host will write it byte-for-byte to `{PREFIX}-Validation-Report.md`.
+- The caller supplies `--json-schema`; use the runtime's structured-output mechanism to return this object in `structured_output`. Plain-text JSON alone does not satisfy that contract.
+- There is only one deliverable now: the structured verdict, with `report` inside it. There is no separate Write step.
+
+## Clarification Protocol
 
-Do NOT guess how to fill ambiguous gaps. Ask first, then revise only with a clear direction.
+If a claim is contradictory or its correct resolution is ambiguous, do not guess or request interactive input inside this worker. Describe the ambiguity in the report and the affected document's finding, with `valid: false`, so the calling orchestration can surface it to the user. An open point must not be treated as clean coverage.
 
 ---
 
 ## Guidelines
 
-- **Always call `Write` for the Validation Report before finishing** (Phase 6) — the on-screen gap report is not the deliverable; the file on disk is. This is your last action, clean or not.
-- **Do not regenerate documents from scratch** — targeted revisions only
+- **Always include the complete report content in the `report` field of your structured verdict** (Phases 6 and 7), clean or not — there is no Write tool to fall back on.
+- **Validate only** — the host owns document revisions and agent dispatch
 - **Be specific about gaps** — point to the exact section, claim, and what is missing
-- **Stop after 3 revision cycles** — if coverage is still incomplete, report remaining gaps and exit
+- **Perform one validation pass per invocation** — return remaining gaps to the host
 - **Out-of-scope items are also validated** — ensure they are not accidentally included in outputs
 - **Traceability is mandatory** — every Use Case ID in Requirements must appear in Tech-Spec

package/src/claude/workflows/am-phase1.js

@@ -29,20 +29,35 @@ return c.run(meta.name, outputDir, prefix, async () => {
     const id = SCOPE_AGENT_MAP[area]
     groups.set(id, [...(groups.get(id) || []), area])
   }
+  // Neither assessor below has a Write tool: each returns its report as plain response
+  // text, which the host persists to its declared `outputs` path (see worker()'s own
+  // comment in lib/workflow-control.js for why — "Never ask an LLM to do I/O").
   const assessmentResults = await c.parallel([...groups].map(([id, areas]) => async () => {
+    const suffix = { 'gaia.agent.assessment.generic': 'Generic', 'gaia.agent.assessment.layered-architecture': 'Layer', 'gaia.agent.assessment.concurrency': 'Concurrency' }[id]
+    const output_file = `${outputDir}/${prefix}-${suffix}-Assessment.md`
     const result = await c.worker(id,
       `${targetPath} --prefix ${prefix} --output-dir ${outputDir}\n` +
       `Read-only assessment. Explicit scope: ${areas.join(', ')}. Inspect risks, evidence, severity and recommendations for EACH listed scope. ` +
       'For security inspect trust boundaries and authorization; devops: build/deploy/observability; domain-model: invariants and ownership; dependencies: versions, provenance and supply-chain risks. ' +
-      'Do not remediate code or dispatch remediation agents. Write your assessment report in the output directory.')
-    const suffix = { 'gaia.agent.assessment.generic': 'Generic', 'gaia.agent.assessment.layered-architecture': 'Layer', 'gaia.agent.assessment.concurrency': 'Concurrency' }[id]
-    const output_file = `${outputDir}/${prefix}-${suffix}-Assessment.md`
-    if (!c.read(output_file).trim()) throw new Error('Assessment report empty: ' + output_file)
+      'Do not remediate code or dispatch remediation agents. Return your assessment report as your final response.',
+      { outputs: [{ path: output_file }] })
     return { agent: id, scopes: areas, result, output_file }
   }))
-  await c.worker('gaia.agent.assessment.intervention-documentation',
+  // intervention-documentation-standard writes a variable number of files (one per
+  // intervention plus an index) whose names it decides itself, so it cannot use the
+  // single static `outputs` contract above — it declares each {path, content} pair in
+  // its own structured_output, and the host validates and persists every one of them.
+  const docs = await c.worker('gaia.agent.assessment.intervention-documentation',
     `--prefix ${prefix} --output-dir ${outputDir} --target ${targetPath}\nUse only the reports from these assessors: ${[...groups.keys()].join(', ')}.\n` +
-    assessmentResults.map(r => `${r.agent}: ${typeof r.result === 'string' ? r.result : JSON.stringify(r.result)}`).join('\n'))
+    assessmentResults.map(r => `${r.agent}: ${typeof r.result === 'string' ? r.result : JSON.stringify(r.result)}`).join('\n'),
+    { schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'object',
+      properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] } } }, required: ['files'] } })
+  if (!docs.files.length) throw new Error('Intervention documentation produced no files')
+  for (const f of docs.files) {
+    if (!f.path || /[\\/]/.test(f.path) || f.path.includes('..')) throw new Error('Invalid intervention document path: ' + f.path)
+    if (!f.content || !f.content.trim()) throw new Error('Empty intervention document: ' + f.path)
+    c.writeOutput(`${outputDir}/${f.path}`, f.content)
+  }
   const metrics = c.assessmentEstimates(outputDir, prefix)
   return { prefix, output_dir: outputDir, target_path: targetPath,
     assessment_summaries: assessmentResults.map(({ agent, scopes, output_file }) => ({ agent, scopes, output_file })),

package/src/claude/workflows/pm-phase1.js

@@ -14,21 +14,24 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const reqId = 'gaia.agent.planner.requirements'
   const specId = 'gaia.agent.planner.tech-spec'
   const valId = 'gaia.agent.planner.validate-feature-docs'
+  const output = (suffix, inputs = [featurePath]) => ({ path: file(suffix), inputs })
+  const requirements = () => c.worker(reqId, featurePath, { outputs: [output('Requirements')] })
+  const techSpec = () => c.worker(specId, featurePath, { outputs: [output('Tech-Spec', [featurePath, file('Requirements')])] })
   let changed = false
   if (force || !fresh(file('Requirements'))) {
-    await c.worker(reqId, featurePath)
+    await requirements()
     if (!c.exists(file('Requirements'))) throw new Error('Requirements output missing')
     changed = true
   }
   if (force || changed || !fresh(file('Tech-Spec'), [featurePath, file('Requirements')])) {
-    await c.worker(specId, featurePath)
+    await techSpec()
     if (!c.exists(file('Tech-Spec'))) throw new Error('Tech-Spec output missing')
     changed = true
   }
   let validationSummary = 'skipped (fresh)'
   if (force || changed || !fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) {
     for (let cycle = 1; cycle <= 3; cycle++) {
-      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Write the validation report and return valid plus a findings array (one string per remaining gap). Do not dispatch other agents.', { label: `validation:${cycle}`, schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } } }, required: ['valid', 'findings'] } })
+      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), and the full validation report content. Do not dispatch other agents.', { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, file('Requirements'), file('Tech-Spec')])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, report: { type: 'string' } }, required: ['valid', 'findings', 'report'] } })
       const text = result.findings.join('\n')
       if (result.valid && result.findings.length === 0) {
         if (!fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) throw new Error('Validation agent did not produce its report')
@@ -36,8 +39,8 @@ return c.run(meta.name, featureDir, prefix, async () => {
         break
       }
       if (cycle === 3) throw new Error('Validation gaps remain after 3 cycles')
-      if (!text.includes('Tech-Spec') || text.includes('Requirements')) await c.worker(reqId, featurePath)
-      if (!text.includes('Requirements') || text.includes('Tech-Spec')) await c.worker(specId, featurePath)
+      if (!text.includes('Tech-Spec') || text.includes('Requirements')) await requirements()
+      if (!text.includes('Requirements') || text.includes('Tech-Spec')) await techSpec()
     }
   }
   c.append(`${featureDir}/${prefix}-process-log.txt`, `[${new Date().toISOString()}] pm-phase1: ${validationSummary}; Gate 1 approval requested\n`)

package/src/claude/workflows/pm-phase2.js

@@ -14,8 +14,10 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const approvals = c.read(file('Approvals.md'))
   const gate = approvals.match(/^## Gate 1\b[^\n]*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m)
   if (!gate || !/✅\s*Approved/.test(gate[1])) throw new Error('Gate 1 approval evidence missing')
-  await c.worker('gaia.agent.planner.work-breakdown', featurePath)
   const jsonPath = file('Work-Breakdown.json')
+  await c.worker('gaia.agent.planner.work-breakdown', featurePath, {
+    outputs: [{ path: jsonPath, inputs: [featurePath, file('Requirements.md'), file('Tech-Spec.md')] }],
+  })
   const report = await c.activity('wb-validate', async () => {
     const res = c.command(['run-asset', 'scripts/wb-validate.js', '--project', c.root,
       '--', jsonPath, file('Requirements.md')], [0, 1])