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

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.11] - 2026-07-08
+
+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.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.10-blue)
+![version](https://img.shields.io/badge/version-2.2.11-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,5 +38,19 @@ If the stage definition lists validation tools, **run them** before writing your
 - Cross-reference everything. If it's referenced, it must exist. If it exists, it should be referenced.
 - 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

@@ -869,6 +869,9 @@ If the `run-stage` directive includes a `reviewer` field (non-null), the orchest
    - Reads the artifact(s) to evaluate what WAS produced
    - 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