fix(kiro-ide): make hooks work via USER_PROMPT env, not stdin (#471)

Kiro IDE delivers hook context through the USER_PROMPT environment
variable (not stdin, which it opens but never writes), and leaves
toolArgs empty. The IDE adapter now reads USER_PROMPT, recovers the
written file path from the tool-result prose, and drives the
command/payload-free hooks off the audit trail.

- audit-logger, sensor-fire, runtime-compile, sync-statusline now do
  real work on Kiro IDE; write paths resolved relative to workspace root.
- runtime-compile and sync-statusline gate on the audit tail (payload-free).
- sync-statusline ide-audit-sync is forward-only (never rewinds Current
  Stage): skips when not Running, pointer none, or audit slug already
  completed/skipped.
- runtime-compile IDE path adds an mtime idempotency guard so a lingering
  transition does not recompile on every subsequent shell command.
- extractWrittenPath tolerates trailing newlines, strips a str_replace
  " (N occurrences)" suffix, and records a visible hook-drop when a
  write-class tool yields no extractable path.
- latestStartedStageSlug ignores synthetic --single stage-runner rows.
- opt-in hook debug log: AIDLC_HOOK_DEBUG=1 or touch aidlc/.aidlc-hook-debug.

Kiro CLI, Claude Code, and Codex behaviour unchanged (new branches gated
behind the IDE-only ide-audit-sync marker and the opt-in debug env var).

Author: SiddhJog

CHANGELOG.md

@@ -2,6 +2,72 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.17] - 2026-07-09
+
+Fixes the Kiro IDE harness's hooks, which previously no-op'd for everything that
+needed to know what the agent just did. Kiro IDE delivers hook context through
+the `USER_PROMPT` environment variable (not stdin, which it opens but never
+writes), and it leaves the tool arguments empty — so the IDE adapter now reads
+`USER_PROMPT`, recovers the written file path from the tool result text, and
+drives the command/payload-free hooks off the audit trail instead. The audit
+logger, sensor firing, runtime-graph recompile, and statusline sync now work in
+Kiro IDE without the agent having to compile the graph by hand. Dropping the
+stdin read also removes the 2s stdin-race timeout the CLI adapter paid on every
+hook; the human-presence mint/block hooks now resolve the project dir from
+`process.cwd()`. The Kiro CLI harness is unaffected (it uses a separate adapter
+and a working stdin channel). Re-copy your `dist/kiro-ide/.kiro/` to pick up the
+fix.
+
+* **Kiro IDE hooks fire correctly** — `aidlc-audit-logger`, `aidlc-sensor-fire`,
+  `aidlc-runtime-compile`, and `aidlc-sync-statusline` now do real work on Kiro
+  IDE. Artifact writes are audited, sensors run, the runtime graph recompiles on
+  transitions, and `Current Stage` stays in sync.
+* **File paths are resolved relative to the workspace root.** Kiro IDE reports
+  the written path relative to the project root in the tool-result text; the
+  adapter resolves it to absolute so `audit-logger`'s record-root check passes.
+* **`aidlc-runtime-compile` and `aidlc-sync-statusline` are payload-free on the
+  IDE** — both gate on the audit tail (latest transition / latest
+  `STAGE_STARTED`) instead of the tool command or task payload the IDE does not
+  surface. `aidlc-sync-statusline` is wired to the `shell` tool event.
+* **The IDE audit-tail gating is forward-only and idempotent.**
+  `aidlc-sync-statusline` never rewinds `Current Stage`: it skips when the
+  workflow is not `Running`, when the pointer is `none`, or when the audit's
+  latest stage is already completed/skipped. `latestStartedStageSlug` ignores
+  synthetic `--single` stage-runner rows. `aidlc-runtime-compile`'s IDE path
+  adds an mtime idempotency guard so a lingering transition (e.g. after
+  `WORKFLOW_COMPLETED`) does not recompile on every subsequent shell command.
+* **The `str_replace`/`fs_append` path extraction is robust.** The adapter
+  tolerates trailing newlines, strips a `str_replace` ` (N occurrences)`
+  suffix, and records a visible hook-drop when a write-class tool yields no
+  extractable path (no silent no-op).
+* **The human-presence mint/block hooks survive the stdin removal.** The
+  `promptSubmit` mint (`HUMAN_TURN`) and the `preToolUse` block floor now
+  resolve the project dir from `process.cwd()` (the IDE gives no `cwd` payload),
+  so the Kiro IDE human-presence gate keeps working; dropping the stdin read
+  also removes the 2s stdin-race the block hook paid on every `preToolUse`.
+* **`log-subagent` records the delegate's identity.** The adapter no longer
+  hardcodes `agent_type: "unknown"`; it extracts the self-identifying first line
+  (`**Reviewer:** <name>` / `**Agent:** <name>`) from the subagent result and
+  forwards the result text, so `SUBAGENT_COMPLETED` carries the real agent. The
+  two reviewer agents (`aidlc-product-lead-agent`,
+  `aidlc-architecture-reviewer-agent`) now emit that identity marker as the
+  first line of their response (an Output Contract in their persona, reinforced
+  in stage-protocol §12a), so the audit trail names which reviewer ran instead
+  of recording `unknown`.
+* **Failed tool calls are not audited as writes.** `audit-and-sensors`
+  explicitly guards `toolSuccess === false`, so a failed op no longer relies on
+  its error prose failing to match the path regexes.
+* **Opt-in hook debug log.** Enable it to have every hook append its decision
+  path to `<record>/.aidlc-hooks-health/hook-debug.log` — either set
+  `AIDLC_HOOK_DEBUG=1`, or `touch aidlc/.aidlc-hook-debug` (the filesystem
+  marker takes effect on the next hook fire with no IDE restart). Off by
+  default (no log, no overhead); see the Kiro IDE harness guide.
+* **Behaviour for Kiro CLI, Claude Code, and Codex is unchanged.** The shared
+  core hooks are edited and re-shipped to all four dists, but the new branches
+  are gated behind the IDE-only `ide-audit-sync` marker (and the opt-in
+  `AIDLC_HOOK_DEBUG` env var), so the CLI/Claude/Codex payload paths behave
+  exactly as before.
+
 ## [2.2.16] - 2026-07-09
 
 The architecture reviewer's read scope is now bounded to the artifacts under review plus the shared inception contracts the stage `consumes:`. On per-unit Construction stages (`functional-design`, `nfr-requirements`, `nfr-design`, `infrastructure-design`, `code-generation`) the reviewer previously had no read-scope constraint and its persona pushed a "cross-reference everything" sweep, so reviewing unit N read sibling units' `construction/<other-unit>/` directories and per-unit cost grew linearly with unit count. Stage-protocol §12a now extends the per-unit reviewer pass-list with `directive.consumes`, the persona and knowledge scope "cross-reference" to what was passed, and the four harness orchestrators (Claude Code, Kiro CLI, Kiro IDE, Codex CLI) append the same bound to their reviewer step. Cross-unit contract verification runs against the shared inception artifacts; sibling-unit files may be spot-checked only when the current unit's design explicitly names an integration point in them. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.
@@ -53,6 +119,7 @@ Gate-revision backstop: the conductor sometimes revises a stage's artifact at an
 * `Revision Count` now reflects a revision made at an open gate even when the conductor skipped the `reject` verb: `approve` backfills the count and the audit pair. Run `reject` yourself when you request changes so your feedback text is still recorded.
 * NEW `Recovered: true` variants of the `GATE_REJECTED` and `STAGE_REVISING` audit rows, emitted by the approve-time backstop when it backfills a skipped rejection.
 * NEW `AIDLC_SKIP_REVISION_BACKSTOP=1` off-switch disables the backstop (mirrors `AIDLC_SKIP_ARTIFACT_GUARD`); the test suite sets it globally so existing approve flows are unaffected.
+
 ## [2.2.10] - 2026-07-06
 
 Workspace detection now recognizes git submodules. A workspace whose code lives in uninitialized submodules (empty dirs plus a `.gitmodules` file) previously scanned as Greenfield, so reverse-engineering was auto-skipped and every design stage ran with zero code understanding. The scanner gains a sixth brownfield signal: a parseable `.gitmodules` with at least one submodule path entry classifies the workspace Brownfield. When submodule paths are uninitialized, the scan warns and names the remedy (`git submodule update --init --recursive`) at birth, in the doctor report, and on `detect`. Languages stay as scanned (Unknown is truthful until the submodules are fetched). **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

README.md

@@ -8,7 +8,7 @@ A native implementation of the **AI-DLC methodology** (AI-Driven Development Lif
 
 The methodology lives once, in a harness-neutral `core/`; each harness adds a thin surface that decides how it shows up on that harness. So you edit the methodology in one place, and every harness distribution is generated from it — no harness gets special treatment. (See [Repository layout](#repository-layout) for how the pieces fit together.)
 
-![version](https://img.shields.io/badge/version-2.2.16-blue)
+![version](https://img.shields.io/badge/version-2.2.17-blue)
 ![license](https://img.shields.io/badge/license-MIT--0-green)
 ![Kiro IDE](https://img.shields.io/badge/harness-Kiro%20IDE-orange)
 ![Kiro CLI](https://img.shields.io/badge/harness-Kiro%20CLI-orange)

core/agents/aidlc-architecture-reviewer-agent.md

@@ -38,6 +38,20 @@ If the stage definition lists validation tools, **run them** before writing your
 - Cross-reference everything within the artifacts under review and the contracts you were passed. If it's referenced there, it must exist there or in the passed contracts. If it exists in the artifacts under review, it should be referenced. Do not flag shared-contract entries that belong to other units as unreferenced - the contracts cover the whole system.
 - Think one layer deeper. The design says "use a queue" — but what about ordering? Retries? Dead letters?
 - Implementation is the test. If you can't mentally trace a request through the system end-to-end, it's incomplete.
+
+## Output Contract
+
+The FIRST line of the response you return to the orchestrator MUST be your
+identity marker, verbatim:
+
+```
+**Reviewer:** aidlc-architecture-reviewer-agent
+```
+
+This is how the audit trail records WHICH reviewer ran (the `SUBAGENT_COMPLETED`
+event reads it from your first line). Do not omit it, reword it, or place other
+text before it. After that line, give your verdict (READY / NOT-READY) and
+findings as usual.
 - Run the tools. They catch structural issues. You catch architectural issues. Together = thorough.
 - READY means "a developer could build this system without architectural guidance beyond this document."
 

core/agents/aidlc-product-lead-agent.md

@@ -36,3 +36,17 @@ You are a senior product leader — the person who signs off before work goes to
 - Be specific. "Story S-4 has no acceptance criteria for the error case" beats "needs more detail."
 - Don't rewrite. Say what's wrong and what good looks like. The builder fixes.
 - READY means "engineering can start without coming back to ask questions."
+
+## Output Contract
+
+The FIRST line of the response you return to the orchestrator MUST be your
+identity marker, verbatim:
+
+```
+**Reviewer:** aidlc-product-lead-agent
+```
+
+This is how the audit trail records WHICH reviewer ran (the `SUBAGENT_COMPLETED`
+event reads it from your first line). Do not omit it, reword it, or place other
+text before it. After that line, give your verdict (READY / NOT-READY) and
+findings as usual.

core/aidlc-common/protocols/stage-protocol.md

@@ -875,6 +875,9 @@ If the `run-stage` directive includes a `reviewer` field (non-null), the orchest
    - Verifies cross-unit contract claims against the passed shared inception contracts, not by sweeping or searching sibling units' design directories (no cross-unit grep or glob patterns); opens another unit's file only when the current unit's design explicitly names it as an integration point, and only that file
    - Runs any validation tools listed (via shell) and includes results in findings
    - Appends a `## Review` section to the primary artifact file with verdict: READY or NOT-READY
+   - Returns a response whose FIRST line is its identity marker verbatim
+     (`**Reviewer:** <reviewer-agent-name>`), so the `SUBAGENT_COMPLETED` audit
+     event records which reviewer ran. The reviewer's persona owns this contract.
 
 3. **Read verdict.** After the reviewer returns, read the `## Review` section from the primary artifact:
    - **READY** → proceed to §13 learnings ritual then the approval gate

core/hooks/aidlc-audit-logger.ts

@@ -13,6 +13,7 @@ import {
   type ClaudeCodeHookInput,
   docsRoot,
   errorMessage,
+  hookDebug,
   hooksHealthDir,
   isClaudeCodeHookInput,
   isoTimestamp,
@@ -21,6 +22,7 @@ import {
 } from "../tools/aidlc-lib.ts";
 
 const projectDir = resolveProjectDirFromHook(import.meta.url);
+hookDebug(projectDir, "audit-logger", "invoked", { projectDir, cwd: process.cwd() });
 
 // Write health heartbeat
 const healthDir = hooksHealthDir(projectDir);
@@ -30,15 +32,22 @@ writeFileSync(join(healthDir, "audit-logger.last"), isoTimestamp(), "utf-8");
 // Read JSON from stdin. If stdin is a TTY (interactive shell, test harness
 // running under `bash -x`-inheriting pipeline), no JSON is coming — exit
 // cleanly instead of blocking on the terminal read.
-if (process.stdin.isTTY) process.exit(0);
+if (process.stdin.isTTY) {
+  hookDebug(projectDir, "audit-logger", "exit: stdin isTTY");
+  process.exit(0);
+}
 
 const input = await Bun.stdin.text();
 let parsed: ClaudeCodeHookInput;
 try {
   const raw: unknown = JSON.parse(input);
-  if (!isClaudeCodeHookInput(raw)) process.exit(0);
+  if (!isClaudeCodeHookInput(raw)) {
+    hookDebug(projectDir, "audit-logger", "exit: not ClaudeCodeHookInput", { input: input.slice(0, 200) });
+    process.exit(0);
+  }
   parsed = raw;
 } catch {
+  hookDebug(projectDir, "audit-logger", "exit: stdin parse failed", { input: input.slice(0, 200) });
   process.exit(0);
 }
 
@@ -54,7 +63,11 @@ const fileNorm = auditFileValue; // forward-slash form for all path matching bel
 // the bare space record root — the write is logged iff it lands under that root.
 const recordRoot = docsRoot(projectDir).replace(/\\/g, "/").replace(/\/$/, "");
 const underRecord = fileNorm === recordRoot || fileNorm.startsWith(`${recordRoot}/`);
-if (!underRecord) process.exit(0);
+hookDebug(projectDir, "audit-logger", "path-gate", { tool, file: fileNorm, recordRoot, underRecord });
+if (!underRecord) {
+  hookDebug(projectDir, "audit-logger", "exit: not under record root");
+  process.exit(0);
+}
 
 // Don't log writes to an audit shard itself (avoid recursion). The shard is
 // audit/<host>-<clone>.md under the record dir; the bare audit.md guard also
@@ -64,13 +77,17 @@ if (
   file.endsWith("\\audit.md") ||
   /[/\\]audit[/\\][^/\\]+\.md$/.test(file)
 ) {
+  hookDebug(projectDir, "audit-logger", "exit: write to audit shard (recursion guard)");
   process.exit(0);
 }
 
 const auditFile = auditFilePath(projectDir);
 
 // Don't auto-create the audit trail — the orchestrator creates it at workflow start.
-if (!existsSync(auditFile)) process.exit(0);
+if (!existsSync(auditFile)) {
+  hookDebug(projectDir, "audit-logger", "exit: audit file missing", { auditFile });
+  process.exit(0);
+}
 
 // Extract the context breadcrumb: the path relative to the record root (the
 // per-intent record dir on the new layout, or the flat `aidlc-docs/` root).
@@ -123,10 +140,12 @@ try {
     File: auditFileValue,
     Context: context,
   }, projectDir);
+  hookDebug(projectDir, "audit-logger", "emitted", { eventType, file: auditFileValue, context });
 } catch (e) {
   // Hook must be a no-op on any audit emission failure to avoid breaking the
   // user's tool call. Record the drop so `--doctor` can surface it, then
   // exit cleanly.
+  hookDebug(projectDir, "audit-logger", "exit: emit threw", { eventType, error: errorMessage(e) });
   recordHookDrop(projectDir, "audit-logger", errorMessage(e));
   process.exit(0);
 }

core/hooks/aidlc-runtime-compile.ts

@@ -21,23 +21,27 @@
 // compile's own audit emits cannot re-trigger the compile.
 
 import { spawnSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   activeIntent,
   activeSpace,
+  auditShards,
   type ClaudeCodeHookInput,
   errorMessage,
+  hookDebug,
   hooksHealthDir,
   isClaudeCodeHookInput,
   isoTimestamp,
   readAllAuditShards,
   recordHookDrop,
   resolveProjectDirFromHook,
+  runtimeGraphPath,
   harnessDir,
 } from "../tools/aidlc-lib.ts";
 
 const projectDir = resolveProjectDirFromHook(import.meta.url);
+hookDebug(projectDir, "runtime-compile", "invoked");
 
 // 1. TTY guard — exit cleanly when invoked outside a piped stdin context
 //    (interactive shell, test harness running under `bash -x`).
@@ -68,8 +72,20 @@ const command: string = parsed.tool_input?.command ?? "";
 const aidlcTransitionTool = /\bbun\b.*\.(?:claude|kiro|codex)\/tools\/aidlc-(state|jump|bolt|utility)\.ts\b/;
 const aidlcOrchestrateReport = /\bbun\b.*\.(?:claude|kiro|codex)\/tools\/aidlc-orchestrate\.ts\b.*\breport\b/;
 const aidlcRuntimeRef = /\bbun\b.*\.(?:claude|kiro|codex)\/tools\/aidlc-runtime\.ts\b/;
-if (aidlcRuntimeRef.test(command)) process.exit(0);
-if (!aidlcTransitionTool.test(command) && !aidlcOrchestrateReport.test(command)) process.exit(0);
+// IDE audit-tail mode: Kiro IDE does not surface the shell command, so the
+// command-based filter cannot run. The adapter sets source="ide-audit-sync" to
+// signal "skip the command filter and gate purely on the audit tail" (steps
+// 6-7). The audit-tail transition check is the real gate; the command filter is
+// only a cheap pre-filter that needs a command string to work.
+const ideAuditMode = (parsed.tool_input?.source ?? "") === "ide-audit-sync";
+hookDebug(projectDir, "runtime-compile", "command-gate", { ideAuditMode, command: command.slice(0, 120) });
+if (!ideAuditMode) {
+  if (aidlcRuntimeRef.test(command)) process.exit(0);
+  if (!aidlcTransitionTool.test(command) && !aidlcOrchestrateReport.test(command)) {
+    hookDebug(projectDir, "runtime-compile", "exit: command not a transition tool");
+    process.exit(0);
+  }
+}
 
 // 4. Audit read — across EVERY per-clone shard of the ACTIVE intent, NOT this
 //    hook process's own PID/clone shard. The state tool that wrote the
@@ -82,7 +98,10 @@ if (!aidlcTransitionTool.test(command) && !aidlcOrchestrateReport.test(command))
 const space = activeSpace(projectDir);
 const intent = activeIntent(projectDir, space) ?? undefined;
 const audit = readAllAuditShards(projectDir, intent, space).replace(/\r\n/g, "\n");
-if (audit.length === 0) process.exit(0);
+if (audit.length === 0) {
+  hookDebug(projectDir, "runtime-compile", "exit: audit empty");
+  process.exit(0);
+}
 
 // 5. Heartbeat — doctor reads this file's mtime to detect silent-hook failure.
 //    Kept at the bare (workspace-level) health dir to match where --doctor reads
@@ -111,7 +130,45 @@ const last3 = blocks.slice(-3);
 //    (before the orchestrator wrote any §13 entries).
 const transitionRegex = /^\*\*Event\*\*:\s*(GATE_APPROVED|STAGE_STARTED|STAGE_AWAITING_APPROVAL|AUDIT_MERGED|WORKFLOW_COMPLETED)\s*$/m;
 const hasTransition = last3.some((b) => transitionRegex.test(b));
-if (!hasTransition) process.exit(0);
+hookDebug(projectDir, "runtime-compile", "transition-gate", { hasTransition, last3count: last3.length });
+if (!hasTransition) {
+  hookDebug(projectDir, "runtime-compile", "exit: no transition in audit tail");
+  process.exit(0);
+}
+
+// 7b. Idempotency guard (IDE audit-tail mode only). On the CLI the command
+//     filter (step 3) already bounds compiles to the one Bash call that emitted
+//     the transition. In ide-audit-sync mode that filter is skipped, so the
+//     transition sits in the tail across EVERY subsequent shell command — and
+//     after WORKFLOW_COMPLETED the tail never changes again, which would make
+//     every future shell command pay a blocking recompile forever. Bound it by
+//     mtime: if runtime-graph.json is already at least as new as the newest
+//     audit shard, the tail hasn't changed since the last compile — skip. A real
+//     new transition bumps a shard's mtime past the graph and re-enables the
+//     compile. Cheap stat calls; no new marker file.
+if (ideAuditMode) {
+  try {
+    const graphMtime = statSync(runtimeGraphPath(projectDir, intent, space)).mtimeMs;
+    let newestShard = 0;
+    for (const shard of auditShards(projectDir, intent, space)) {
+      try {
+        const m = statSync(shard).mtimeMs;
+        if (m > newestShard) newestShard = m;
+      } catch {
+        // shard vanished mid-read — ignore
+      }
+    }
+    if (graphMtime >= newestShard) {
+      hookDebug(projectDir, "runtime-compile", "skip: graph newer than audit (idempotent)", {
+        graphMtime,
+        newestShard,
+      });
+      process.exit(0);
+    }
+  } catch {
+    // runtime-graph.json absent (never compiled) → fall through and compile.
+  }
+}
 
 // 8. Dispatch — sync subprocess. Hook waits for completion. On non-zero
 //    exit, record the drop for `--doctor` to surface; never block the