Skip to content

v5.3.0

Choose a tag to compare

@Kanevry Kanevry released this 22 Sep 06:55
· 567 commits to main since this release

Added

  • scripts/lib/tail-window.mjs (readTailWindow(file, maxBytes) → { text, cut, size }) — the ONE bounded tail-window reader for append-only JSONL ledgers and transcripts, replacing five private copies of the same byte-window primitive: hooks/on-stop.mjs, hooks/subagent-telemetry.mjs, scripts/lib/agent-status.mjs, scripts/lib/session-id.mjs and scripts/lib/telemetry-flush-health-banner.mjs (#1272). Each caller keeps its own error mapping (null / [] / discriminated result / throw); the module owns only the window, loops until it is filled, and reports cut so a caller can drop the partial first line. Named ceiling (BV-004): the window is held in memory in one piece — fine for the 64 KiB..1 MiB windows in use, revisit above ~16 MiB. New suite tests/lib/tail-window.test.mjs; hooks/_lib/hook-import-set.json regenerated (the module is reachable from four hook entry files).

  • consumeDialecticPending({ repoRoot }) in scripts/lib/auto-dialectic.mjs, plus the Step 6.4 loop-closing block in skills/evolve/references/evolve-dialectic-mode.md (#1380). After a successful /evolve dialectic --apply — or after the operator explicitly discards a reviewed proposal — the skill now writes the last-run stamp AND deletes .orchestrator/dialectic-pending.md. Nothing else writes the one or removes the other, so without these two calls the session-start maintenance-due probe reported dialectic and pending-sidecar as due forever. The same step now serialises result.diff (an object { user?, agent? }) into the Markdown string writeDialecticPending expects — passing the object threw TypeError.

  • scripts/lib/reconcile/backlog.mjs — a LEAF module holding partitionMaterialized / countReconcileBacklog, re-exported from scripts/lib/reconcile/engine.mjs so every existing caller is unchanged. The session-start reconcile-nudge probe imports the count from here instead of from the write-capable engine, which dragged the emitter, renderer, unicode validator and candidate-store writer into a read-only banner's static closure: 11 modules / 151,946 B → 19 modules / 322,897 B (+112 %, measured 2026-09-18), inherited unasked by scripts/lib/maintenance-due-banner.mjs. The leaf brings the probe back to 13 modules / 176,331 B (and the maintenance-due banner from 35 / 577,439 B to 29 / 430,873 B); the +2 modules against the pre-session closure are the leaf itself plus eligibility.mjs, the price of the probe counting the same population /reconcile does. The runtime cost was never the point; a banner must not be able to reach a writer.

  • Three runtime-read Session Config surfaces that no document described, now in docs/session-config-reference.md first and docs/session-config-template.md second (#1155, #1243, #1365): cross-repo.projects (a block key, NOT the flat cross-repos list — only the inline projects: [a, b] form is read, a - block list yields [] silently), worktree-exclude (with its measured scope limit: createWorktree() has no production caller, so the key changes nothing in a wave today) and the whole gitlab-portfolio block (enabled / mode / stale-days / critical-labels — the last is block-form only; an inline list is silently ignored).

  • scripts/lib/js-mask.mjs (maskSource(src, { keepLiterals })) — ONE JavaScript lexer for every "separate code from data" scanner here, with the regex-literal branch three hand-rolled stripComments copies never had (#1388). Five consumers: scripts/lib/validate/check-untracked-test-deps.mjs (where it grew; a one-line re-export keeps the old import path alive, because package.json carries no exports map and every scripts/lib/** path is therefore public), check-entry-guard.mjs, plus the three converted this session — check-validator-registration.mjs, check-test-git-config-target.mjs and scripts/lib/auq/parse.mjs (see Fixed for what each was measurably getting wrong). Named ceiling (BV-004) on the one-token keyword lookback, measured 2026-09-18 over git ls-files '*.mjs' (1245 files): 0 genuine division chains after return/typeof/case/… — all 18 files whose masking the lookback changes carry a real regex literal; revisit trigger is the first such chain.

  • scripts/lib/vault-yaml.mjs (readVaultSlug(repoRoot), VAULT_YAML_FILE) — the reader for the metadata.slug key in a repo's own .vault.yaml, which nothing read until now (#1131). Every vault writer derived the vault folder from the CHECKOUT DIRECTORY name instead (narrative-mirror.mjs via subjectToSlug, vault-mirror/namespace.mjs via basename(process.cwd())), so a repo whose directory name differs from its registered slug had its narrative, sessions and learnings filed under a second, wrong folder — and the #829 loose-slug healer only repairs case and punctuation drift, never a genuinely different name. Precedence is now explicit repo opt > vault-name override > declared slug > basename (narrative-mirror.mjs) and vaultName > declared slug > deriveRepo() (namespace.mjs, which stays a leaf: node:fs, node:path, node:module, vault-mirror/utils.mjs). A declared slug SKIPS resolveLooseSlug — it IS the canonical folder name, and healing it re-opens the ambiguity that keeps a duplicate pair alive once one exists. The reader never throws: absent file, unreadable file, malformed YAML, missing key, non-string or non-slug value all return null and leave the caller on its pre-#1131 chain, and js-yaml is resolved lazily through createRequire so a checkout without node_modules cannot crash at module load.

  • renderPendingBody(diff) / comparePendingBody() in scripts/lib/auto-dialectic.mjs plus the Step 6.4 prose and its AUQ in skills/evolve/references/evolve-dialectic-mode.md (#1386). --apply now compares the FRESHLY derived body against the sidecar the operator actually reviewed before any peer card is written. The serializer moved out of the skill's JS snippet VERBATIM so both paths build the body from one implementation — two hand-copied serializers would report drift that is only formatting.

  • .orchestrator/consumed/<ISO-stamp>-<rand>-dialectic-pending.md (DIALECTIC_CONSUMED_DIR, DIALECTIC_CONSUMED_RETENTION = 10, #1388): consumeDialecticPending MOVES the sidecar instead of unlinking it — it was the only copy of what the operator reviewed. The maintenance-due probe reads an explicit two-path list, so an archived file does not re-raise pending-sidecar (#1380 stays fixed). Ceiling + revisit trigger (BV-004): newest 10; revisit if checkStaleArtifacts ever reports a consumed/ file, since it counts every untracked .orchestrator/** file older than 30 days. The prune is best-effort — a failure never fails a consume.

  • isRuleExpired(rawExpiry, now, onUnparseable), exported from scripts/lib/rule-loader.mjs and now also the gate in scripts/lib/reconcile/backlog.mjs's defaultReadMaterializedProvenance (#1387). An EXPIRED rule file is skipped WHOLE — frontmatter key and body bullets alike — so its learnings stop counting as materialized by a rule that no longer reaches any agent (materialized forever, re-proposable never). ONE predicate, ONE Date.parse and one clock reading per scan, fail-open in both consumers: an absent or unparseable expires-at is NOT expired, because fail-closed would un-materialize the whole corpus on one typo. Two limits documented in docs/rule-authoring.md § Consolidated rules and skills/reconcile/SKILL.md, both measured 2026-09-18 and both left unsolved on purpose: it covers only the on-disk half of partitionMaterialized (79 of this repo's 92 provenance keys are ALSO sidecar-terminal, so 13 keys actually return — the sidecar half carries operator DECLINES and must not re-ask an answered question), and a file the sweep cannot split (no-1to1-mapping &c.) that then expires legitimately re-proposes on every run with no mechanical exit (--dry-run --json reported skipped: [] over 7 generated files, so the live tree is clear).

  • header_raises in the sweep-expired-rules summary and its human stdout line (scripts/sweep-expired-rules.mjs, summarize now exported, #1388). A header-raise is an action: 'rewrite' plan carrying reason: 'header-raise', so it was counted inside rewrites and invisible on stdout although --json always carried plans[].reason. It is a SUBSET of rewrites, never a sibling — the two are deliberately not disjoint.

  • malformed_scope_files on the verifyWaveScope report, the scope_verified payload and the human table (scripts/lib/scope-echo.mjs, docs/events-schema.md; #1379). A per-agent <state-dir>/filescopes/wave-<N>/*.json that cannot be read or parsed was skipped silently, which made a wave with corrupt scope files indistinguishable from one that was never injected — the same digest-unknown / injection-missing verdicts either way. Always present, including as 0, the same honesty guarantee malformed_lines carries for the ledger side (HR-105). A file that parses but holds an empty or non-array scope is NOT counted: an empty scope is legitimate.

  • closeIssues() and the --close [--vcs gitlab|github] [-R <spec>] <id>... CLI in scripts/lib/issue-close-strip-labels.mjs (#308) — one call strips every status:* label, closes, then re-reads each issue, printing one JSON line per id ({id, stripped, closed, state}) and exiting 1 when any id did not verify as closed. skills/session-end/references/phase-5-issue-cleanup.md Phase 5 now runs this single command instead of the old two-step stripStatusLabels + glab issue close prose, which had been skipped often enough that 339 closed issues still carried status:in-progress (measured 2026-09-19).

  • WAVE_KEY_ALIASES (agents_planned/agents_started/agents_completed → agent_count_*) and normalizeWaveKeys() in scripts/lib/session-schema/{constants,normalizer}.mjs, applied on read by normalizeSession and on write by scripts/emit-session.mjs (#1390 P1) — one recorded session (main-2026-09-18-session-1, 5 waves) had written the de-underscored spelling, so every agent_count_* reader saw undefined for its waves. scripts/emit-session.mjs also derives the optional field session_start_ref from STATE.md's session-start-ref frontmatter — owner-checked, full sha only — so /evolve analyze gets an attributable commit range instead of a time window that also catches a parallel session's commits (#1339 P8). scripts/lib/session-schema.mjs's barrel now also re-exports isCoordinatorDirectHousekeeping from the existing session-schema/filters.mjs.

  • resolveRepoNamespace({ repoRoot }) in scripts/lib/vault-mirror/namespace.mjs (#1389) — reads the declared .vault.yaml slug from a caller-supplied repoRoot instead of always process.cwd(); scripts/lib/vault-mirror/process.mjs and scripts/vault-mirror.mjs thread the CLI's invocation cwd through. Additive: every caller that omits repoRoot is unaffected.

  • neutralizeFingerprintSentinel() and fingerprintSentinelLine(), exported from scripts/lib/test-runner/issue-reconcile.mjs (#1339 P6) — the one shared sentinel-neutralisation and sentinel-writer pair, now also used by scripts/lib/ux-grill/reconcile.mjs's oneLine()/buildUxGrillIssueBody() instead of a second hand-copied sanitizeSentinel().

  • scripts/lib/skill-evidence-window.mjs — the skill-applied-judge (instruction-adherence/report-quality) gets an actual evidence window for the first time: excerpts built around the skill's call site in the transcript instead of a tail slice (#1399). Measured: the call site landed inside the old tail window in 6 of 67 cases, inside the new call-site window in 67 of 67. runSkillJudge no longer dispatches on near-empty evidence — the previous '' default was 1387 characters, under the 8000-token gate, and was silently judged as though it were real transcript content. Session-end Phase 3.6.6 now joins over the raw UUID.

  • A second PSA-006 claim class, gate-verdict (hooks/_lib/subagent-transcript.mjs, hooks/post-subagent-discovery-validator.mjs; #1385 S2) — a completion/gate-green assertion (STATUS: done, "tests pass", "alles grün") carrying no run receipt (a pass/fail count, a file count, or an exit code) and no adjacent measurement command. The scanner had been structurally blind to exactly these two line shapes: the #1198 gate-summary exemption skipped STATUS:/"N passed" lines before any pattern ran. Measured on a 130-case labelled corpus built for this fix: the scanner answered "no violation" on 128 of 130 before the fix (accuracy 30.2%, Cohen's κ 0.007 — indistinguishable from guessing); after, wanted hits went 6/92 → 12/92 with false positives unchanged at 3/34. Records now carry kind; a record with no kind predates the split and is distributional by construction. The hook remains log-and-warn — it blocks nothing.

  • scripts/release-session-lock.mjs — a new CLI that releases the session lock, emits lock.released with explicit session/lock IDs, and reads the lock back to confirm absence; exit 0 only when the release is verified (#1395). skills/session-end/SKILL.md Phase 3.8 is now this single call instead of prose instructions to release the lock. Measured before this change: this repo's own ledger held 5 acquired events against 0 released; fleet-wide 110 of 702 (15.7%).

  • orchestrator.wave_dispatch.worktree_base_checked (#1413) — a new event from the dispatch hook, which compares HEAD against session-start-ref behind a process-local identity check and warns (never blocks) on drift; the worktree base belongs to the harness, since the Agent tool itself carries no base field. The event always carries a stale value on BOTH outcomes, on purpose — reporting only the positive case would leave the firing rate unfalsifiable. Measured: per-wave isolation shows in 2 of 455 records, a commit marker in 0 of 455.

  • Epic #1425 Stufe 1, Teil A — scripts/lib/process-group.mjs (spawnInGroup, killProcessGroup, verifyProcessIdentity, installExitHandler, recordGateProcess/readGateProcessLedger/pruneGateProcessLedger, buildCommandSignature). spawn(cmd, { shell: true }) makes the SHELL the child, so child.kill() signalled that shell only and its own children (tsgo --noEmit, vitest workers) were reparented to PID 1 and kept running — the 2026-09-20 incident on this host: four orphaned tsgo processes, two at PPID 1, 86–588 % CPU and up to 8.0 GB RSS each, the machine at 13 % free memory. detached: true makes the shell a process-group LEADER, so process.kill(-pgid, sig) reaches every descendant that did not setsid away. The kill is a ladder — SIGTERM → DEFAULT_KILL_GRACE_MS grace (re-exported from wave-executor/dispatch-common.mjs, never re-defined) → SIGKILL to the GROUP — because a grandchild installing trap "" TERM survives the group SIGTERM (measured on Darwin 25.6.0, 2026-09-21). Three further measured constraints are wired in rather than assumed: close fires only once every group member has closed the shared pipe (hence a hard deadline), maxBuffer does not exist on async spawn (hence a hand-rolled 16 MiB byte cap reproducing the existing spawnSync/ENOBUFS contract), and a detached child survives its parent's exit at PPID 1 (hence installExitHandler). A4, the ancestry register: every gate process this repo starts itself is recorded with pid, pgid, start time and command signature in .orchestrator/runtime/gate-processes.jsonl — the identity basis Teil B joins against.

  • Epic #1425 Stufe 1, Teil B — scripts/lib/orphan-reaper.mjs (#1430, #1431, #1433): the net under the process-group kill, for orphans that happen anyway (a crashed session, a harness SIGKILL, a leak from a foreign repo on the same host). Shape is the lock-reaper.mjs split — parsePsSnapshot → decideReapCandidates (PURE: no I/O, no signal, fully testable from ps text fixtures) → targeted ps -p identity re-check → killProcessGroup → wait → re-measure. A candidate is a CONJUNCTION (register ∧ PPID 1 ∧ age ∧ read-only command signature ∧ identity still verifying), because PPID 1 alone is a weapon pointed at the operating system: 538 of 784 processes (68.6 %) had PPID 1 on this host, measured 2026-09-21. The identity gate runs before SIGTERM and before SIGKILL, so a recycled pgid aborts the ladder instead of being signalled. Effect is read back after verify-wait-ms — survived_sigkill is never booked as success (PRD B6: on 2026-09-20 the ad-hoc check falsely reported "still alive" because it measured immediately after kill -9). Every decision, including a withdrawn one, is appended to .orchestrator/metrics/reaper-audit.jsonl; falseAlarmRate() judges the instrument over a rolling window of decisions and reports instrument_suspect above the 10 % HR-101 ceiling without ever acting on it. The existing detector (countZombieProcesses) would have counted ZERO in the 2026-09-20 incident: its ps carries no ppid and no rss, and it defines a zombie as IDLE — the exact opposite of a runaway.

  • Orphan-scan triggers in two hooks, plus the reaper: and gate: Session Config blocks (#1432 B4). hooks/post-tool-batch-wave-signal.mjs (PostToolBatch — the only hook with measurably high frequency during a wave) and hooks/on-stop.mjs (Stop + SubagentStop — which lands exactly when gate children have just finished) each do one config read plus one stat of the shared throttle marker .orchestrator/tmp/reaper-last-scan, then hand the work to a DETACHED, unref()-ed child running the new CLI tail of orphan-reaper.mjs. Nothing is scanned inline: one ps round-trip out of Node was measured at ~47 ms, alone over the 50 ms reaper.max-hook-latency-ms budget; steady-state hook latency with the trigger in place measured 0.15 ms. New parsers scripts/lib/config/reaper.mjs (_parseReaper) and scripts/lib/config/gate.mjs (_parseGate), both tolerant and independent of the ## Session Config section boundary, with the blocks documented opt-in in docs/session-config-template.md and docs/session-config-reference.md. New event orchestrator.reaper.scan_completed, emitted at most once per scan and only when the scan found something (candidates, reports or kills) or the instrument itself is suspect (false-alarm rate over 10 % of the last false-alarm-window decisions) — a per-fire record would be exactly the always-on signal HR-101 calls a broken instrument.

  • scripts/lib/validate/check-hook-entry-guards.mjs (#1422) — an AST oracle over the hooks registered in the four hook manifests, flagging missing-entry-guard and toplevel-profile-exit. Registered BLOCKING in scripts/validate-plugin.mjs (232 checks / 0 failures at 110f334d). The class it closes is concrete: a hook-reachable module without an entry guard executes its whole program when imported.

  • scripts/check-sessions-integrity.mjs (#1417) — CLI front-end for checkSessionsIntegrity (--session-id, --json; exit 0/1/2, a missing record deliberately exiting 1). Until now the check existed only as a node --input-type=module -e one-liner inside skills/session-end/session-metrics-write.md, because the function had no entry point. The #1408 record parsed fine and was still invalid (ended_at instead of completed_at, four required fields missing), so vault-mirror dropped it as skipped-invalid and nobody was told until the next session-start banner.

  • scanEventsBackwards() / listEventSourcesNewestFirst() in scripts/lib/events.mjs (#1414) — newest-first reading across ledger rotations, so a reader that only needs the recent tail stops at the first hit instead of parsing the whole corpus. Plus parseEtimeToSeconds() in scripts/lib/resource-probe/parsers.mjs, the ps etime parser the reaper's age criterion needs.

Changed

  • Default dialectic.budget-tokens 8000 → 32000 (DEFAULT_BUDGET_TOKENS in scripts/lib/config/dialectic.mjs, now the SSOT that scripts/dialectic-deriver.mjs's DEFAULT_BUDGET.input imports; #1380). The value is an INPUT CEILING the pre-dispatch estimate aborts on, never a spend and never a truncation — so the old default made a real corpus unrunnable rather than smaller: card bodies + steering alone estimate ~12k tokens in this repo, a consumer repo measured 11,158 (2026-09-10) and 30,262 (2026-09-18). Repos that already set budget-tokens explicitly are unaffected; repos on the default stop ending budget-exceeded. Docs, template and the --budget-tokens help text in the evolve skill (and its generated .agents/ / .codex-plugin/ copies) say "ceiling", not "budget".
  • The dialectic deriver's output contract is per-## -section, not a full-body replacement (agents/dialectic-deriver.md, the prompt in scripts/dialectic-deriver.mjs, skills/evolve/references/evolve-dialectic-mode.md; #1380). The merge has been section-wise since #1310 — but the agent was still told "emit the FULL replacement body … omitted sections are deleted", which invites an LLM to reproduce every hand-written managed section. The prompt now says omitted sections stay unchanged, and the anti-pattern list is corrected: an invented section is NOT rejected downstream (detectEmptying refuses only a proposal with zero content lines), so the instruction is to skip the target instead.
  • The backticked-citation checker now scans the rule corpora, and it blocks. scripts/lib/validate/check-skill-script-paths.mjs adds .claude/rules and .cursor/rules to SCAN_DIRS plus a MD_EXTENSIONS covering Cursor's .mdc (#1384). Both surfaces ship — .cursor/rules goes into the npm tarball and is symlinked into consumer repos — and neither had a gate; .cursor/rules/010-session-workflow.mdc kept citing commands/go.md and commands/close.md for a full release after 3ebf0e9d folded them into skills. Measured 2026-09-18: corpus 295 → 329 files, 4 blocking findings on the first run (all fixed in the same change, see Fixed). Because a rules file legitimately cites paths that only exist at runtime, a missing target is excused only when it is under a harness state root (.orchestrator/, .claude/, .codex/, .cursor/, .pi/) and git ignores it — one git check-ignore --stdin for the whole run, failing open toward REPORTING. The git half alone would have silenced a typo in a docs/specs/… or coverage/… citation forever. check-skill-links.mjs documents the resulting division of labour: links there, backticked citations here.
  • Three consolidated rule files now expire earlier — .claude/rules/measurement-discipline.md 2026-10-04 → 2026-10-02, .claude/rules/review-and-adapter-contracts.md 2026-10-04 → 2026-10-02, .claude/rules/test-hygiene.md 2026-10-20 → 2026-10-07 (#1382). Each header was outliving its own earliest absorbed learning, which the merge contract forbids (docs/rule-authoring.md § Consolidated rules); the body sentence expires-at <D> = the EARLIEST of the N absorbed dates was corrected with it. Consumers loading these rules lose them from injection sooner. Five folded provenance pairs across guard-design.md, identity-and-locks.md, review-and-adapter-contracts.md and test-hygiene.md are annotated markers only with the entry their substance was folded into, so all 7 consolidated files are 1:1 sweepable again rather than 3 of 7.
  • The expiry sweeper now RAISES a too-low rule header (scripts/lib/reconcile/rule-expiry-sweep.mjs, #1382): a frontmatter expires-at sitting EARLIER than the earliest absorbed date is lifted to it, as its own rewrite trigger (action: 'rewrite', reason: 'header-raise', visible in --dry-run --json before --apply) touching nothing but that line and the counter sentence. Left alone the file passes its header date with nothing expired, rule-loader.mjs stops injecting it, and the surviving provenance markers keep /reconcile treating its learnings as materialized — the substance goes dark and is never re-proposed. Measured 2026-09-18 on the live corpus: 3 of 7 files in that state (identity-and-locks → 2026-10-02, process-contracts → 2026-10-27, toolchain-and-build → 2026-10-16), ≈31.5 kB. The direction is one-way by contract: a header that OUTLIVES its content is still reported as an advisory only, because lowering on every run would cut a healthy entry's TTL short. Documented in docs/rule-authoring.md § point 2.
  • scripts/release.mjs's evaluateCiRow() names the CAUSE a CI preflight row went red (#1384): the degraded branch appends the probe's detail, the read branch falls back to details.reason when no failing job can be named. A short sha, a commit the mirror has never seen and a HEAD with no pipeline all printed the identical CI status unknown (query-failed) before. With neither field present the text is byte-identical to before.
  • scripts/lib/ci-status-banner.mjs clamps and control-byte-escapes every API-supplied fragment (reason, failingJobName, allowFailureJobs) at generation via sanitizeApiText(), 60 chars (#1384). The degraded branch has escaped since #1031; the READ branch interpolated a raw API status — a value carrying \r plus an ANSI sequence could repaint the release preflight's ci-green-on-head row green while its verdict stayed ok: false.
  • isUserInvocableValue(value, file, key) takes the frontmatter key it is judging and names THAT key in its WARN (scripts/lib/user-invocable-skills.mjs, #1384). It is also the normaliser for the sibling marker disable-model-invocation, and a disable-model-invocation: yes demotion reported user-invocable: "yes" — sending the operator to a line that does not exist in the file. scripts/generate-cursor-adapter.mjs now parses each SKILL.md once through a memoised skillFlags(): the predicate is not side-effect-free, so reading the same key from three call sites emitted the same WARN three times (measured on a two-skill fixture: 3 lines for 2 defects).
  • scripts/lib/validate-vendored-rules.mjs no longer validates README.md as a vendored rule — rules-sync.mjs vendors only the entries listed in _index.md (#1164). Six library rules under rules/ dropped ## See Also entries naming files the vendored corpus does not contain (development.md, security.md, testing.md, mvp-scope.md, cli-design.md).