universal-dev-standards 6.7.5 → 6.9.0

package/bundled/core/tech-debt-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/tech-debt-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-03-31
+**Version**: 1.1.0
+**Last Updated**: 2026-08-20
 **Applicability**: All software projects
 **Scope**: universal
 **Industry Standards**: Martin Fowler's Technical Debt Quadrant, Ward Cunningham's Debt Metaphor
@@ -65,13 +65,70 @@ Every technical debt item must be recorded in a registry with the following 11 f
 
 ### Registry Storage Options
 
-The registry can be stored in one of the following locations:
+The registry can be stored in any of the following locations. Each option is legal **only if** it also satisfies the condition in the right-hand column — see [Overdue Handling](#overdue-handling) below.
 
-| Option | Best For | Format |
-|--------|----------|--------|
-| `docs/tech-debt-registry.md` | Small teams, simple tracking | Markdown table |
-| Issue tracker (GitHub Issues, Jira) | Larger teams, workflow integration | Tagged issues with `tech-debt` label |
-| Dedicated spreadsheet | Non-technical stakeholders | CSV/Excel with the 11 fields |
+| Option | Best For | Format | Overdue-check condition |
+|--------|----------|--------|-------------------------|
+| `docs/tech-debt-registry.md` | Small teams, simple tracking | Markdown table | A repository check parses the table and fails on rows past their Target Resolution Date — **or** the file carries an Unattended Declaration |
+| Issue tracker (GitHub Issues, Jira) | Larger teams, workflow integration | Tagged issues with `tech-debt` label | A scheduled query on the due-date field that actually **runs** and raises; a saved filter nobody opens is not a check — **or** an Unattended Declaration |
+| Dedicated spreadsheet | Non-technical stakeholders | CSV/Excel with the 11 fields | Only if the sheet is exported, on a stated cadence, to a location a check reads — **or** an Unattended Declaration |
+
+> **Why that column had to be added.** A registry no program can read satisfies every other requirement in this section: all 11 fields present, an Owner named, a Target Resolution Date set. Nothing about it is wrong — until the date passes, and then nothing happens. The spreadsheet option is deliberately **not** removed; a spreadsheet is often the only format the people who fund the work will open. What is no longer legal is for any storage option to be a place where dates go to expire unobserved.
+
+### Overdue Handling
+
+A **Target Resolution Date** that passes with no consequence is indistinguishable from having no date at all. This subsection defines what "the date arrived" means.
+
+#### The three legal dispositions
+
+When an item reaches its Target Resolution Date, exactly one of three things must happen, and it must leave a trace:
+
+| Disposition | Meaning | Required trace |
+|-------------|---------|----------------|
+| **Resolve** | Do the work | Registry entry closed + a `Tech-Debt: TD-NNN resolved` commit footer (see [Commit Marking](#6-commit-marking)) |
+| **Withdraw** | Decide not to do it, and delete the record | Entry marked withdrawn, with a reason and a date. It stops being counted as debt because it no longer is any |
+| **Extend** | Set a new Target Resolution Date | The new date **and** a written reason, recorded together; earlier dates stay visible (append, do not overwrite) |
+
+There is no fourth disposition. "Still open, date passed, nobody looked" is not a state this standard permits — it is the failure this subsection exists to name.
+
+**Rule TD-EXP-001 (Required)** — An item past its Target Resolution Date with none of the three dispositions applied makes the registry non-compliant. Overdue is a finding, not a neutral background condition.
+
+**Rule TD-EXP-002 (Required, prohibition)** — Expiry MUST NOT be implemented as **automatic extension** or **automatic closure**.
+
+- Automatic extension makes the date unfalsifiable: it can never be missed, so it never measures anything.
+- Automatic closure deletes the record without anyone having decided to.
+
+Both stop the clock, and neither leaves a trace that it did. A date whose only consumer is a job that pushes it forward is decoration.
+
+**Rule TD-EXP-003 (Required)** — Extending requires the reason to be recorded next to the new date. Changing only the date is not an extension; it is an erasure with a timestamp on it.
+
+**Rule TD-EXP-004 (Recommended)** — An item extended three or more times with no progress recorded between extensions should be re-triaged as a **Withdraw** candidate. Repeated extension is evidence that nobody intends to do the work; recording that honestly is more useful to the next reader than a fourth date.
+
+#### Unattended Declaration
+
+Not every team can run a check. **A registry with no automated overdue check is still compliant — but only if it says so.**
+
+An **Unattended Declaration** is a visible, dated statement inside the registry itself:
+
+```
+Unattended — no automated check reads this registry for overdue items.
+Reviewed manually by <owner> on a <cadence> cadence. Last reviewed: <date>.
+```
+
+**Rule TD-EXP-005 (Required)** — A registry MUST be in exactly one of two states, and MUST make which one visible to anyone reading the registry:
+
+1. **Checked** — a named, runnable check reads the registry and fails when an item is past its Target Resolution Date.
+2. **Unattended** — no such check exists, an Unattended Declaration is present, and it names an owner, a review cadence, and the date of the last review.
+
+A registry in neither state is non-compliant. The declaration is not paperwork: it is the whole difference between a reader who knows nothing is watching and a reader who assumes something is.
+
+**Rule TD-EXP-006 (Required)** — The "Last reviewed" date in an Unattended Declaration is itself subject to the cadence that declaration states. A declaration whose last review is older than its own cadence is an overdue item in its own right, and the three dispositions apply to it.
+
+> **This standard ships no checker, and that is a known cost — stated here rather than left to be discovered.**
+>
+> UDS defines the requirement; it does not provide a program that enforces it. Adopters who want the **Checked** state must write the check themselves, and most teams will not — which is exactly the failure mode described above, now applying to this section as well.
+>
+> That is why the minimum bar here is **not** "build a checker". It is **"never let a registry be silently unattended."** Declaring `Unattended` costs one paragraph and is fully compliant. Being unattended *without* declaring it is the one outcome this standard actually forbids, because it is the only one that misleads the reader about whether anything is watching.
 
 ---
 
@@ -200,6 +257,7 @@ Tech-Debt: TD-042 resolved
 - [Refactoring Standards](refactoring-standards.md) — Techniques for resolving code debt
 - [Testing Standards](testing-standards.md) — Addressing test debt
 - [Commit Message Guide](commit-message-guide.md) — Commit format including debt markers
+- [Governance Layer](governance-layer.md) — Standard #0; applies the same clock to pending decisions and accepted risks, and defines aggregate-reporting and freshness-metric rules
 
 ---
 
@@ -207,6 +265,7 @@ Tech-Debt: TD-042 resolved
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-08-20 | Added: Overdue Handling — three legal dispositions on expiry (resolve / withdraw / extend-with-reason), TD-EXP-001..006, prohibition on automatic extension and automatic closure, Unattended Declaration as the compliant alternative to a checker; Registry Storage Options gains an overdue-check condition per option (a registry no program can read is legal only when declared unattended) |
 | 1.0.0 | 2026-03-31 | Initial release: 6 debt types, registry template, budget allocation, prioritization matrix, quantitative metrics, commit marking |
 
 ---

package/bundled/core/turn-completion-integrity.md

@@ -0,0 +1,196 @@
+# Turn Completion Integrity
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/turn-completion-integrity.md)
+
+**Version**: 1.3.0
+**Last Updated**: 2026-09-08
+**Applicability**: Any harness where an agent ends a turn and hands control back to a human
+**Scope**: universal
+**Industry Standards**: none claimed — derived from observed failures, see Evidence
+
+---
+
+## Purpose
+
+An agent writes *"I'll do X next"* and then ends the turn without doing X.
+
+The human reads a sentence describing work that was never done. Nothing errors, no
+check fails, and the transcript reads like progress. The next turn starts from a
+state the human believes is further along than it is.
+
+This is not a knowledge failure — the agent named the correct next step. It is a
+**closure** failure: the turn ended at the point where the work should have started.
+
+---
+
+## The Rule
+
+**R1.** If the agent's final message states a first-person commitment to a next
+action, the turn MUST NOT end until that action is taken or the agent states what
+blocks it.
+
+**R2.** "What blocks it" means naming the person or input each remaining item waits
+on. *"The main parts are done"* is not a blocker statement; *"the deploy waits on
+your key, the doc waits on nothing and I am doing it now"* is.
+
+**R3.** A rule written only in the agent's instructions is not enforcement. R1 MUST
+be evaluated **at the moment the turn ends**, by something that is not the agent.
+
+---
+
+## Why R3 exists
+
+The instruction form of this rule was written into a project's agent instructions and
+violated inside the same session that read it. It was then written into a published
+standard, marked optional, with no checker reading it; the same violation recurred
+seven days later.
+
+An instruction is an input. The failure happens at a decision point — *"I am about to
+end this turn"* — and an input that is not consulted at that point is not in effect.
+This is the general shape: **a documented requirement with no enforcement at its
+decision point is a suggestion, and its compliance is unmeasured, not high.**
+
+---
+
+## What the check MUST NOT do
+
+**R4. Do not block on work that is always outstanding.** A repository always has open
+TODOs, a backlog always has items. A gate that is true on every turn is turned off,
+and then it protects nothing. The check fires **only** on a commitment the agent made
+in that message.
+
+**R5. Fail open, always.** Any error — unreadable transcript, missing field, malformed
+JSON, unexpected schema — MUST let the turn end. A hook that can trap a session is
+worse than no hook, because the human's only recovery is to disable it, and they will
+disable it permanently.
+
+**R6. Bound the blocking.** The check MUST enforce
+(a) a cooldown between blocks, and
+(b) a cap on blocks within a **rolling time window**.
+
+A cap counted per session with no reset is not a safety limit — it is an off switch on
+a delay, and it disarms silently in exactly the long session where the rule matters
+most.
+
+---
+
+## The human can end the turn, and the agent's words cannot say so
+
+**R9.** The check MUST exempt a turn the human asked to end, and MUST determine
+that from the human's own most recent message — not from the agent's.
+
+This rule exists because its absence was measured, once, on the first real
+firing after this standard shipped. The human wrote *"pause, I'm going home"*;
+the agent acknowledged and listed what it would resume; the check read an
+abandoned commitment and blocked.
+
+The detector was not wrong about the pattern. **A turn ending by instruction and
+a turn ending on an abandoned commitment produce the same words from the agent**,
+because in both cases the agent names work it is not doing now. Nothing in the
+final message separates them, so a check that reads only that message cannot.
+
+**R10.** The stop-request pattern MUST be narrow, and its corpus MUST include
+work instructions that merely contain a stopping word. A false exemption is not
+one missed block: it silences the check for the rest of the session. During
+implementation the pattern matched *"stop using the hardcoded list and walk the
+registry instead"* — an instruction to do work, read as an instruction to stop.
+
+**R11.** The check's own block message re-enters the transcript as a human turn.
+It MUST be able to recognise its own output and skip it when looking for the
+human's last message.
+
+Without this, R9 works exactly once. The block message becomes "the human's most
+recent message" on the next run, the real instruction to stop is hidden behind
+it, and the exemption disappears — silently, and only in the situation it was
+built for.
+
+This is the same family as a detector matching the prose that documents it,
+one step further along: **the check reads its own output.** Carry a fixed marker
+string in the block message and skip any human turn containing it.
+
+**R12.** The check MUST be able to recognise the ending R2 defines. A check that
+enforces R2 but cannot see an itemized blocker list blocks the one ending the
+standard asks for — it punishes correct behaviour, and that is a faster way to
+get uninstalled than missing a violation.
+
+Recognition needs three things, and dropping any one of them was measured to
+break it:
+
+| Requirement | Why |
+|---|---|
+| Two or more list items | One item with an attribution is a sentence, not an itemization |
+| A blocker attribution anywhere in the message, not per item | Real writing puts it in the preamble — *"the rest are all on you, itemized:"* — and requiring it per item missed the first real message it was tested against |
+| No vague-completion phrase | *"the rest are done"* is the summary R2 rejects; a list that disposes of the remainder that way is a summary wearing a list's clothes |
+
+🔴 **Exclude the check's own scaffolding from the attribution search.** The
+heading *"what you need to decide"* contains the word *"you"*, so a list of work
+already finished satisfied the attribution test by way of the heading above it.
+The detector read its own structure — the same failure as R11, one layer down.
+
+---
+
+## Language coverage is a correctness property, not a translation task
+
+The check reads prose written by the agent, so **its detector is language-specific**.
+A detector carrying only one language's patterns, shipped to an adopter working in
+another, produces a hook that is installed, runs on every turn, exits 0, and can never
+fire. Every observable signal is identical to "the agent is behaving well".
+
+**R7.** Each supported language MUST ship as a locale pack carrying **its own corpus**
+of cases that must block and cases that must pass, and the pack's self-test MUST run
+in CI. A locale pack whose corpus does not pass is not shipped.
+
+**R8.** An adopter whose language has no pack MUST be told the check is inactive for
+their language. Silence here reproduces the exact failure the standard exists to
+prevent, one level up.
+
+---
+
+## What the detector matches
+
+The shape is: **a first-person future marker, then an action verb, in the same
+sentence**, minus three exclusions.
+
+| Element | Purpose | Failure if omitted |
+|---|---|---|
+| First-person + future marker | Distinguishes a commitment from a description | Matches the user's words quoted back |
+| Action verb | Distinguishes doing from reporting | *"I'll explain why"* counts as work |
+| Same-sentence scope | Keeps the two halves related | A negated clause and a later real commitment merge into one non-match |
+| Exclude reporting verbs | *"I'll say / note / mention"* is not work | The check fires on its own summaries |
+| Exclude negation | *"I won't change that"* is a decision, not a commitment | A refusal reads as a promise |
+| Exclude quoted and tabular text | Examples of the pattern are not instances of it | The check fires on its own documentation |
+
+Each exclusion above was added because its absence produced a false block in testing.
+An implementation that drops one will reproduce that block.
+
+---
+
+## Evidence
+
+Observed over one project, 2026-08 to 2026-09:
+
+| Observation | Count |
+|---|---|
+| Same complaint raised by the human about stated-but-undone next steps | 5 |
+| Times the instruction form was present and violated in the same session | ≥1 |
+| Detector versions defeated by the pattern in their own source or examples | 5 |
+| Detector false positives caught by a corpus before shipping | 3 |
+
+The last row is the argument for R7. Three of the five detector defects were caught
+only because a corpus existed; the two that shipped were the ones no case covered.
+
+---
+
+## Checklist
+
+- [ ] The check runs at turn end, not as an instruction to the agent
+- [ ] Every failure path exits without blocking
+- [ ] A cooldown and a rolling-window cap are both present
+- [ ] Each shipped language has a corpus, and the corpus runs in CI
+- [ ] Adopters in unsupported languages are told the check is inactive
+- [ ] The check does not consult repository state (open TODOs, backlog)
+- [ ] A turn the human asked to end is exempt, decided from the human's message
+- [ ] The stop-request corpus includes work instructions containing a stopping word
+- [ ] The check recognises its own block message and does not read it as the human's
+- [ ] The check recognises the itemized blocker ending R2 defines, and does not block it
+- [ ] The attribution search excludes the check's own headings and scaffolding

package/bundled/hooks/check-dangerous-cmd.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook: Dangerous Command Detection
+ *
+ * Detects potentially destructive shell commands and blocks execution.
+ * Exit code: 0 = safe, 1 = dangerous
+ *
+ * Usage: echo "rm -rf /" | node check-dangerous-cmd.mjs
+ *    or: node check-dangerous-cmd.mjs "rm -rf /"
+ *
+ * Performance target: < 500ms
+ *
+ * @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md (REQ-2)
+ */
+
+const DANGEROUS_PATTERNS = [
+  /rm\s+-rf\s+\//,
+  /mkfs\./,
+  /dd\s+if=.*of=\/dev\//,
+  /format\s+[a-zA-Z]:/,
+  />\s*\/dev\/sda/,
+  /chmod\s+-R\s+777\s+\//,
+  /:()\{\s*:\|:&\s*\};:/,  // fork bomb
+];
+
+/**
+ * Check if a command matches dangerous patterns.
+ * @param {string} cmd - The shell command to check
+ * @returns {boolean} true if dangerous
+ */
+export function isDangerousCommand(cmd) {
+  if (!cmd || typeof cmd !== 'string') return false;
+  return DANGEROUS_PATTERNS.some((p) => p.test(cmd));
+}
+
+// CLI mode
+if (process.argv[1] && process.argv[1].endsWith('check-dangerous-cmd.mjs')) {
+  const input = process.argv[2];
+  if (input) {
+    if (isDangerousCommand(input)) {
+      console.error(`⚠️ Dangerous command detected: "${input}"`);
+      process.exit(1);
+    } else {
+      process.exit(0);
+    }
+  } else {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      const cmd = data.trim();
+      if (isDangerousCommand(cmd)) {
+        console.error(`⚠️ Dangerous command detected: "${cmd}"`);
+        process.exit(1);
+      } else {
+        process.exit(0);
+      }
+    });
+  }
+}

package/bundled/hooks/check-logging-standard.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook: Structured Logging Check
+ *
+ * Checks code for unstructured logging calls (console.log, console.warn, etc.)
+ * and suggests using structured logging instead.
+ * Exit code: 0 = pass, 1 = unstructured logging found
+ *
+ * Usage: echo 'console.log("debug")' | node check-logging-standard.mjs
+ *    or: node check-logging-standard.mjs 'console.log("debug")'
+ *
+ * Performance target: < 500ms
+ *
+ * @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md (REQ-3)
+ */
+
+const UNSTRUCTURED_PATTERNS = [
+  /console\.log\(/,
+  /console\.warn\(/,
+  /console\.error\(/,
+  /console\.info\(/,
+  /console\.debug\(/,
+];
+
+/**
+ * Check if code contains unstructured logging calls.
+ * @param {string} code - The code to check
+ * @returns {boolean} true if unstructured logging found
+ */
+export function hasUnstructuredLogging(code) {
+  if (!code || typeof code !== 'string') return false;
+  return UNSTRUCTURED_PATTERNS.some((p) => p.test(code));
+}
+
+// CLI mode
+if (process.argv[1] && process.argv[1].endsWith('check-logging-standard.mjs')) {
+  const input = process.argv[2];
+  if (input) {
+    if (hasUnstructuredLogging(input)) {
+      console.error('⚠️ Unstructured logging detected. Use structured logging (e.g., JSON logger) instead.');
+      process.exit(1);
+    } else {
+      process.exit(0);
+    }
+  } else {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      const code = data.trim();
+      if (hasUnstructuredLogging(code)) {
+        console.error('⚠️ Unstructured logging detected. Use structured logging (e.g., JSON logger) instead.');
+        process.exit(1);
+      } else {
+        process.exit(0);
+      }
+    });
+  }
+}

package/bundled/hooks/check-turn-completion.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook: Turn Completion Integrity
+ *
+ * Runs at turn end. Blocks when the agent's final message states a first-person
+ * commitment to a next action that the turn then ended without taking.
+ *
+ * Contract (Claude Code Stop hook):
+ *   stdin  — JSON with session_id, transcript_path, stop_hook_active
+ *   block  — print {"decision":"block","reason":"..."} on stdout, exit 0
+ *   allow  — print nothing, exit 0
+ *
+ * Every failure path allows. See core/turn-completion-integrity.md R5: a hook
+ * that can trap a session is worse than none, because the only recovery a human
+ * has is to disable it, and they will disable it permanently.
+ *
+ * Usage: node check-turn-completion.mjs  (reads stdin)
+ *        node check-turn-completion.mjs --self-test
+ *        node check-turn-completion.mjs --languages
+ *
+ * @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md
+ * @see core/turn-completion-integrity.md
+ */
+import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectCommitment, userAskedToStop } from './turn-completion/detect.mjs';
+
+export const VERSION = '1.1.0';
+
+const COOLDOWN_SEC = 120;
+// A cap counted per session with no reset is an off switch on a delay: it
+// disarms silently in exactly the long session where the rule matters most.
+// A rolling window bounds runaway loops just as well and recovers by itself.
+const MAX_BLOCKS_PER_WINDOW = 6;
+const WINDOW_SEC = 3600;
+
+const STATE_DIR = join(homedir(), '.uds', 'turn-completion');
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Locales this hook ships. The self-test fails if any of them will not load. */
+export const SHIPPED_LOCALES = ['en', 'zh-TW'];
+
+/**
+ * Load every shipped locale pack.
+ *
+ * At runtime a pack that fails to load is skipped (R5: a broken pack must not
+ * stop the turn from ending). 🔴 But that swallow is also how a shipping
+ * mistake hides: with zero packs loaded the hook runs, exits 0, and can never
+ * fire — the same shape as good behaviour. So `failed` is returned rather than
+ * discarded, and the self-test treats a non-empty `failed` as a failure.
+ * Caught while renaming the packs to .mjs: the loader still asked for .js.
+ */
+export async function loadPacks() {
+  const packs = [];
+  const failed = [];
+  for (const id of SHIPPED_LOCALES) {
+    try {
+      packs.push(await import(join(HERE, 'turn-completion', 'locales', `${id}.mjs`)));
+    } catch (e) {
+      failed.push({ id, why: String((e && e.message) || e) });
+    }
+  }
+  return { packs, failed };
+}
+
+/**
+ * 🔴 This hook's own block message enters the transcript as a user turn. On the
+ * next run it would therefore be read as "the human's last message", hiding the
+ * real one ("pause, I'm going home") and silently voiding the R9 exemption.
+ *
+ * Same family as the detector matching the prose that documents it — except
+ * here it reads its own output. The reason string carries this line so it can
+ * recognise itself.
+ */
+export const SELF_ECHO = 'UDS standard turn-completion-integrity (R1)';
+
+/** Plain text of a transcript message, or '' if it carries none. */
+function textOf(msg) {
+  const c = msg && msg.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return '';
+  // Tool results also arrive with role "user"; only text blocks are prose.
+  const parts = c.filter((p) => p && p.type === 'text').map((p) => p.text || '');
+  return parts.some((p) => p.trim()) ? parts.join('\n') : '';
+}
+
+/**
+ * Last assistant message and last human message in a Claude Code JSONL
+ * transcript. The human's message is needed because a turn that ends by their
+ * instruction looks, from the agent's words alone, exactly like one that ends
+ * on an abandoned commitment.
+ */
+export function lastMessages(transcriptPath) {
+  let assistant = '';
+  let user = '';
+  for (const line of readFileSync(transcriptPath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    let ev;
+    try { ev = JSON.parse(line); } catch { continue; }
+    const msg = ev && ev.message;
+    if (!msg) continue;
+    const t = textOf(msg);
+    if (!t) continue;
+    if (msg.role === 'assistant') assistant = t;
+    else if (msg.role === 'user' && !t.includes(SELF_ECHO)) user = t;
+  }
+  return { assistant, user };
+}
+
+function readState(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; }
+}
+
+function reason(packId, sentence) {
+  return [
+    'Your last message stated a next action, and then the turn ended without taking it.',
+    '',
+    `Detected by the ${packId} pack, in: "${sentence}"`,
+    '',
+    'UDS standard turn-completion-integrity (R1): a stated next action is not optional.',
+    '',
+    'Do one of these now:',
+    '  (a) take the action you just said you would take;',
+    '  (b) if it is actually blocked, say what blocks it and what you need, then do',
+    '      the next item that is not blocked;',
+    '  (c) if everything is done or blocked, list every remaining item WITH the',
+    '      person or input it waits on. That itemized list is the only shape of',
+    '      ending that R2 accepts — "the main parts are done" is not one.',
+  ].join('\n');
+}
+
+async function main() {
+  let raw = '';
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch {
+    return;
+  }
+
+  let data;
+  try { data = JSON.parse(raw); } catch { return; }
+  if (!data || typeof data !== 'object') return;
+  if (data.stop_hook_active === true) return;
+
+  const tp = data.transcript_path;
+  if (!tp || !existsSync(tp)) return;   // cannot tell is not the same as should block
+
+  const sid = String(data.session_id || 'unknown');
+  const statePath = join(STATE_DIR, `${sid}.json`);
+  const st = readState(statePath);
+  const now = Date.now() / 1000;
+
+  const stamps = (Array.isArray(st.stamps) ? st.stamps : [])
+    .filter((t) => typeof t === 'number' && now - t < WINDOW_SEC);
+  if (stamps.length >= MAX_BLOCKS_PER_WINDOW) return;
+  if (now - (st.last || 0) < COOLDOWN_SEC) return;
+
+  let msgs;
+  try { msgs = lastMessages(tp); } catch { return; }
+  if (!msgs.assistant.trim()) return;
+
+  const { packs } = await loadPacks();
+  if (packs.length === 0) return;
+
+  // The human asked for the turn to end. That is a legitimate ending, and the
+  // agent's own words cannot distinguish it from an abandoned commitment.
+  if (userAskedToStop(msgs.user, packs)) return;
+
+  const hit = detectCommitment(msgs.assistant, packs);
+  if (!hit.fired) return;
+
+  stamps.push(now);
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(statePath, JSON.stringify({ stamps, last: now }));
+  } catch {
+    /* state is an optimisation; failing to write it must not change the verdict */
+  }
+
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: reason(hit.packId, hit.sentence),
+  }));
+}
+
+async function selfTest() {
+  const { packs, failed } = await loadPacks();
+  let ok = failed.length === 0 && packs.length === SHIPPED_LOCALES.length;
+  console.log(`[turn-completion] v${VERSION} — packs: ${packs.map((p) => p.id).join(', ')}`
+    + ` (${packs.length}/${SHIPPED_LOCALES.length} shipped locales)`);
+  for (const f of failed) console.log(`  x   locale ${f.id} failed to load — ${f.why}`);
+
+  for (const pack of packs) {
+    for (const [want, label, text] of pack.corpus) {
+      // Run against ALL packs, which is the shipped configuration. A pack that
+      // is correct alone and wrong beside another is not correct.
+      const got = detectCommitment(text, packs).fired;
+      const good = got === want;
+      ok &&= good;
+      console.log(`  ${good ? 'OK ' : 'x  '} [${pack.id}] ${want ? 'must block' : 'must pass'} — ${label}`
+        + (good ? '' : `   (got: ${got ? 'block' : 'pass'})`));
+    }
+    for (const [want, label, text] of pack.stopCorpus || []) {
+      const got = userAskedToStop(text, packs);
+      const good = got === want;
+      ok &&= good;
+      console.log(`  ${good ? 'OK ' : 'x  '} [${pack.id}] user ${want ? 'IS' : 'is NOT'} asking to stop — ${label}`
+        + (good ? '' : `   (got: ${got ? 'exempt' : 'not exempt'})`));
+    }
+  }
+  // The block message must contain the marker, or the hook cannot tell its own
+  // output from the human's next instruction.
+  const selfRecognised = reason('en', 'x').includes(SELF_ECHO);
+  ok &&= selfRecognised;
+  console.log(`  ${selfRecognised ? 'OK ' : 'x  '} block message carries the self-echo marker`);
+
+  console.log(`[turn-completion] self-test ${ok ? 'passed' : 'FAILED'}`);
+  process.exit(ok ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--self-test') {
+  await selfTest();
+} else if (arg === '--languages') {
+  const { packs } = await loadPacks();
+  console.log(packs.map((p) => `${p.id} (${p.label})`).join('\n'));
+  console.log('\nThis check reads prose. If you work in a language not listed above,'
+    + '\nit is installed and running but cannot fire. See turn-completion-integrity R8.');
+} else {
+  try { await main(); } catch { /* R5 */ }
+}