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,67 @@
 
 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.
+* **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/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

core/hooks/aidlc-sync-statusline.ts

@@ -1,19 +1,34 @@
-// PostToolUse hook: Sync aidlc-state.md on stage task activation
-// Triggered on TaskUpdate — extracts slug from activeForm "[slug]" suffix
-// Receives JSON on stdin from Claude Code
+// PostToolUse hook: Sync aidlc-state.md current stage.
+//
+// Two activation paths, distinguished by the payload:
+//   1. Claude Code / Kiro CLI — a TaskUpdate carrying status + activeForm
+//      "[slug]". Fires on transition to in_progress; the slug comes from the
+//      activeForm suffix.
+//   2. Kiro IDE — the IDE gives no task payload (toolArgs is empty), so the
+//      adapter sends tool_input.source = "ide-audit-sync" and this hook reads
+//      the latest STAGE_STARTED slug from the audit tail instead. Payload-free.
+// In both cases the slug is reconciled into the state file via set-status.
+// Receives JSON on stdin from the adapter / Claude Code.
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   type ClaudeCodeHookInput,
+  getField,
+  hookDebug,
   hooksHealthDir,
   isClaudeCodeHookInput,
   isoTimestamp,
+  latestStartedStageSlug,
+  parseCheckboxes,
+  readAllAuditShards,
+  readStateFile,
   resolveProjectDirFromHook,
   stateFilePath,
   harnessDir,
 } from "../tools/aidlc-lib.ts";
 
 const projectDir = resolveProjectDirFromHook(import.meta.url);
+hookDebug(projectDir, "sync-statusline", "invoked");
 
 // Read JSON from stdin. Exit cleanly if stdin is a TTY — no Claude Code JSON
 // coming in this scenario (test / direct-run / debug-mode inherited stdin).
@@ -29,30 +44,70 @@ try {
   process.exit(0);
 }
 
-const status = parsed.tool_input?.status ?? "";
-
-// Only fire when a task transitions to in_progress
-if (status !== "in_progress") process.exit(0);
-
-const activeForm: string = parsed.tool_input?.activeForm ?? "";
-if (!activeForm) process.exit(0);
-
-// Extract slug from "[slug]" suffix in activeForm
-const slugMatch = activeForm.match(/\[([a-z][a-z0-9-]*)\]$/);
-if (!slugMatch) process.exit(0);
-const slug = slugMatch[1];
-
 // State file must exist (won't exist before handleInit runs)
 const stateFile = stateFilePath(projectDir);
 if (!existsSync(stateFile)) process.exit(0);
 
+// Resolve the target slug by activation path.
+let slug = "";
+const source = parsed.tool_input?.source ?? "";
+if (source === "ide-audit-sync") {
+  // Kiro IDE path: derive the current stage from the audit tail (payload-free).
+  // This is a FORWARD-ONLY mirror: it may only nudge Current Stage toward the
+  // latest STAGE_STARTED, never backward. Without the guards below, the last
+  // STAGE_STARTED lingers after a stage completes (approve advances Current
+  // Stage / finalize sets it to none + Status: Completed but emits no new
+  // STAGE_STARTED), so a naive "audit != state → set-status" would resurrect a
+  // finished stage — set-status forces Status: Running and flips the checkbox
+  // back to in-progress. Guards, in order:
+  const stateContent = readStateFile(projectDir);
+  const status = (getField(stateContent, "Status") ?? "").trim();
+  const current = (getField(stateContent, "Current Stage") ?? "").trim();
+  const audit = readAllAuditShards(projectDir);
+  const auditSlug = latestStartedStageSlug(audit);
+  hookDebug(projectDir, "sync-statusline", "ide-audit-sync", { auditSlug, current, status });
+
+  // (a) Only sync a live, running workflow. A completed/parked workflow (Status
+  //     != Running) or a cleared pointer (Current Stage none/empty) is ahead of
+  //     the audit tail by design — never rewind it.
+  if (status !== "Running") process.exit(0);
+  if (current === "" || current === "none") process.exit(0);
+  // (b) No audit slug, or it already matches state → nothing to do.
+  if (!auditSlug) process.exit(0);
+  if (current === auditSlug) process.exit(0);
+  // (c) Never sync BACKWARD: if the audit slug is a stage the workflow has
+  //     already completed or skipped, the state is legitimately ahead of it
+  //     (the stage finished; a newer STAGE_STARTED just wasn't the last row).
+  //     Syncing would demote a done stage — refuse.
+  const checkboxes = parseCheckboxes(stateContent);
+  const auditCb = checkboxes.find((c) => c.slug === auditSlug);
+  if (auditCb && (auditCb.state === "completed" || auditCb.state === "skipped")) {
+    hookDebug(projectDir, "sync-statusline", "skip: audit slug already done/skipped", {
+      auditSlug,
+      auditState: auditCb.state,
+    });
+    process.exit(0);
+  }
+  slug = auditSlug;
+} else {
+  // Claude Code / Kiro CLI path: TaskUpdate → in_progress with "[slug]" suffix.
+  const status = parsed.tool_input?.status ?? "";
+  if (status !== "in_progress") process.exit(0);
+  const activeForm: string = parsed.tool_input?.activeForm ?? "";
+  if (!activeForm) process.exit(0);
+  const slugMatch = activeForm.match(/\[([a-z][a-z0-9-]*)\]$/);
+  if (!slugMatch) process.exit(0);
+  slug = slugMatch[1];
+}
+
 // Health heartbeat
 const healthDir = hooksHealthDir(projectDir);
 mkdirSync(healthDir, { recursive: true });
 writeFileSync(join(healthDir, "sync-statusline.last"), isoTimestamp(), "utf-8");
 
 // Update state file via set-status (call the utility tool directly)
 const toolPath = join(projectDir, harnessDir(), "tools", "aidlc-utility.ts");
+hookDebug(projectDir, "sync-statusline", "set-status", { slug });
 Bun.spawnSync(["bun", toolPath, "set-status", "--stage", slug, "--project-dir", projectDir], {
   stdout: "ignore",
   stderr: "ignore",