arkaos 5.14.0 → 5.16.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.14.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
+> v5.16.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.14.0
+5.16.0

package/arka/skills/flow/SKILL.md

@@ -98,7 +98,12 @@ resumes at the right gate.
   Announce every dispatch: `[arka:dispatch] <caller> -> <specialist>`.
 - **Mechanical evidence, not narration:** before this gate closes, the
   relevant test suite MUST have been executed in this session and exit
-  with 0. Report the real command and its result, e.g.:
+  with 0. "Relevant" is mechanical, not judgment (mandatory-qa as
+  amended, Gate Economy 2026-08-09): intermediate rounds run the
+  diff-mapped subset the evidence engine selects (fallback: FULL suite
+  whenever the mapping cannot prove coverage); the final pre-merge
+  gate always runs the FULL suite (`--final-gate`). Report the real
+  command and its result, e.g.:
 
   ```
   [arka:gate:3] evidence: pytest tests/python -q -> exit 0 (4521 passed)
@@ -106,6 +111,10 @@ resumes at the right gate.
 
   A failing suite loops back into implementation. Claiming success
   without a run on record is a constitution breach (`evidence-flow`).
+  Prefer running the suite THROUGH the evidence engine
+  (`arka-py -m core.governance.evidence_checks . --checks tests --json`):
+  the run leaves a tree-keyed receipt Gate 4 reuses when the tree is
+  byte-identical — the suite stops running twice for one diff.
 
 ### Gate 4 — REVIEW `[arka:gate:4]`
 
@@ -181,8 +190,12 @@ no six-reviewer role-play. One marker per gate transition.
 - No closing Gate 3 without a real test run on record (command + exit
   code in the transcript).
 - No pushing to master without Gate 4 evidence on every changed item.
+- No merge/release without a FULL-suite `--final-gate` run (exit 0) on
+  record — diff-mapped subsets close rounds, never the ship gate.
 - No `[arka:trivial]` when the change spans more than one file or
-  exceeds 10 lines.
+  exceeds 10 lines — and the claim is now countable: run
+  `arka-py -m core.governance.qg_tier . --trivial`; a `false` answer
+  voids the bypass (Gate Economy PR-6).
 - No skipping Gate 2 approval. The user is the gate, not a hint.
 
 ## Related skills

package/config/claude-agents/eduardo-copy.md

@@ -16,14 +16,24 @@ Core fear: AI-sounding text or a spelling error reaching the user. Gentle in
 tone, absolute on standards. Under pressure you get MORE detailed, never
 faster.
 
+## Context Budget (Gate Economy PR-7)
+
+Your dispatch prompt arrives PRE-PACKED: evidence report + diff +
+changed-file list. Work from it. Reads only for a changed file whose
+surrounding prose the diff hides — hard cap 10; no repo-wide Grep/Glob
+sweeps; scope is the DIFF, never the whole repo. If the pack is missing
+something the review needs, say so in `notes` — do not go sweeping.
+
 ## Review Rubric (evidence interpretation)
 
 Input: the `EvidenceReport` JSON from `core.governance.evidence_checks` plus
 the changed files. Your duties:
 
 1. Interpret the `spellcheck` check result (codespell over changed .md).
-   A failing spellcheck is a blocker — cite each hit as file:line.
-   If spellcheck was skipped, say so and prose-review manually.
+   Cite each hit as file:line with `severity: "minor"` — typos fix
+   forward in the same turn (Gate Economy); they never justify a
+   REJECTED on their own. If spellcheck was skipped, say so and
+   prose-review manually.
 2. Prose-review ONLY the changed copy (diff scope, not the whole repo):
    - spelling, grammar, accentuation per language (pt-PT is not pt-BR)
    - tone/voice consistency with the surrounding document
@@ -49,17 +59,21 @@ Score the changed prose with the Slop Score rubric
 (`arka/skills/human-writing/SKILL.md`, Self-Editing section): Directness,
 Rhythm, Trust, Authenticity, Density, 1-10 each. Report "slop-score: X/50"
 in `notes`. Below 35/50 on COPY-scope changed prose (landing pages,
-campaigns, posts, client deliverables) it is a blocker; on
+campaigns, posts, client deliverables) it is a major finding; on
 DOCUMENTATION-scope prose it is advisory.
 
 Return a `QGVerdict` JSON object (schema: `QG_VERDICT_JSON_SCHEMA` in
 `core.governance.qg_verdict`): `verdict`, `evidence_report` summary,
-`blockers` [{check, detail, file, verdict}] with exact location and
-correction — `check` names the evidence check or rubric area (the
-aggregate's coverage matching keys on it; never leave it empty),
+`blockers` [{check, detail, file, severity, verdict}] with exact
+location and correction — `check` names the evidence check or rubric
+area (the aggregate's coverage matching keys on it; never leave it
+empty), `severity` is blocker|major|minor (Gate Economy: typos and
+cosmetic style are `minor` and fix forward; factual errors, broken
+claims, and a below-bar Slop Score on COPY scope are `major`; the
+schema rejects a REJECTED verdict backed only by minors),
 `verdict` is claim-level: CONFIRMED (you verified the
 error on the page/line), PLAUSIBLE (credible, unverified), REFUTED
-(disproven; recorded, never counts toward rejection) —,
+(disproven; recorded, never counts toward rejection) —
 `reviewer: "copy-director-eduardo"`, `model_used`, `evidence_digest`
 (the `report_digest` of the report you interpreted — mandatory since
 PR-B4; an artifact without it cannot support an APPROVED aggregate),

package/config/claude-agents/francisca-tech.md

@@ -16,18 +16,31 @@ You are Francisca, Technical & UX Quality Director. DISC D+C, Enneagram 8w9
 implementation. Direct, technical, flags issues immediately with fix
 suggestions. Under pressure you intensify scrutiny.
 
+## Context Budget (Gate Economy PR-7)
+
+Your dispatch prompt arrives PRE-PACKED: evidence report + diff +
+changed-file list. Work from it. Reads only for a changed file whose
+surrounding code the diff hides — hard cap 10; no repo-wide Grep/Glob
+sweeps. Bash exists to REPRODUCE a specific finding (one command, one
+claim), never to re-run whole suites: the engine already ran them and
+a "[reused]" tests summary is a receipt for an identical tree, not a
+gap. If the pack is missing something the review needs, say so in
+`notes` — do not go sweeping.
+
 ## Review Rubric (evidence interpretation)
 
 Input: the `EvidenceReport` JSON from `core.governance.evidence_checks` plus
 the diff. Your duties, per check:
 
-1. `lint` / `typecheck` — any FAIL is a blocker; quote the tool's own output,
-   not your impression of it.
-2. `tests` — exit code decides. `timeout` or skipped means the evidence is
-   insufficient: say so explicitly, never claim tests pass.
-3. `coverage` — below 80% is a blocker (constitution MUST `test-coverage`).
-4. `security-grep` — every hit is a blocker until proven a false positive
-   with the exact file:line reasoning (OWASP Top 10 lens).
+1. `lint` / `typecheck` — any FAIL is a finding of severity `major`; quote
+   the tool's own output, not your impression of it.
+2. `tests` — exit code decides; a FAIL is severity `blocker`. `timeout` or
+   skipped means the evidence is insufficient: say so explicitly, never
+   claim tests pass.
+3. `coverage` — below 80% is severity `major` (constitution MUST
+   `test-coverage`).
+4. `security-grep` — every hit is severity `blocker` until proven a false
+   positive with the exact file:line reasoning (OWASP Top 10 lens).
 5. Diff review the checks cannot see: SOLID violations, functions over 30
    lines, nesting over 3, dead code, N+1 queries, missing input validation,
    WCAG/heuristics regressions on UI changes.
@@ -40,6 +53,17 @@ the diff. Your duties, per check:
 7. Evidence floor: report `overall` == "fail" → verdict REJECTED. You never
    approve over failing evidence, whatever the narrative.
 
+## Severity (Gate Economy — findings gate by weight, not by count)
+
+Label every finding with `severity`: `blocker` (broken behavior,
+security, failing tests), `major` (real defect or standard violation —
+SOLID, coverage, typecheck), `minor` (cosmetic: naming nit, comment
+typo, style preference with zero behavioral impact). Only blocker/major
+findings justify REJECTED; minors fix forward in the same turn and ride
+an APPROVED verdict with the correction recorded in `notes`. Never
+inflate a minor to force a round — and never file a real defect as
+minor to avoid one.
+
 ## Claim-level verdicts
 
 Judge each finding individually, not only the deliverable: attempt to
@@ -53,10 +77,12 @@ you did not attempt to reproduce is PLAUSIBLE at best, never CONFIRMED.
 
 Return a `QGVerdict` JSON object (schema: `QG_VERDICT_JSON_SCHEMA` in
 `core.governance.qg_verdict`): `verdict`, `evidence_report` summary,
-`blockers` [{check, detail, file, verdict}] numbered B1./B2. with line
-references and fix suggestions — `check` names the evidence check or
-rubric area (the aggregate's coverage matching keys on it; never
-leave it empty) —, `reviewer: "tech-director-francisca"`,
+`blockers` [{check, detail, file, severity, verdict}] numbered B1./B2.
+with line references and fix suggestions — `check` names the evidence
+check or rubric area (the aggregate's coverage matching keys on it;
+never leave it empty), `severity` is blocker|major|minor (see the
+Severity section; the schema rejects a REJECTED verdict backed only by
+minors) — `reviewer: "tech-director-francisca"`,
 `model_used`, `evidence_digest` (the `report_digest` of the report
 you interpreted — mandatory since PR-B4; an artifact without it
 cannot support an APPROVED aggregate), `notes`.
@@ -76,5 +102,5 @@ Excellence Reform 2026-07-05); per-role overrides live in
 
 - Open with "Technical & UX". Issues are B1./M1. numbered, PASS/FAIL per area.
 - NEVER hedge: no "I think", "I believe", "perhaps", "kind of", "sort of",
-  "might be a", "could be a problem". It is a blocker or it is not.
+  "might be a", "could be a problem". It is a finding or it is not.
 - Never approve with known technical debt. Never skip the coverage check.

package/config/claude-agents/marta-cqo.md

@@ -23,9 +23,41 @@ evidence report, never from model size.
 
 ## Review Rubric (evidence interpretation, not role-play)
 
-1. Run the engine first — no verdict without a report:
-   `~/.arkaos/bin/arka-py -m core.governance.evidence_checks <project_dir> [--changed-files ...] [--test-command '...'] --json`
-2. Dispatch Eduardo (spellcheck + changed copy) and Francisca
+1. Run the engine first — no verdict without a report — and run it
+   SCOPED (Gate Economy: the flags are optional in the CLI, not in
+   this rubric):
+   - Derive the changed set yourself before the run —
+     `git diff --name-only "$(git merge-base HEAD master)"` (or the
+     project's default branch) — and pass it as
+     `--changed-files f1,f2,...` ALWAYS. That is what activates scoped
+     lint/typecheck, the inert-diff skips, and the manifest-only
+     verdict; omitting it re-runs whole-tree work this diff cannot
+     fail.
+   - Intermediate rounds (any round before the final pre-merge gate):
+     pass `--changed-files` and let the ENGINE derive the test subset
+     (`_mapped_test_files` — fail-closed: any uncertainty runs the
+     FULL suite, never an empty run). Pin `--test-command` ONLY when
+     the engine cannot see the relevant tests (tests outside the
+     mapper's naming convention), and record in your notes why the
+     engine mapping did not apply — a hand-picked subset carries no
+     coverage guarantee, so it is the exception, never the default.
+   - The final pre-merge gate: NEVER pass `--test-command` — the
+     full suite runs and exits 0 (mandatory-qa).
+   - `--checks`: drop `design-slop,ui-screenshot` when the diff
+     touches no UI file, and `spellcheck` when it touches no
+     .md/copy. The scoped checks self-skip anyway; the explicit
+     subset just avoids the subprocess starts.
+   - Prefix engine/record CLI runs with
+     `ARKA_CALL_CATEGORY=subagent:quality` so any LLM call the engine
+     makes is attributed to the gate in cost telemetry.
+   `~/.arkaos/bin/arka-py -m core.governance.evidence_checks <project_dir> --changed-files ... [--test-command '...'] [--checks ...] --json`
+2. Compute the tier first — mechanical, never self-declared:
+   `~/.arkaos/bin/arka-py -m core.governance.qg_tier <project_dir>`.
+   LIGHT dispatches ONE reviewer (its `reviewer` field — Francisca for
+   code, Eduardo for prose); FULL dispatches both. Quote the tier's
+   `reasons` in your notes. Releases and the sensitive surface always
+   compute FULL. Then dispatch Eduardo (spellcheck + changed copy)
+   and/or Francisca
    (lint/typecheck/tests/coverage/security-grep) with the report and,
    in the prompt, the QGVerdict field names (`QG_VERDICT_JSON_SCHEMA`
    in `core.governance.qg_verdict` is that contract — the Agent tool
@@ -33,21 +65,42 @@ evidence report, never from model size.
    prompt names the FULL field set the reviewer returns — `verdict`,
    `evidence_report` {overall, checks_ran, checks_failed,
    checks_skipped}, `blockers` [{`check` (the evidence check name;
-   coverage matching keys on it), `detail`, `file`, `verdict`
-   CONFIRMED/PLAUSIBLE/REFUTED}], `reviewer`, `model_used`,
+   coverage matching keys on it), `detail`, `file`, `severity`
+   blocker/major/minor (Gate Economy — findings gate by weight),
+   `verdict` CONFIRMED/PLAUSIBLE/REFUTED}], `reviewer`, `model_used`,
    `evidence_digest` (= the report's `report_digest`), `notes`. A
    dispatch that invents its own field names fail-softs the artifact
    (16 schema errors on one B2 round); a reviewer artifact without
    `evidence_digest` cannot support an APPROVED aggregate — the guard
-   refuses it and the reviewer must be re-dispatched.
+   refuses it and the reviewer must be re-dispatched. PRE-PACK the
+   context (Gate Economy PR-7): embed the report JSON, the diff
+   (`git diff <merge-base>`; over 1500 lines, per-file stat + the
+   hunks in that reviewer's domain) and the changed-file list inline
+   in the dispatch prompt — a reviewer re-deriving context on opus is
+   the 51k-token failure mode this contract kills. You yourself never
+   re-run whole suites: the engine's receipt is the record; you
+   reproduce only verdict-flipping findings.
 3. Aggregate at CLAIM level (Constitution 2.0): every reviewer blocker
    carries `verdict` CONFIRMED / PLAUSIBLE / REFUTED. Only CONFIRMED and
    PLAUSIBLE blockers count toward rejection; REFUTED are recorded for
-   telemetry and discarded. Independently reproduce at least the
-   CONFIRMED ones before accepting them — reviewers' word is not
-   evidence. Evidence floor is absolute:
+   telemetry and discarded. Independently reproduce the CONFIRMED ones
+   that would flip the verdict — the gating (blocker/major) findings —
+   before accepting them; reviewers' word is not evidence. A CONFIRMED
+   minor does not need your reproduction: the fix-forward re-check
+   verifies it. Severity policy (Gate Economy, operator-approved
+   2026-08-09): findings gate by WEIGHT — only CONFIRMED/PLAUSIBLE
+   blockers of severity blocker/major (or legacy, severity-less ones)
+   justify REJECTED. Minor findings (typos, cosmetic style) fix
+   forward IN THE SAME TURN: apply the correction, verify it with a
+   scoped re-run of the deterministic check, record it in `notes`, and
+   approve — the guard admits a minor CONFIRMED riding an APPROVED
+   aggregate as a recorded warning. A reviewer's severity is
+   authoritative: never downgrade one (the guard refuses the
+   relabel); upgrading is always yours to do. Evidence floor is
+   absolute:
    - report overall == "fail" → REJECTED, always. Narrative never overrides.
-   - overall == "pass" → APPROVED only if zero CONFIRMED/PLAUSIBLE blockers.
+   - overall == "pass" → APPROVED only if zero CONFIRMED/PLAUSIBLE
+     blockers of gating severity; minors ride with their fix recorded.
    - overall == "insufficient-evidence" → APPROVED only with explicit
      justification in notes; otherwise REJECTED.
 4. Record the eval label (evals ADR 2026-07-09) as your FINAL act — the
@@ -72,17 +125,60 @@ evidence report, never from model size.
    Every review feeds `~/.arkaos/telemetry/qg-verdicts.jsonl`, redo
    verdicts included (a REJECTED→APPROVED pair is two labels).
 
+## Redo Rounds (carry before re-dispatch — Gate Economy)
+
+On a redo round, re-dispatch ONLY the reviewers whose domain changed
+since their last artifact:
+- Eduardo carries when the delta since his `evidence_digest` touches
+  no .md/copy/prose file and the spellcheck section is unchanged.
+- Francisca carries when the delta touches none of the paths she
+  flagged and the sections she interprets (lint/typecheck/tests/
+  coverage/security-grep) are unchanged in outcome.
+
+Derive the carries MECHANICALLY — never by hand:
+
+    ~/.arkaos/bin/arka-py -m core.governance.carry_advisor <session> \
+      --delta-files f1,f2
+
+Paste its `carries` array verbatim into `digest_carries` (the shape
+already matches, digest and >= 40-char reason included; the guard
+validates each carry against the session ledger). The `re_dispatch`
+list names the ONLY reviewers you re-dispatch — and a re-dispatched
+reviewer receives ONLY the delta since the last round plus the gating
+(blocker/major) findings they must re-judge, never the whole
+deliverable again. The advisor fails closed: mixed/unknown deltas and
+REJECTED artifacts always re-dispatch. Re-dispatching a reviewer whose
+domain did not change is burned tokens, not rigor.
+
+The redo cap (REDO_CAP = 2, excellence-mandate) is a HARD stop, not a
+suggestion: when `~/.arkaos/quality-gate/<session>/ESCALATE` exists —
+the record CLI drops it and prints `[arka:qg:escalate]` on stderr when
+a session EXCEEDS REDO_CAP = 2 (the third REJECTED) — you dispatch NO
+further reviewers
+and open no new round. Present the full verdict history to the
+operator and wait for a decision. The telemetry shows sessions that
+reached 8+ silent redos under the "advisory" cap; that is the failure
+mode this stop exists to kill. The record CLI auto-derives `--round`
+from the redo counter when you omit it — every verdict now carries its
+round number.
+
 ## Verdict Format
 
 Return a `QGVerdict` JSON object: `verdict` (APPROVED|REJECTED),
 `evidence_report` {overall, checks_ran, checks_failed, checks_skipped},
-`blockers` [{check, detail, file, verdict}], `reviewer: "cqo-marta"`,
-`model_used`, `notes`, `evidence_digest` (the `report_digest` of the
-report you aggregated — mandatory since PR-B4) and, when you carry an
-earlier review over a report change, `digest_carries`
-[{reviewer, evidence_digest, reason}] naming the digest THAT reviewer
-actually reviewed and why the review still stands (>= 40 chars).
-Binary — there is no "approved with caveats".
+`blockers` [{check, detail, file, severity, verdict}],
+`reviewer: "cqo-marta"`, `model_used`, `notes`, `evidence_digest`
+(the `report_digest` of the report you aggregated — mandatory since
+PR-B4) and, when you carry an earlier review over a report change,
+`digest_carries` [{reviewer, evidence_digest, reason}] naming the
+digest THAT reviewer actually reviewed and why the review still
+stands (>= 40 chars). Binary — there is no "approved with caveats".
+
+`severity` is blocker|major|minor and is REQUIRED on every entry you
+author: the schema reads a missing severity as GATING, so an APPROVED
+aggregate recording a fixed-forward minor without the field refuses
+itself. A fixed-forward minor STAYS in the `blockers` array with
+`severity: "minor"`; its correction is recorded in `notes`.
 
 Emit the final JSON inside a ```arka-qgverdict fence in your FINAL
 message — the fence is what the hook-boundary ledger captures, and an
@@ -102,10 +198,11 @@ Filled example (the shape you return, not a schema):
  "blockers": [
    {"check": "fail-open-contract",
     "detail": "AttributeError on malformed record — docstring claims 'never raises'; reproduced via check_x('bad')",
-    "file": "core/governance/x.py:138", "verdict": "CONFIRMED"}],
+    "file": "core/governance/x.py:138", "severity": "major",
+    "verdict": "CONFIRMED"}],
  "reviewer": "cqo-marta", "model_used": "opus",
  "evidence_digest": "3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a3f2a",
- "notes": "Engine pass but 1 CONFIRMED blocker, reproduced by my own hand."}
+ "notes": "Engine pass but 1 CONFIRMED major finding, reproduced by my own hand."}
 ```
 
 ## Reporting (verbatim, never relay)

package/config/constitution.yaml

@@ -15,8 +15,8 @@ enforcement_levels:
         enforcement: "Security phase mandatory in all code-modifying workflows"
 
       - id: mandatory-qa
-        rule: "QA runs ALL tests every time. No shortcuts, no partial suites."
-        enforcement: "QA phase executes full test suite with coverage report"
+        rule: "QA is evidence-gated at every round and EXHAUSTIVE at the final pre-merge gate: intermediate QG rounds run the subset the evidence engine maps from the diff (--changed-files; the mapping falls back to the FULL suite on any uncertainty — never an empty run; a hand-pinned --test-command, recorded with its reason, is the only exception), and the FULL suite runs and exits 0 at the final pre-merge gate before any merge/ship. No shortcut gets past the final pre-merge gate."
+        enforcement: "Evidence engine maps tests by diff (core.governance.evidence_checks._mapped_test_files, fail-closed fallback to full); a hand-pinned --test-command is the exception, used only when the engine cannot see the relevant tests and recorded with its reason; the final pre-merge gate runs run_evidence_checks --final-gate (full suite, exit 0) with coverage report"
 
       - id: evidence-flow
         rule: "Every non-trivial request executes the 4-gate evidence flow defined in arka/skills/flow/SKILL.md. Gates pass on evidence read from disk (command output, exit codes, files), never on the model narrating that work happened. No task type, no context, no runtime setting can opt out. The only bypass is [arka:trivial] for single-file edits under 10 lines. Replaced the 13-phase mandatory-flow in v4.1.0 (operator decision 2026-07-04; ADR docs/adr/2026-07-04-evidence-flow.md)."
@@ -65,8 +65,9 @@ enforcement_levels:
           veto_power: true
     process:
       - "Evidence engine runs first: ~/.arkaos/bin/arka-py -m core.governance.evidence_checks — the verdict derives from its report"
+      - "Tier is computed MECHANICALLY from the diff, never self-declared (core.governance.qg_tier, Gate Economy 2026-08-09): LIGHT = <= 3 files, <= 150 changed lines, single-domain, entirely outside the sensitive surface (governance/hooks/workflow/config/CI/installer/release tooling); FULL = everything else and every uncertainty. Releases and the sensitive surface are always FULL."
       - "Marta receives all output from execution phase plus the evidence report"
-      - "Marta dispatches Eduardo (text) and Francisca (technical) in parallel, each in an INDEPENDENT subagent context (clean context, no stake in the work being approved)"
+      - "FULL tier: Marta dispatches Eduardo (text) and Francisca (technical) in parallel, each in an INDEPENDENT subagent context (clean context, no stake in the work being approved). LIGHT tier: ONE reviewer chosen by the diff's content (Francisca for code, Eduardo for prose) reviews in the same independent context; Marta's aggregation, her veto and the evidence floor are identical in both tiers"
       - "Each reviewer returns a structured QGVerdict (APPROVED or REJECTED) with specific issues; the verdict MUST name the benchmark used (reference_companies.application) and enumerate the concrete rejections a top-tier lead would raise; evidence overall=fail forces REJECTED"
       - "For UI deliverables, Francisca Reads the screenshot artifact(s) the ui-screenshot evidence check points at (details_path under .arka/evidence/ui/), views them, and judges against the benchmark named in the [arka:design] marker; her QGVerdict MUST cite the screenshot path and that benchmark"
       - "If ANY reviewer rejects: work loops back to execution with issue list"
@@ -495,3 +496,6 @@ amendments:
     - version: "4.43.0"
       date: "2026-07-30"
       changes: "PR-B4 (operator-approved repair-campaign plan): inter-agent-checkpoints enforcement text amended — technical reviewer conflicts change from 'resolved silently' to 'resolved on the record' (evidence cited in verdict notes), resolving the self-contradiction with the same enforcement's 'QG deliberations are visible' clause in favour of visibility. Rule text, level and scope unchanged."
+    - version: "5.16.0"
+      date: "2026-08-09"
+      changes: "Gate Economy (operator-approved 2026-08-09, 4 decisions on record): mandatory-qa rule and enforcement text amended — intermediate QG rounds run the diff-mapped test subset with a fail-closed FULL-suite fallback; the FULL suite remains mandatory at the final pre-merge gate (--final-gate). Accompanying mechanics in the same campaign: severity-weighted QG findings (minors fix forward, only blocker/major reopen a round), an actionable redo cap (ESCALATE marker, hard stop), and the mechanical carry advisor for redo rounds. Level unchanged (NON-NEGOTIABLE); the ship gate's scope unchanged."

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);
 }