arkaos 4.38.0 → 4.40.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.38.0 — 89 agents, 17 departments, 332 skills, 297 commands, 17 ADRs.
+> v4.40.0 — 89 agents, 17 departments, 332 skills, 297 commands, 17 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.38.0
+4.40.0

package/bin/arka-doctor

@@ -162,9 +162,10 @@ if [ "$FIX_MODE" = true ] && [ "$HOOKS_OK" = false ]; then
       --arg pc "$HOOKS_DIR/pre-compact.sh" \
       --arg ptu "$HOOKS_DIR/post-tool-use.sh" \
       '{
-        "UserPromptSubmit": [{"hooks":[{"type":"command","command":$ups,"timeout":10}]}],
+        "UserPromptSubmit": [{"hooks":[{"type":"command","command":$ups,"timeout":20}]}],
         "PreCompact": [{"hooks":[{"type":"command","command":$pc,"timeout":30}]}],
-        "PostToolUse": [{"hooks":[{"type":"command","command":$ptu,"timeout":5}]}]
+        "PostToolUse": [{"hooks":[{"type":"command","command":$ptu,"timeout":5}]}],
+        "PostToolUseFailure": [{"hooks":[{"type":"command","command":$ptu,"timeout":5}]}]
       }')
     jq --argjson hooks "$HOOKS_JSON" '.hooks = $hooks' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp" && \
       mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"

package/config/hooks/_lib/fastpath/engine.cjs

@@ -17,7 +17,10 @@
  * this file — that is exactly the drift the manifest exists to kill.
  */
 
-const SCHEMA_VERSION = 1;
+// v2: post.success_exit_codes removed with the PostToolUseFailure
+// wiring — an old engine + new manifest mismatch now delegates via
+// validateManifest instead of crashing into the shim's fail-open {}.
+const SCHEMA_VERSION = 2;
 
 /** Python truthiness — NOT JS Boolean(): [] and {} are falsy in Python,
  *  "false" (non-empty string) is truthy in both. flow_enforcer coerces
@@ -255,6 +258,34 @@ function flowAuthFresh(sid, manifest, ctx) {
   return nowSeconds - ts <= manifest.numbers.auth_ttl_seconds;
 }
 
+/** Textual output of a PostToolUse tool_response — parity with the
+ *  PostToolUse paths of _tool_text in post_tool_use.py (string,
+ *  stdout/stderr and Task/content shapes, isAsync guard and Python's
+ *  `or ""` falsy coercion included). Failure-event payloads never
+ *  reach this — decidePost delegates PostToolUseFailure outright. */
+function toolText(payload) {
+  const response = payload.tool_response;
+  if (typeof response === "string") return response;
+  if (response && typeof response === "object") {
+    if ("stdout" in response || "stderr" in response) {
+      return [response.stdout, response.stderr]
+        .map((part) => String(part || ""))
+        .filter(Boolean)
+        .join("\n");
+    }
+    if (response.isAsync) return "";
+    const content = response.content;
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content
+        .filter((block) => block && block.type === "text")
+        .map((block) => String(block.text || ""))
+        .join("");
+    }
+  }
+  return "";
+}
+
 /**
  * PostToolUse decision. Returns
  *   {action:"fast-exit", stdout:"{}", writes:[...]} — mcp telemetry only
@@ -267,18 +298,23 @@ function decidePost(payload, manifest, ctx) {
   }
   const toolName = String(payload.tool_name || "");
 
+  // A failing tool throws inside the runtime and fires
+  // PostToolUseFailure (2.1.220 contract) — failed-command turns are
+  // the gotchas pipeline's primary material, so they always go to
+  // Python. Rare by construction: no fast path is worth having here.
+  if (payload.hook_event_name === "PostToolUseFailure") {
+    return { action: "delegate", reason: "failure-event" };
+  }
+
   // Q3/Q4 — plan approval (G2) + subagent tracking live in Python.
   if (manifest.tools.post_delegate_always.includes(toolName)) {
     return { action: "delegate", reason: "post-stateful-tool" };
   }
 
   // Q5 — error path: gotchas, violations, cognition capture, metrics.
-  const exitCode = String(payload.exit_code ?? "") || "0";
-  if (!manifest.post.success_exit_codes.includes(exitCode)) {
-    return { action: "delegate", reason: "error-exit-code" };
-  }
-  const toolOutput = String(payload.tool_output ?? "");
-  if (compileRegex(manifest.post.error_trigger).test(toolOutput)) {
+  // PostToolUse never carries an exit code (failures fire the event
+  // above), so the only error signal on this path is trigger text.
+  if (compileRegex(manifest.post.error_trigger).test(toolText(payload))) {
     return { action: "delegate", reason: "error-trigger" };
   }
 
@@ -333,5 +369,6 @@ module.exports = {
   pythonTruthy,
   readJsonFile,
   safeSessionId,
+  toolText,
   validateManifest,
 };

package/config/hooks/cwd-changed.ps1

@@ -2,13 +2,17 @@
 # ArkaOS — CwdChanged Hook (Windows / PowerShell 5.1+)
 #
 # Port of config/hooks/cwd-changed.sh. Fires when the working directory
-# changes. Detects ecosystem and stack so Claude knows which squad and
-# tooling apply to the project.
+# changes. Detects the ecosystem/stack and surfaces them to the operator
+# as a system message.
 #
 # Contract:
 # - Reads a JSON object on stdin with a `cwd` field.
-# - Emits `{"additionalContext": "..."}` on stdout when context is found,
-#   or nothing (and exit 0) when there is nothing to say.
+# - Emits `{"systemMessage": "..."}` on stdout when context is found, or
+#   nothing (and exit 0) when there is nothing to say. CwdChanged's
+#   hookSpecificOutput accepts watchPaths only (Claude Code 2.1.220) —
+#   additionalContext is unreachable on this event. On later prompts the
+#   cwd-reading Synapse layers refresh (git branch, graph context,
+#   knowledge retrieval, cwd-scoped session memory).
 # ============================================================================
 
 $ErrorActionPreference = 'Stop'
@@ -148,5 +152,7 @@ if ($descriptor) {
 }
 
 if ($context) {
-    [pscustomobject]@{ additionalContext = $context } | ConvertTo-Json -Compress
+    # CwdChanged accepts no additionalContext (watchPaths only) — the
+    # top-level systemMessage is the one deliverable surface on this event.
+    [pscustomobject]@{ systemMessage = $context } | ConvertTo-Json -Compress
 }

package/config/hooks/cwd-changed.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 # ============================================================================
 # ArkaOS — CwdChanged Hook
-# Fires when the working directory changes. Detects ecosystem and injects
-# project context so Claude knows which squad and stack to use.
+# Fires when the working directory changes. Detects the ecosystem/stack
+# and surfaces a systemMessage naming them (the one deliverable surface
+# on this event — CwdChanged's hookSpecificOutput accepts watchPaths
+# only).
 # ============================================================================
 
 input=$(cat)
@@ -116,7 +118,12 @@ if [ -n "$DESCRIPTOR" ]; then
 fi
 
 if [ -n "$CONTEXT" ]; then
-  # Build the JSON with jq so any quote/backslash in the ecosystem name or
+  # CwdChanged's hookSpecificOutput accepts watchPaths ONLY (Claude Code
+  # 2.1.220 schema) — additionalContext is unreachable on this event. The
+  # top-level systemMessage key IS consumed and surfaced to the operator.
+  # On later prompts the cwd-reading Synapse layers refresh (git branch,
+  # graph context, knowledge retrieval, cwd-scoped session memory).
+  # Built with jq so any quote/backslash in the ecosystem name or
   # descriptor path is escaped, never breaking the envelope (OWASP A03).
-  jq -nc --arg ctx "$CONTEXT" '{additionalContext: $ctx}'
+  jq -nc --arg msg "$CONTEXT" '{systemMessage: $msg}'
 fi

package/config/hooks/gate-manifest.json

@@ -635,13 +635,9 @@
       "flags": "i",
       "js": "(error:|fatal:|exception:|failed|ENOENT|EACCES|EPERM|panic:)",
       "py": "(error:|fatal:|exception:|failed|ENOENT|EACCES|EPERM|panic:)"
-    },
-    "success_exit_codes": [
-      "0",
-      ""
-    ]
+    }
   },
-  "schema_version": 1,
+  "schema_version": 2,
   "session_id": {
     "flags": "",
     "js": "^[A-Za-z0-9._-]{1,128}$",

package/config/hooks/post-tool-use.ps1

@@ -6,8 +6,16 @@
 # which mistakes repeat across projects.
 #
 # Contract:
-# - Reads a hook payload JSON from stdin (tool_name, tool_output, exit_code,
-#   cwd).
+# - Reads a hook payload JSON from stdin. Registered for two events
+#   (2.1.220 contract): PostToolUse delivers a structured tool_response
+#   (Bash dicts carry stdout/stderr; this port handles the string and
+#   stdout/stderr shapes only — no Task/content path); a failing tool
+#   throws inside the runtime and fires PostToolUseFailure instead,
+#   which carries the output in `error`, prefixed "Exit code N" for
+#   Bash. The payload has no top-level output or exit-code fields.
+#   Also read: tool_name, cwd, session_id, and a legacy
+#   assistant_message the payload never carries (dead read, see
+#   core/hooks/post_tool_use.py `_confirm_flow_authorization`).
 # - Always exits 0 and writes `{}` on stdout — PostToolUse does not inject
 #   context.
 # - Side effect: updates %USERPROFILE%\.arkaos\gotchas.json and
@@ -100,7 +108,7 @@ $stdinText = [Console]::In.ReadToEnd()
 $shouldProcessGotchas = $true
 $payload = $null
 $toolName = ''
-$toolOutput = ''
+$toolText = ''
 $exitCode = '0'
 $cwd = ''
 
@@ -116,10 +124,37 @@ if ([string]::IsNullOrWhiteSpace($stdinText)) {
 
 if ($shouldProcessGotchas -and $null -ne $payload) {
     $toolName   = if ($null -ne $payload.tool_name)   { [string]$payload.tool_name   } else { '' }
-    $toolOutput = if ($null -ne $payload.tool_output) { [string]$payload.tool_output } else { '' }
-    $exitCode   = if ($null -ne $payload.exit_code)   { [string]$payload.exit_code   } else { '0' }
     $cwd        = if ($null -ne $payload.cwd)         { [string]$payload.cwd         } else { '' }
 
+    # Event → (text, exit code). Mirrors the string and stdout/stderr
+    # paths of _tool_text / _tool_exit_code in core/hooks/post_tool_use.py
+    # (no Task/content path in this port). On PostToolUseFailure the
+    # output arrives in `error`; the runtime's "Exit code N" envelope is
+    # its wrapper, not command output, so it is stripped from the text
+    # and surfaced as the exit code. A user interrupt is not a failure.
+    $eventName = if ($null -ne $payload.hook_event_name) { [string]$payload.hook_event_name } else { '' }
+    if ($eventName -eq 'PostToolUseFailure') {
+        $errText = if ($null -ne $payload.error) { [string]$payload.error } else { '' }
+        $envMatch = [regex]::Match($errText, '^Exit code (\d+)\n?')
+        if ($envMatch.Success) {
+            $exitCode = $envMatch.Groups[1].Value
+            $toolText = $errText.Substring($envMatch.Length)
+        } else {
+            $exitCode = '1'
+            $toolText = $errText
+        }
+        if ($payload.is_interrupt) { $exitCode = '0' }
+    } else {
+        $resp = $payload.tool_response
+        if ($resp -is [string]) {
+            $toolText = $resp
+        } elseif ($null -ne $resp) {
+            $stdoutPart = if ($null -ne $resp.stdout) { [string]$resp.stdout } else { '' }
+            $stderrPart = if ($null -ne $resp.stderr) { [string]$resp.stderr } else { '' }
+            $toolText = (@($stdoutPart, $stderrPart) | Where-Object { $_ }) -join "`n"
+        }
+    }
+
     # --- Flow marker cache write (v2 ALLOW accelerator) ------------------
     # Mirror of the bash hook: detect [arka:routing] or [arka:trivial] in
     # $payload.assistant_message and persist via core.workflow.marker_cache.
@@ -211,7 +246,7 @@ except Exception:
     # ─── Only process when there is actually an error ─────────────────
     $errorPattern = '(?i)(error:|fatal:|exception:|failed|ENOENT|EACCES|EPERM|panic:)'
     if ($exitCode -eq '0' -or [string]::IsNullOrEmpty($exitCode)) {
-        if ($toolOutput -notmatch $errorPattern) {
+        if ($toolText -notmatch $errorPattern) {
             $shouldProcessGotchas = $false
         }
     }
@@ -230,7 +265,7 @@ $null = New-Item -ItemType Directory -Force -Path $arkaosRuntimeDir -ErrorAction
 if ($shouldProcessGotchas) { do {
 
 # ─── Extract first meaningful error line ─────────────────────────────
-$lines = $toolOutput -split "`r?`n"
+$lines = $toolText -split "`r?`n"
 $errorLineRegex = '(?i)(error|fatal|exception|failed|ENOENT|EACCES|EPERM|panic|cannot|not found|permission denied)'
 $errorLine = $null
 foreach ($ln in $lines) {

package/config/hooks/session-start.sh

@@ -18,8 +18,32 @@ export ARKA_HOOK_CWD="$_HOOK_CWD"
 _ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
 if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
 
+# ─── Resolve the root via the shared resolver (one root per session) ───
+# Reading .repo-path raw diverged from every other hook: the file points
+# at an npx cache that `npm cache clean` can purge, while
+# arka_resolve_root falls through to the ~/.arkaos/lib snapshot. The
+# chosen root AND source both travel to the entrypoint so the session
+# can name the root it actually ran from ([arka:root]).
 REPO=""
-[ -f "$HOME/.arkaos/.repo-path" ] && REPO=$(cat "$HOME/.arkaos/.repo-path")
+ARKA_ROOT_SOURCE="legacy"
+if command -v arka_resolve_root >/dev/null 2>&1; then
+  [ -n "${ARKAOS_ROOT:-}" ] && ARKA_ROOT_SOURCE="env"
+  REPO="$(arka_resolve_root)"
+  if [ "$ARKA_ROOT_SOURCE" != "env" ]; then
+    if [ -f "$HOME/.arkaos/.repo-path" ] \
+       && [ "$REPO" = "$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null)" ]; then
+      ARKA_ROOT_SOURCE="repo-path"
+    elif [ "$REPO" = "$HOME/.arkaos/lib" ]; then
+      ARKA_ROOT_SOURCE="lib-snapshot"
+    else
+      ARKA_ROOT_SOURCE="fallback"
+    fi
+  fi
+elif [ -f "$HOME/.arkaos/.repo-path" ]; then
+  REPO=$(cat "$HOME/.arkaos/.repo-path")
+fi
+export ARKA_ROOT_SOURCE
+export ARKA_ROOT="$REPO"
 
 # The MODULE file is the guard, not just core/: an older installed
 # snapshot without it would exec into "No module named ..." (exit 1,

package/config/hooks/user-prompt-submit.ps1

@@ -1,17 +1,19 @@
 # ============================================================================
 # ArkaOS v2 - UserPromptSubmit Hook (Synapse Bridge) (Windows / PowerShell 5.1+)
 #
-# Port of config/hooks/user-prompt-submit.sh. Calls the Python Synapse bridge
-# for 8-layer context injection, with a pure-PowerShell fallback for
-# installations where Python is unavailable or the bridge is missing.
+# Port of config/hooks/user-prompt-submit.sh. Calls the Python Synapse
+# bridge for layered context injection, with a pure-PowerShell fallback
+# for installations where Python is unavailable or the bridge is missing.
 #
 # Contract:
 # - Reads a JSON payload from stdin (userInput / message / raw).
 # - Emits a single-line JSON object on stdout:
-#       {"additionalContext": "<sync-notice><synapse-or-fallback>"}
+#       {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit",
+#        "additionalContext": "<sync-notice><route-reminder> <synapse-or-fallback>"}}
+#   (a top-level additionalContext key is ignored by Claude Code)
 # - Side effect: writes one line to the cache metrics JSONL.
 #
-# Target latency: <100ms (hook timeout is 10s in settings).
+# Target latency: <100ms (hook timeout is 20s in settings).
 #
 # File is pure ASCII. Any typographic characters that need to appear in the
 # output are built from [char] codes at runtime so PS 5.1's default ANSI
@@ -54,7 +56,7 @@ if (-not $v2Installed) {
     foreach ($v1 in $v1Paths) {
         if ((Test-Path -LiteralPath $v1 -PathType Container) -and -not (Test-Path -LiteralPath $migrationMarker)) {
             $msg = "[MIGRATION] ArkaOS v1 detected at $v1. Run: npx arkaos migrate - This will backup v1, preserve your data, and install v2. See: https://github.com/andreagroferreira/arka-os#install"
-            [pscustomobject]@{ additionalContext = $msg } | ConvertTo-Json -Compress
+            [pscustomobject]@{ hookSpecificOutput = [pscustomobject]@{ hookEventName = 'UserPromptSubmit'; additionalContext = $msg } } | ConvertTo-Json -Compress -Depth 4
             exit 0
         }
     }
@@ -336,7 +338,7 @@ $routeReminder = '[arka:route] Every response MUST route through a department sq
 
 # --- Output ----------------------------------------------------------------
 $additionalContext = "$syncNotice$routeReminder $pythonResult"
-[pscustomobject]@{ additionalContext = $additionalContext } | ConvertTo-Json -Compress
+[pscustomobject]@{ hookSpecificOutput = [pscustomobject]@{ hookEventName = 'UserPromptSubmit'; additionalContext = $additionalContext } } | ConvertTo-Json -Compress -Depth 4
 
 # --- Metrics (JSONL append) ------------------------------------------------
 $elapsed = [int]$sw.ElapsedMilliseconds

package/config/hooks/user-prompt-submit.sh

@@ -20,7 +20,8 @@
 #   - One-shot nudges (KB-cite, meta-tag, closing-marker) gated by
 #     effort level; cognitive context injection.
 #
-# Timeout: 10s | Output: JSON to stdout | Target: <100ms
+# Timeout: 20 s (in-hook budget ARKA_UPS_BUDGET_MS, default 6000 ms)
+# Output: JSON to stdout | Target: <100ms
 # ============================================================================
 
 # ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
@@ -44,7 +45,7 @@ elif [ -z "${ARKAOS_ROOT:-}" ]; then
 fi
 export ARKAOS_ROOT
 
-_ARKA_L0_FALLBACK='{"additionalContext": "[Constitution] NON-NEGOTIABLE: branch-isolation, security-gate, mandatory-qa, evidence-flow, arkaos-not-yes-man, excellence-mandate | QUALITY-GATE: marta-cqo, eduardo-copy, francisca-tech-ux | MUST (28) incl.: squad-routing, spec-driven, conventional-commits, test-coverage, subagent-discipline, persona-vs-artifact"}'
+_ARKA_L0_FALLBACK='{"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": "[Constitution] NON-NEGOTIABLE: branch-isolation, security-gate, mandatory-qa, evidence-flow, arkaos-not-yes-man, excellence-mandate | QUALITY-GATE: marta-cqo, eduardo-copy, francisca-tech-ux | MUST (28) incl.: squad-routing, spec-driven, conventional-commits, test-coverage, subagent-discipline, persona-vs-artifact"}}'
 
 # Test seam: bats asserts the fallback CONTENT deterministically —
 # the shared resolver overwrites ARKA_PY, so an env flag is the only

package/config/settings-template.json

@@ -25,7 +25,7 @@
           {
             "type": "command",
             "command": "{{HOOKS_DIR}}/user-prompt-submit.sh",
-            "timeout": 10
+            "timeout": 20
           }
         ]
       }
@@ -52,6 +52,17 @@
         ]
       }
     ],
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{{HOOKS_DIR}}/post-tool-use.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "CwdChanged": [
       {
         "hooks": [

package/core/governance/evidence_checks.py

@@ -390,24 +390,54 @@ def _foreign_pytest_can_collect(
     return probe.returncode in (0, 5)
 
 
+def _degrade_pytest_no_tests(result: CheckResult) -> CheckResult:
+    """Map pytest exit 5 (no tests collected) to insufficient evidence.
+
+    A bare ``pytest`` in a Python project that ships no tests exits 5.
+    Absence of tests is not evidence of FAILURE, yet ``passed =
+    returncode == 0`` read exit 5 as FAIL and ``_derive_overall`` then
+    forced REJECTED at the QG (issue #354). ``_foreign_pytest_can_collect``
+    already treats exit 5 as a valid import path — this keeps that
+    precedent for the verdict: exit 5 becomes ``passed=None``
+    (non-conclusive), never ``False``.
+    """
+    if result.exit_code != 5:
+        return result
+    prefix = "no tests collected (pytest exit 5) — insufficient evidence; "
+    return replace(result, passed=None, summary=prefix + result.summary)
+
+
 def _check_tests(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
     if test_command:
-        return _run("tests", shlex.split(test_command), project_dir, timeout)
+        argv = shlex.split(test_command)
+        result = _run("tests", argv, project_dir, timeout)
+        # exit 5 is pytest's "no tests collected"; scan the first 3
+        # tokens so `python -m pytest` / `arka-py -m pytest` degrade too,
+        # while non-pytest runners (npm test) stay a real FAIL. Bounded to
+        # argv[:3] so a later test-path arg named *pytest* never matches
+        # (issue #354).
+        if any("pytest" in Path(tok).name for tok in argv[:3]):
+            return _degrade_pytest_no_tests(result)
+        return result
     if _has_python(project_dir, changed):
         local_pytest = _project_pytest(project_dir)
         if local_pytest:
             return _labelled(
-                _run("tests", [*local_pytest, "-q"], project_dir, timeout),
+                _degrade_pytest_no_tests(
+                    _run("tests", [*local_pytest, "-q"], project_dir, timeout),
+                ),
                 "tests(project-venv)",
             )
         pytest_cmd = _tool_cmd("pytest")
         if pytest_cmd and _foreign_pytest_can_collect(
             pytest_cmd, project_dir, timeout
         ):
-            return _run("tests", [*pytest_cmd, "-q"], project_dir, timeout)
+            return _degrade_pytest_no_tests(
+                _run("tests", [*pytest_cmd, "-q"], project_dir, timeout),
+            )
         if pytest_cmd:
             return _skip(
                 "tests",