@event4u/agent-config 14.6.0 → 14.8.0

package/docs/guidelines/agent-infra/artifact-drafting-protocol-mechanics.md

@@ -87,10 +87,54 @@ those artifacts:
   to obtain.
 - **Scope is the batch, nothing more.** An artifact NOT declared in the
   roadmap (discovered mid-run) triggers the full interactive protocol —
-  or, under the contract, the scope-out-of-roadmap halt.
+  or, under the contract, the scope-out-of-roadmap halt. That halt is the
+  **default** and stays the default; see § Late artifacts below for the one
+  declared value that changes it.
 - Batch mode never skips the Research pass itself — it relocates and
   batches it. `artifact_protocol: skip` does not exist.
 
+### Late artifacts — `halt` by default, `auto-research` only when declared
+
+The bullet above is the whole rule when the contract says nothing. A contract
+may instead declare `late_artifacts: auto-research`
+([`roadmap-execution-contract § 2a`](../../../src/agent-src/contexts/execution/roadmap-execution-contract.md)),
+and then a mid-run discovery runs **this** procedure rather than halting:
+
+1. **Re-run Phase B against current state** — the same overlap scan the batch
+   ran at contract time, now over the artifact the run just found. Nothing new
+   is invented: this is the accepted-as-non-interactive procedure, later.
+2. **Extend verdict → extend silently.** The nearest match is edited. This is
+   the outcome the overlap scan exists to produce and it needs no approval it
+   did not already have.
+3. **Create verdict → derive Phase A from what is already on the record.** The
+   understand-answers come from the roadmap step text plus the decision-sheet
+   answers the user accepted. No new question is opened.
+4. **Genuine overlap conflict → halt.** Two plausible extend targets, or a
+   match whose scope contradicts the step, is a real decision and stops the
+   run.
+5. **Cap: three per run, then halt regardless of verdict.**
+
+`halt` remains the shipped default (`decision 2026-08-20`, AI council 2/2 on
+the `autonomy-defaults-sheet` fork; record
+`agents/evidence/council/drain-blocker-dispositions-a.md`). The reasoning is
+short: the cap bounds how far an unplanned artifact can drift the run, but it
+does not decide whether the drift is wanted, and the conservative side of that
+fork is the behaviour the tree already had. Making `auto-research` a declared
+value rather than an inherited one is also what makes its own kill criterion —
+the late-artifact revisit rate — attributable to the runs that chose it.
+Reverting is one word in each of the two tables; no mechanism depends on the
+default's direction.
+
+**Kill criterion for `auto-research`, at the site rather than in a roadmap:**
+a late-artifact revisit rate above 20 % — an auto-authored or auto-extended
+artifact later reworked or reverted — removes the value and returns every
+late discovery to `halt`. **No instrument today:** nothing counts late
+artifacts or their revisits, so the rate is unmeasured rather than low, and
+the cap of three is the only live bound. Recorded here because a criterion
+that lives only in the roadmap that flipped the default becomes unreachable
+the moment that roadmap is archived.
+
+
 ## Complexity budget — the six questions before a new artefact
 
 Folded here from the 9.4.0 review (Prio 5), which named the failure mode:

package/docs/guidelines/agent-infra/context-hygiene-mechanics.md

@@ -88,3 +88,29 @@ Exit code is always 0 — hooks must never block the agent loop.
 
 - `context-hygiene` (rule) — thresholds, 3-failure rule, tool-loop cap, read-loop Iron Law.
 - `systematic-debugging` § Debug micro-loop — the one-test-one-fix-one-rerun procedure.
+
+## The CI waiter — use the helper, never the hand-written loop
+
+`./scripts-run src/scripts/ci_settle <pr> [--timeout-min N] [--interval-sec N]`
+
+Exit codes: **0** settled green · **1** settled red, with the failing checks
+named · **2** did not settle, or the API could not be read — never a verdict.
+
+Four states classify as *not settled*, and each one is a way the hand-written
+form goes wrong: an API error, a non-zero `gh` exit, unparseable output, and
+**zero registered checks** (a run that has not registered its checks yet looks
+exactly like a finished one with nothing to report).
+
+**Why it exists.** Measured 2026-08-20:
+
+```bash
+until ! gh pr checks 1459 | grep -q "pending"; do sleep 60; done
+```
+
+The API then failed. Its error text — `error connecting to api.github.com` —
+contains no `pending`, so the loop exited, the session reported a settle that
+had not happened, and the claim had to be retracted to the user in the next
+reply. The bug is not the sleep or the grep: **absence of the word `pending`
+was treated as evidence of completion**, and an error is neither settled nor
+pending. The exit condition is the part that is easy to get wrong, so it lives
+in one place rather than in every agent's head.

package/docs/guidelines/agent-infra/false-green.md

@@ -1,6 +1,6 @@
 # False Green — the ways a passing result can be wrong here
 
-> Nine failure modes, each with the detection command that distinguishes "found nothing" from "looked at nothing". Every one is drawn from this repository's own history, not from a generic checklist.
+> Eleven failure modes, each with the detection command that distinguishes "found nothing" from "looked at nothing". Every one is drawn from this repository's own history, not from a generic checklist.
 
 _Origin: `road-to-skill-ecosystem-gate-integrity` Phase 3. The recurring shape is not that a gate reports a wrong finding — it is that a gate reports **no** finding for a reason unrelated to the property it guards, and no output distinguishes the two cases._
 
@@ -128,6 +128,52 @@ empty rendered template equals an absent target file. The gate reports
 comparing. Two absences are the absence of a comparison, not the presence of a
 match. The estate-wide audit is below.
 
+### 10. Hook-bypass override
+
+The gate never ran because the hook that runs it was disabled for that
+invocation. `git commit --no-verify` (and its short `-n` form) skips every
+pre-commit hook; `core.hooksPath` repointed at an empty directory skips them
+permanently and silently. Both produce a commit that looks exactly like a
+commit whose hooks passed. The same shape reaches the runtime hook layer: a
+concern bound in the manifest is still inert on a host that does not honour a
+deny, so "the guard is registered" is not "the guard fired".
+
+<!-- example-fence-allow: git-no-verify -- the fence teaches how to DETECT the core.hooksPath bypass; the forbidden form has to appear for the diagnostic to be readable, and every line here is a read-only query -->
+```bash
+git config --get core.hooksPath                       # empty = repo default, good
+./scripts-run src/scripts/hooks/block_no_verify --help # the tool-call guard
+agent-config hooks:status                             # per-host bindings, not the manifest
+```
+
+**Structural fix:** the bypass is blocked at tool-call time by
+`block-no-verify` on the one host that honours a deny, and the authoritative
+gate is remote CI, which no local override can skip. Never read a local green
+as evidence when the hook path was overridden — re-run in CI, or run the gate
+directly rather than through the hook.
+
+### 11. Cached-green reuse
+
+The green belongs to a different input than the one being judged. Three real
+shapes here. A gate that reads `dist/agent-src/` passes against a **stale
+projection** while the `src/` change it was meant to judge is not in the tree it
+scanned — the recorded trap is a worktree whose stale `dist` faked generator
+drift, and its mirror, a golden capture reading `dist` where the assertion was
+about `src`. A count ratchet sits inside its limit for so long that "within
+budget" stops meaning anything, which is why a baseline carries an expiry at
+all. And the conversational form: trusting a verification run earlier in the
+same session, after the tree has moved underneath it.
+
+```bash
+bash src/scripts/condense.sh --changed        # dist != rewrite(src) => the scan root is stale
+./scripts-run src/scripts/check_condensation --summary   # byte-exactness dist vs rewrite(src)
+```
+
+**Structural fix:** regenerate before judging (`task sync` then
+`task generate-tools`, in that order), and treat a baseline unchanged past
+`STALE_AFTER_DAYS` (56, `_lib/gate_baseline.ts:39`) as suppression rather than
+as headroom. A completion claim rests on a run made **after** the last edit, not
+on the freshest run you happen to remember.
+
 ## The audited sync/parity gates
 
 Comparison-shaped gates carry entry #9's failure mode by default: `diff a b`

package/docs/guidelines/agent-infra/memory-access.md

@@ -8,6 +8,23 @@ abstraction backed by `scripts/memory_lookup.ts` (TypeScript, run via
 tsx). It reads curated YAML under `agents/memory/<type>/` and the
 agent-written `agents/memory/intake/*.jsonl` signal log.
 
+## Index by the moment, not only by the topic
+
+Every entry answers **"what was I about to do when this would have helped"** — a
+verb and its object (`author a roadmap`, `wait on CI`, `push a branch`, `edit a
+markdown section with a script`) — and the index carries a trigger-moment
+section keyed on those verbs beside the topic grouping.
+
+A store indexed only by subject is an index for *browsing*, and browsing is not
+the failure mode: an agent does not go looking for a trap it does not know
+exists. Measured 2026-08-20 on one instrumented session — of eleven error
+classes, **nine already had an entry** and all nine were read *after* the
+failure. The deficit was delivery, not knowledge.
+
+Writing the trigger key is part of writing the entry. A second index maintained
+separately from the entries rots, and a rotted index is worse than none because
+it still looks authoritative.
+
 ## The contract
 
 Consumers reach it via the CLI (`agent-config memory:lookup`) or the

package/docs/guidelines/agent-infra/recurring-criticism-mechanics.md

@@ -0,0 +1,96 @@
+# Recurring-criticism mechanics
+
+> Depth for the `recurring-criticism` rule — the past-disposition store list, the mechanism-is-the-defect classification, the hardening floor, and the failure-mode catalog.
+
+_No YAML frontmatter, deliberately: every other guideline under `docs/guidelines/`
+is frontmatter-less, and a `name:` key here makes the two MCP resource loaders
+derive different URIs for the same file — one from the key
+(`guideline://recurring-criticism-mechanics`), one from the path
+(`guideline://agent-infra/recurring-criticism-mechanics`). That is a
+`mcp_parity_smoke` drift, and it only surfaces once `dist/cli/agent-config.js`
+is built, so the local suite passes and CI does not._
+
+Depth for [`recurring-criticism`](../../../src/rules/recurring-criticism.md). The
+rule carries the obligation; this carries the lookup addresses and the reasoning
+that would otherwise be paid in every session — that rule is phrase-triggered, and
+a phrase-triggered rule is unconditionally loaded on Claude (the emitter writes no
+`paths:` when any non-path trigger is present), so every line in it is a line every
+session pays for. This file is read on demand.
+
+## Look it up before re-deriving it
+
+Without a mechanism that forces a reference to the earlier disposition, every
+recurrence becomes a fresh investigation even where the answer already exists
+<!-- harvest:forced-lookup-of-past-root-causes -->. The stores are fragmented and
+only partly queryable, so **name which one you checked**:
+
+| Store | Path | Queryable? |
+|---|---|---|
+| ADRs + index | `docs/decisions/` + `INDEX.md`, via `adr_cite_check <ADR-NNN>` | yes — status, `review_trigger` state, successors |
+| Estate / activation / low-impact dispositions | `agents/decisions/*.yml`, `agents/decisions/low-impact-decisions.md` | yes, closed vocabularies |
+| Roadmap dispositions | `agents/roadmaps/{archive,skipped,later}/` | `later/` only; `skipped/` carries its reason as header prose |
+| Curated memory | `agents/memory/*.yml` | yes |
+| Analysis documents | `agents/evidence/analysis/` | grep only |
+| Harvest / borrow ledgers | `provenance/*.jsonl` | yes, but `adopt`/`adapt` only |
+
+**Rejections are the weak spot, and by design.** `provenance/README.md` states that
+a `reject` verdict lives in the analysis document rather than a ledger, because
+nothing in the tree cites it. So "I found nothing" here means *unstructured prose
+was grepped*, never *nothing was decided*. Say which of the two you mean — the
+difference decides whether the recurrence is new information or a lookup failure.
+
+## The mechanism is the candidate defect, not the item
+
+Classify what was missing before choosing an artefact — the taxonomy in
+[`skill-improvement-pipeline`](../../../src/skills/skill-improvement-pipeline/SKILL.md)
+§ Classify the missing component (instruction · source-of-truth · tool · validator ·
+permission · sandbox · evaluation · recovery-path) is the one to use, because "add
+another rule" is the answer that feels right and is usually wrong.
+
+Then land the learning where it **constrains** the next run, per
+[`learning-to-rule-or-skill`](../../../src/skills/learning-to-rule-or-skill/SKILL.md).
+A lesson that does not narrow the next attempt produces thrashing rather than
+convergence <!-- harvest:unconstraining-lesson-thrashes -->; a learning that lives
+only in a reply is not a learning, it is a note.
+
+**Third recurrence of the same class escalates to structure** —
+[`decision-review`](../../../src/skills/decision-review/SKILL.md) § Escalation owns
+the threshold, and its point is worth restating: a louder restatement of a rule the
+agent keeps missing is the one response already known not to work. At that point
+the choice is a deterministic gate or deletion, not more prose.
+
+## The hardening floor
+
+Self-improvement loops can regress the artefact they improve
+<!-- harvest:self-improvement-can-self-regress -->. Two consequences:
+
+- A hardening change carries the **same evidence bar** as any other change. "We
+  learned something" is not a licence, and a mechanism proposed in response to a
+  recurrence still needs a measured false-positive rate before it becomes CI.
+- It never arrives as a **weakened** gate, a widened allowlist, a lifted Hard
+  Floor, or a loosened ratchet. If the only available hardening lowers a floor, the
+  recurrence escalates to the owner instead — that transition is owner-reserved per
+  [`decision-revisit-gate`](../../../src/rules/decision-revisit-gate.md) § Who
+  decides.
+
+## Failure modes
+
+- **Resolving on the count.** "You have said it three times, so you are right" is
+  the sycophancy failure with a procedure attached. The count opens the question.
+- **Resolving on the count, inverted.** "It is only the second time, so the old
+  call stands" — the repetition still shifted the burden of proof.
+- **Naming no outcome.** A resolution that does not say which of the three applies
+  (decision wrong · never recorded · unreachable) has not resolved anything.
+- **Grepping prose and reporting absence.** See the rejection note above.
+- **Treating a resemblance as a recurrence.** Mechanism-match runs first; a new
+  complaint that tests a different mechanism is a new finding.
+- **Hardening the item instead of the mechanism.** Fixing the one instance leaves
+  the surface that dismissed it intact, which is what produces the fourth
+  recurrence.
+- **Writing the learning into the reply.** It has to land in an artefact.
+
+## See also
+
+- [`recurring-criticism`](../../../src/rules/recurring-criticism.md) — the obligation.
+- [`decision-revisit-gate`](../../../src/rules/decision-revisit-gate.md) — the other entrance (a lock blocking a change), the five steps, the owner-reserved table.
+- [`self-repair-loop`](../../../src/rules/self-repair-loop.md) — the single-occurrence intake and the `occurrences` counter this rule consumes.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "14.6.0",
+    "version": "14.8.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/agent-src/scripts/archival_sweep.ts

@@ -0,0 +1,117 @@
+/**
+ * Archival-sweep spawner for the roadmap dashboard.
+ *
+ * Split out of `update_roadmap_progress.ts` rather than authored there: that
+ * file sits at the 1500-line source ceiling `check_source_size_budget`
+ * ratchets, and the sweep plus its contract is the newest and most separable
+ * thing in it. The contract below is that text, moved intact.
+ *
+ * `--archive` (opt-in; wired into `task roadmap-progress` and
+ * `agent-config roadmap:progress`) runs the archival sweep before rendering
+ * instead of printing "Completed roadmaps not yet archived" and leaving the
+ * work to a human who has been ignoring the line for weeks. It is a flag rather
+ * than the default because the PostToolUse hook re-runs the WRITE path once per
+ * turn on every roadmap edit, and a hook that silently `git mv`s files mid-work
+ * is a bigger problem than the warning it would remove. `--check` never
+ * archives — see `run_archival_sweep`.
+ *
+ * WHY the warning existed at all, since this is the one place a reader of the
+ * flag will look: the sweep's own default is `--changed-only`, so a PR archives
+ * exactly the roadmaps it completed. A roadmap completed by a PR whose sweep did
+ * not run is then complete, on the trunk, and OUTSIDE every later branch's
+ * history — no `--changed-only` sweep finds it again. Measured 2026-08-20: six
+ * such roadmaps, with every regen reprinting the warning at whoever ran it.
+ * `/create-pr` § 1c keeps `--changed-only`; repo-wide reconciliation is this
+ * flag's job and nothing else's.
+ *
+ * This layout is deliberate rather than convenient: the prose homes for it are
+ * both at their ceilings (`roadmap-progress-mechanics.md` sits 122 chars under
+ * the 16,000-char depth ceiling, and `roadmap-management/SKILL.md` tips
+ * `skill_too_large` on any prose block), so the contract lives with the code it
+ * governs. Moving it out means making room first.
+ *
+ * AI council 2026-08-20 (anthropic + openai, blind peer review): both seats
+ * converged on explicit opt-in + `--all` scope + hook archival-free, and both
+ * independently required the `--check` exclusion, the archive-before-render
+ * order, and that a failed sweep must not render. RECORDED DISSENT: one seat
+ * argued for flipping the sweep's own default to `--all` instead. Rejected —
+ * that makes every PR a potential estate-wide cleanup, which is exactly what
+ * `--changed-only` exists to prevent.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Same directory as `update_roadmap_progress.ts`, so the `path.dirname` below
+// resolves the sweep script exactly as it did before the split.
+const _HERE = fileURLToPath(import.meta.url);
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Run the archival sweep for every complete roadmap, in-place.
+ *
+ * Spawned rather than imported: `archive_completed_roadmaps.ts` imports
+ * `collect` from `update_roadmap_progress.ts`, so a static import back would close a cycle, and
+ * `main()` is synchronous so a dynamic `await import()` is not available either.
+ * The sweep is the same twin `_regen_dashboard` already spawns in the other
+ * direction, so the spawn shape is the established one in this pair.
+ *
+ * No recursion: the sweep re-runs this script with NO flags, so its inner
+ * dashboard pass has archival off and terminates at depth 2.
+ *
+ * `--all`, not the sweep's `--changed-only` default. The default exists so a PR
+ * archives exactly the roadmaps it completed; here the caller asked the
+ * repo-wide dashboard to reconcile the estate, and the roadmaps that leak are
+ * by construction the ones NOT in this branch's history — six had accumulated
+ * on the trunk while the warning printed every regen. A roadmap the sweep
+ * refuses (open blockers) stays put and is still reported below.
+ */
+export function run_archival_sweep(root: string): SweepResult {
+    const script = path.join(path.dirname(_HERE), 'archive_completed_roadmaps.ts');
+    if (!_isFile(script)) {
+        // A consumer install without the sweep script: nothing to run, and that
+        // is a normal state — the warning below still reports the roadmaps.
+        return { ran: false, ok: true, stdout: '', stderr: '' };
+    }
+    const argv = [script, '--all', '--repo-root', root];
+    const binName = process.platform === 'win32' ? 'tsx.cmd' : 'tsx';
+    let dir = path.dirname(_HERE);
+    for (;;) {
+        const candidate = path.join(dir, 'node_modules', '.bin', binName);
+        if (fs.existsSync(candidate)) {
+            return _sweepResult(spawnSync(candidate, argv, { cwd: root, encoding: 'utf-8' }));
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return _sweepResult(spawnSync('npx', ['tsx', ...argv], { cwd: root, encoding: 'utf-8' }));
+}
+
+export interface SweepResult {
+    ran: boolean;
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+
+function _sweepResult(r: ReturnType<typeof spawnSync>): SweepResult {
+    return {
+        ran: true,
+        ok: r.status === 0,
+        stdout: String(r.stdout ?? ''),
+        stderr: String(r.stderr ?? ''),
+    };
+}
+

package/src/agent-src/scripts/archive_completed_roadmaps.ts

@@ -31,6 +31,7 @@
  *     ./scripts-run src/scripts/archive_completed_roadmaps            # --changed-only (default)
  *     ./scripts-run src/scripts/archive_completed_roadmaps --all
  *     ./scripts-run src/scripts/archive_completed_roadmaps --base origin/main --dry-run
+ *     ./scripts-run src/scripts/archive_completed_roadmaps --repo-root /path/to/proj
  *
  * --- Parity notes (ADR-200) ---
  *
@@ -397,10 +398,13 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
     // Python: `_run([sys.executable, str(script)], root)`; the twin spawns the
     // dashboard generator twin through the same `tsx` runtime, cwd=root.
     _runTwin(root, script);
-    const dash = path.join(root, 'agents', 'roadmaps-progress.md');
-    if (_isFile(dash)) {
-        _run(['git', 'add', '--', 'agents/roadmaps-progress.md'], root);
-    }
+    // The dashboard is NOT staged. It is gitignored in this repository, and
+    // `git add -- <ignored-path>` exits 1 with "The following paths are ignored"
+    // -- a code `_run` returns and this call site discarded, so the previous
+    // `git add` here was a silent no-op from the moment the file was untracked
+    // (2026-08-21) and nothing objected. Regenerating it is still correct; the
+    // developer reads it on disk, and `task roadmap-progress-check` compares a
+    // present copy against a fresh render.
 }
 
 /**
@@ -462,19 +466,21 @@ function _runTwin(root: string, script: string): void {
 const _PROG = 'archive_completed_roadmaps.py';
 
 function _usage(): string {
-    return `usage: ${_PROG} [-h] [--all] [--base BASE] [--dry-run]\n`;
+    return `usage: ${_PROG} [-h] [--all] [--base BASE] [--dry-run] [--repo-root REPO_ROOT]\n`;
 }
 
 interface Args {
     all: boolean;
     base: string;
     dry_run: boolean;
+    repo_root: string | null;
 }
 
 function _parseArgs(argv: readonly string[]): Args {
     let all = false;
     let base = 'origin/main';
     let dry_run = false;
+    let repo_root: string | null = null;
     const emitError = (msg: string): never => {
         process.stderr.write(_usage());
         process.stderr.write(`${_PROG}: error: ${msg}\n`);
@@ -502,17 +508,30 @@ function _parseArgs(argv: readonly string[]): Args {
         } else if (tok.startsWith('--base=')) {
             base = tok.slice('--base='.length);
             i += 1;
+        } else if (tok === '--repo-root') {
+            const val = argv[i + 1];
+            if (val === undefined) {
+                emitError('argument --repo-root: expected one argument');
+            }
+            repo_root = val as string;
+            i += 2;
+        } else if (tok.startsWith('--repo-root=')) {
+            repo_root = tok.slice('--repo-root='.length);
+            i += 1;
         } else {
             emitError(`unrecognized arguments: ${tok}`);
         }
     }
-    return { all, base, dry_run };
+    return { all, base, dry_run, repo_root };
 }
 
 function main(argv?: readonly string[]): number {
     const ns = _parseArgs(argv ?? process.argv.slice(2));
 
-    const root = _repo_root();
+    // An explicit `--repo-root` wins over the `git rev-parse` resolution. The
+    // dashboard generator passes it so a monorepo sub-project sweep cannot walk
+    // up to the enclosing repo and archive the PARENT's roadmaps.
+    const root = ns.repo_root ?? _repo_root();
     const archived = archive_completed(root, {
         changed_only: !ns.all,
         base: ns.base,