feat(substrate): enforcement & stewardship — opt-in gate, dotfile learn-loop, verify timeout (Tranche C)#19
Merged
CodeWithJuber merged 1 commit intoJul 6, 2026
Conversation
…rn-loop, verify timeout (Tranche C)
Realizes the paper's mandatory-gate spine (Eq 5 / M2 "halt on insufficient
input") as an opt-in, and fixes two enforcement/stewardship gaps.
- Opt-in enforcing gate (FORGE_ENFORCE=1): the assumption gate can now BLOCK, not
just advise. On the ambient path it halts a prompt with no concrete anchor
("fix it") or an action into a very large predicted blast radius, returning the
clarifying questions. Low-false-positive by design (a specified task is never
blocked) and OFF by default. enforceDecision() in src/substrate.js; wired into
the preflight hook via a UserPromptSubmit block decision.
- Reconciled the two hook manifests: global/settings.template.json wired only
cortex.sh preflight (1 of 6 modes), so the dotfile install captured no events
and distilled no lessons — the learn loop was dead for those users. It now wires
all six modes (session-start/prompt/preflight/pre-edit/capture/stop) to match
hooks/hooks.json.
- forge verify can't hang: runTests is bounded by FORGE_VERIFY_TIMEOUT_MS
(default 10 min); a timeout is reported honestly, never as a pass.
Reversibility-via-auto-git-snapshot was assessed and deferred: auto git operations
inside a hook are too risky to enable by default; the enforcing gate + protect-paths
guard cover the safety limb without it.
218 tests pass (+3), typecheck + Biome clean, zero new runtime deps.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HGZUYFdUb4EViXV5tRid19
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Tranche C — the paper's mandatory-gate spine (Eq 5 / M2 "halt on insufficient input"), made
real but opt-in, plus two enforcement/stewardship fixes.
Opt-in enforcing gate (
FORGE_ENFORCE=1)The assumption gate has always been advisory ("never blocks"). This adds an opt-in mode where it
can halt: on the Claude Code ambient path it blocks a prompt with no concrete anchor at all
("fix it", "make it better") — or an action into a very large predicted blast radius — and
returns the clarifying questions via a
UserPromptSubmitblock decision. Low-false-positive bydesign: a specified task is never blocked. Off by default — behaviour is unchanged unless you
set the flag.
enforceDecision()insrc/substrate.js.Reconciled the two hook manifests (the dead learn-loop bug)
global/settings.template.json(the dotfile install) wired onlycortex.sh preflight— 1 of 6modes — so those users got the substrate advisory but never captured events or distilled
lessons: the entire Cortex learning loop was dead for them, while plugin users had it. The
template now wires all six modes (
session-start,prompt,preflight,pre-edit,capture,stop), matchinghooks/hooks.json.forge verifycan't hangrunTestsnow bounds the test run with a timeout (FORGE_VERIFY_TIMEOUT_MS, default 10 min); atimeout is reported honestly as "did not complete", never as a pass.
On reversibility (auto git-snapshot) — deliberately deferred
I assessed the "stage/rollback before a flagged edit" limb and chose not to auto-run git inside a
hook — auto git operations are too risky to enable by default and can interfere with the user's
own workflow. The enforcing gate + the existing
protect-pathsguard cover the safety limb withoutit; a
forge snapshot-style explicit command is a cleaner future home if wanted.Checklist
npm testpasses (Node 18/20/22) — 218 tests (+3)npm run checkpasses (Biome lint + format)enforceDecision: off / vacuous / specified / blast)feat:)CHANGELOG.mdupdated under## [Unreleased]FORGE_ENFORCE,FORGE_VERIFY_TIMEOUT_MSin GUIDE)Risk & rollback
change only adds the same hooks the plugin already runs; the verify timeout only bounds a hang.
FORGE_ENFORCEunset (feature inert).Extra checks
npm run typecheckpassessettings.template.jsonvalidated as JSON; all 6 cortex modes confirmed wiredVerification
Full suite + typecheck + Biome green.
enforceDecisionunit tests cover: off-by-default neverblocks; enforcing blocks a hard-underspecified prompt and a >threshold blast radius; a specified
task is never blocked. Manual: the reconciled template parses and now lists all six
cortex.shmodes.
Next: Tranche D (DX & evidence — uniform
--json, broaderdoctor, guard hardening,model_tiers,eval harness).
🤖 Generated with Claude Code
https://claude.ai/code/session_01HGZUYFdUb4EViXV5tRid19
Generated by Claude Code