arkaos 5.13.0 → 5.15.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.13.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
+> v5.14.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-5.13.0
+5.15.0

package/config/evals/marketing.yaml

@@ -389,7 +389,7 @@
     the carousel frames, and the different headline options they can compare. Can you put
     that together?
   expected_properties:
-  - Produces a creative review page from the HTML template, not plain markdown
+  - Produces a self-contained HTML creative review page, not plain markdown
   - Populates the DATA object (concept tabs, in-feed preview, frame storyboard, headline variations,
     copy, destination)
   - Labels storyboard frames by narrative job rather than by pictured content
@@ -398,9 +398,9 @@
   - Does not present invented stats or stock imagery as the brand's real assets
   - Uses placeholders for unrendered frames and keeps image paths relative
   - Explains how to deliver the page (open locally / host / hand off the file)
-  rubric: Should recognize this as a creative review page request and apply references/creative-review-page.md
-    + the assets/creative-review-template.html template rather than producing plain markdown.
-    Should copy the template into the output folder and populate its DATA object with the
+  rubric: Should recognize this as a creative review page request and apply the build spec in
+    references/creative-review-page.md rather than producing plain markdown. Should build a
+    single self-contained review.html in the output folder and populate its DATA block with the
     four concepts as tabs, each with an in-feed Instagram preview, a labeled frame-by-frame
     storyboard (frames labeled by narrative job — Hook / Problem / Proof / Ask — not by pictured
     content), selectable headline variations, primary text, and destination/CTA. Should curate

package/config/hooks/_lib/arka_python.sh

@@ -154,3 +154,107 @@ arka_resolve_root() {
   fi
   printf '%s\n' "${ARKA_OS:-$HOME/.claude/skills/arkaos}"
 }
+
+# ─── Degraded-run telemetry ────────────────────────────────────────────
+# A hook that fails open and says nothing is indistinguishable from a hook
+# that ran and allowed. That ambiguity is not hypothetical: an ArkaOS venv
+# that could not `import pydantic` made every gate on one machine allow
+# silently for months, and the same silence previously kept two real bugs
+# invisible while manufacturing a third that never existed (Cross-Machine
+# Lab, X3).
+#
+# Two hard rules, both deliberate:
+#
+#   1. NEVER write to stderr. Claude Code surfaces hook stderr to the user
+#      as an error, so a diagnostic there converts a silent degradation
+#      into visible noise on every event — trading one bad failure mode
+#      for a worse one. The record goes to a file; only a reader who wants
+#      it pays for it.
+#   2. NEVER change the exit code. Fail-open is the correct posture for a
+#      governance hook: a broken interpreter must not block the user's
+#      work. This makes the degradation legible, not fatal.
+#
+# One JSON line per event, appended. Failure to write is swallowed —
+# telemetry must never be the thing that breaks a hook.
+#
+# Growth cap: mirrors DEGRADED_LOG_MAX_BYTES in core/hooks/_shared.py. This
+# writer needs it MORE than the Python one, not less — the cases it records
+# (no interpreter, missing entrypoint) fire on every single tool call, so an
+# uncapped log on a broken machine is the runaway, not a corner case.
+ARKA_DEGRADED_MAX_BYTES=5242880
+
+arka_hook_degraded() {
+  local hook="${1:-unknown}" reason="${2:-unknown}" detail="${3:-}"
+  local dir="$HOME/.arkaos/telemetry"
+  local file="$dir/hook-degraded.jsonl"
+  local stamp bytes
+  stamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null)" || stamp=""
+  # Keep detail on one line and out of the JSON grammar's way. Every C0
+  # control character (and DEL) becomes a space: a raw tab, \r or \001
+  # reaching the printf below emits a byte JSON forbids inside a string, so
+  # one degraded event carrying a Python traceback used to poison the whole
+  # line for every reader. Translated rather than deleted so words do not
+  # fuse — "expected\tgot" must stay two tokens. LC_ALL=C keeps the range
+  # byte-wise; tr pads set2 by repeating its last character (POSIX).
+  detail="$(printf '%s' "$detail" | LC_ALL=C tr '\000-\037\177' ' ' \
+    | cut -c1-400)"
+  detail="${detail//\\/\\\\}"
+  detail="${detail//\"/\\\"}"
+  if [ -f "$file" ]; then
+    bytes="$(wc -c < "$file" 2>/dev/null | tr -d ' ')"
+    case "$bytes" in
+      '' | *[!0-9]*) ;;
+      *)
+        if [ "$bytes" -ge "$ARKA_DEGRADED_MAX_BYTES" ]; then
+          mv -f "$file" "$file.1" 2>/dev/null || true
+        fi
+        ;;
+    esac
+  fi
+  {
+    mkdir -p "$dir" 2>/dev/null &&
+      printf '{"ts":"%s","hook":"%s","reason":"%s","detail":"%s"}\n' \
+        "$stamp" "$hook" "$reason" "$detail" >> "$file"
+  } 2>/dev/null || true
+  return 0
+}
+
+# Run a hook entrypoint under the resolved interpreter, recording the
+# degraded cases instead of exec'ing into silence.
+#
+# ─── Deliberate divergence: this path does NOT `exec` ───────────────────
+# Every other .sh wrapper (post-tool-use, session-start, session-end,
+# subagent-stop, user-prompt-submit) still ends in `exec "$ARKA_PY" -m …`.
+# This one cannot, and the reason is structural rather than stylistic:
+# `exec` REPLACES the shell with Python, so there is no surviving process
+# to read the exit status afterwards. Recording "the entrypoint failed"
+# requires observing the status the entrypoint exited with, which requires
+# outliving it. Restoring `exec` here would silently delete the
+# entrypoint-failed record — the single most valuable one, since it is the
+# only witness to a broken interpreter that resolves but cannot run.
+#
+# Two measured costs, accepted knowingly:
+#   1. One extra live process (this shell) for the hook's lifetime.
+#   2. On a hard kill of the wrapper (Claude Code's 10s timeout), the
+#      Python child is reparented to PID 1 instead of dying with the
+#      shell — an orphan for the remainder of its own run. Not fixable by
+#      trapping: bash defers trap handling until the foreground command
+#      returns, and backgrounding the child would redirect its stdin from
+#      /dev/null in a non-interactive shell, which breaks the hook's stdin
+#      contract outright. The orphan is short-lived and harmless; a hook
+#      that cannot report its own failure is neither.
+#
+# Exit codes pass through UNCHANGED. Note which ones are NOT failures:
+#   0  allow
+#   2  the documented deny/block code — a gate doing its job, never logged
+# Anything else means the entrypoint did not get to decide, which is
+# exactly the case worth a record.
+arka_run_hook() {
+  local hook="$1" module="$2" status
+  "$ARKA_PY" -m "$module"
+  status=$?
+  if [ "$status" -ne 0 ] && [ "$status" -ne 2 ]; then
+    arka_hook_degraded "$hook" "entrypoint-failed" "exit=$status module=$module py=$ARKA_PY"
+  fi
+  return "$status"
+}

package/config/hooks/pre-tool-use.cjs

@@ -22,6 +22,62 @@ const path = require("node:path");
 
 const FAIL_OPEN_EXIT = 0;
 
+// Growth cap, mirroring DEGRADED_LOG_MAX_BYTES in core/hooks/_shared.py
+// and ARKA_DEGRADED_MAX_BYTES in _lib/arka_python.sh.
+const DEGRADED_MAX_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Record that this shim allowed because it could not run, not because it
+ * decided — the same JSONL line, in the same file, as record_degraded() in
+ * core/hooks/_shared.py and arka_hook_degraded() in _lib/arka_python.sh:
+ * {ts,hook,reason,detail}, appended, never on stderr, never fatal, never a
+ * change to the exit code.
+ *
+ * This surface needs it most, not least. On POSIX the installer registers
+ * THIS file as the PreToolUse command whenever it and the fastpath engine
+ * are deployed (installer/adapters/claude-code.js::hookEntry), so the .sh
+ * chain — the one that carries the shell telemetry — is reached only by
+ * delegation. Every fail-open below therefore happens BEFORE any other
+ * writer exists to observe it: instrumenting only the .sh would have left
+ * the default install's three silent exits exactly as silent as before.
+ *
+ * `via=cjs` leads every detail because `unhandled-fail-open` is a reason
+ * the Python entrypoint also emits; the surface has to be readable from
+ * the line itself.
+ */
+function recordDegraded(reason, detail) {
+  try {
+    const home = process.env.HOME || require("node:os").homedir();
+    const dir = path.join(home, ".arkaos", "telemetry");
+    const file = path.join(dir, "hook-degraded.jsonl");
+    fs.mkdirSync(dir, { recursive: true });
+    try {
+      if (fs.statSync(file).size >= DEGRADED_MAX_BYTES) {
+        fs.renameSync(file, file + ".1");
+      }
+    } catch {
+      // No log yet, or one that cannot be rotated: append regardless. A
+      // cap that suppresses the record defeats the point of recording.
+    }
+    const line = JSON.stringify({
+      // Second precision, no fractional part — byte-identical to the
+      // strftime/date formats the other two writers use.
+      ts: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
+      hook: "pre-tool-use",
+      reason,
+      detail: String(detail == null ? "" : detail)
+        // JSON.stringify would escape control characters rather than emit
+        // them raw, but a tab-laden stack trace still makes the line
+        // unreadable; normalise for the same reason the shell writer does.
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .slice(0, 400),
+    });
+    fs.appendFileSync(file, line + "\n");
+  } catch {
+    // Telemetry must never be the thing that breaks a hook.
+  }
+}
+
 function readStdin() {
   try {
     return fs.readFileSync(0, "utf8");
@@ -34,6 +90,10 @@ function delegate(rawStdin) {
   const sibling = path.join(__dirname, "pre-tool-use.sh");
   if (!fs.existsSync(sibling)) {
     // Missing sibling → bash would exit 127; the contract is fail-open.
+    // A split deploy that lands the .cjs without the .sh disables every
+    // gate for the whole install, so this is the highest-stakes silent
+    // allow in the file — it never reaches the shell writer.
+    recordDegraded("delegate-target-missing", `via=cjs sibling=${sibling}`);
     process.exit(FAIL_OPEN_EXIT);
   }
   // Lazy require: the fast path never pays for child_process.
@@ -44,6 +104,16 @@ function delegate(rawStdin) {
     env: { ...process.env, ARKA_HOOK_FASTPATH: "0" },
   });
   if (result.error || result.status === null) {
+    // Two distinct degradations, both invisible until now: bash could not
+    // be spawned at all (result.error — no bash on PATH, EACCES, EMFILE),
+    // or it was killed by a signal before deciding (status null). Neither
+    // is an allow the gate chain ever made.
+    const err = result.error;
+    recordDegraded(
+      "delegate-spawn-failed",
+      `via=cjs error=${err ? err.code || err.message : "none"} ` +
+        `status=${result.status} signal=${result.signal || "none"}`
+    );
     process.exit(FAIL_OPEN_EXIT);
   }
   process.exit(result.status);
@@ -104,6 +174,14 @@ function main() {
 
 try {
   main();
-} catch {
+} catch (err) {
+  // The shim's own last resort. Structurally identical to the
+  // `unhandled-fail-open` handler at the bottom of core/hooks/
+  // pre_tool_use.py, and previously just as silent: exit 0, empty stdout,
+  // nothing anywhere to say the gate chain never ran.
+  recordDegraded(
+    "unhandled-fail-open",
+    `via=cjs ${err && err.stack ? err.stack : String(err)}`
+  );
   process.exit(FAIL_OPEN_EXIT);
 }

package/config/hooks/pre-tool-use.sh

@@ -26,6 +26,14 @@
 _ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
 if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
 
+# A split deploy (wrapper present, _lib absent) must still run the hook —
+# telemetry is an observer, never a dependency. These no-op stubs are
+# defined only when the real ones did not arrive.
+command -v arka_hook_degraded >/dev/null 2>&1 || arka_hook_degraded() { :; }
+command -v arka_run_hook >/dev/null 2>&1 || arka_run_hook() {
+  shift; "$ARKA_PY" -m "$1"
+}
+
 # ─── Resolve ARKAOS_ROOT (validated — see arka_resolve_root in _lib) ────
 # .repo-path can point at a purged npx cache; the shared resolver falls
 # through to the ~/.arkaos/lib snapshot instead of exporting a dead root.
@@ -44,7 +52,10 @@ fi
 export ARKAOS_ROOT
 
 # ─── Degrade gracefully (fail open, same as before) ─────────────────────
+# Still fail-open, but no longer silent: with no interpreter every gate in
+# this hook allows, and that must be distinguishable from a gate that ran.
 if ! command -v "$ARKA_PY" >/dev/null 2>&1; then
+  arka_hook_degraded "pre-tool-use" "no-interpreter" "ARKA_PY=$ARKA_PY"
   exit 0
 fi
 # Self-root fallback: the wrapper ships next to its python entrypoint, so
@@ -56,6 +67,7 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/pre_tool_use.py" ]; then
     ARKAOS_ROOT="$_SELF_ROOT"
     export ARKAOS_ROOT
   else
+    arka_hook_degraded "pre-tool-use" "entrypoint-missing" "root=$ARKAOS_ROOT"
     exit 0
   fi
 fi
@@ -63,5 +75,10 @@ fi
 # ─── Single python process; stdin/stdout/stderr/exit-code pass through ──
 # Interpreter resolution handled by the shared resolver (ARKA_PY): prefers
 # the ArkaOS venv (has pyyaml/pydantic), falls back to a yaml-capable python3.
-PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec "$ARKA_PY" -m core.hooks.pre_tool_use
+#
+# NOT `exec`, unlike every other .sh wrapper here — deliberate, and the
+# trade-off is written out in full at arka_run_hook in _lib/arka_python.sh.
+# Short version: exec replaces this shell with Python, leaving nobody to
+# read the exit status, and the status IS the entrypoint-failed signal.
+export PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}"
+arka_run_hook "pre-tool-use" core.hooks.pre_tool_use