Skip to content

feat: the end-to-end reliability layer — completion gate, session state, docs sweep, intent routing#47

Merged
CodeWithJuber merged 13 commits into
masterfrom
claude/forge-work-system-setup-p26ka5
Jul 10, 2026
Merged

feat: the end-to-end reliability layer — completion gate, session state, docs sweep, intent routing#47
CodeWithJuber merged 13 commits into
masterfrom
claude/forge-work-system-setup-p26ka5

Conversation

@CodeWithJuber

@CodeWithJuber CodeWithJuber commented Jul 10, 2026

Copy link
Copy Markdown
Owner

What & why

Implements the uploaded end-to-end reliability framework (claude-e2e-kit + FRAMEWORK/RESEARCH docs) natively in forgekit — every mechanism as a first-class feature, following forgekit idioms and math, so forge init and the plugin deliver the whole system to downstream repos. Kills the two failure modes the framework formalizes: partial work (code changes without the artifacts that depend on it) and session amnesia (the next session re-assumes what this one knew).

  • The completion gate (Stop) — src/gate.js + a synchronous completion-gate.sh guard: when a session tries to finish having changed code since its git baseline with no doc or state artifact moved, the stop is blocked once, with the repair checklist as the reason. Loop-safe (stop_hook_active + once-per-session marker), fail-open on every error path, FORGE_STOPGATE=0 kill switch. Classification derives from the atlas registries + the shared test-file predicate — no parallel regex lists. Full decision-table test matrix.
  • forge handoff — bounded session snapshot (.forge/state.md, rewritten ≤150 lines) re-injected at every session start; forge decide — append-only ADR-lite decision log + machine-readable ledger twin.
  • Session anchoring — SessionStart records the session's HEAD baseline (resume never moves it), prunes week-old session artifacts, and injects the snapshot + last 10 commits + uncommitted changes.
  • forge docs sync — the diff-driven docs sweep: changed identifiers (added AND removed lines) scanned against every doc artifact → UPDATED / STALE (file:line hits) / VERIFIED-UNAFFECTED with the reason recorded. Dogfooded on this very branch — which caught and fixed a prose-parenthesis false-positive class.
  • Intent protocol cards — prompt intent via the same exemplar k-NN math as model routing (labeled bank incl. Hinglish rows + confidence gate, NOT a keyword DFA); bugfix/feature/refactor/release cards injected once per run; questions get no ceremony. FORGE_INTENT=0 kill switch.
  • Recorded assumptions + CUSUM drift — preflight records the assumptions it proceeds under and the per-prompt goal-drift score; sustained drift (CUSUM, previously test-only math) rides the gate's block reason; assumptions surface in the next handoff.
  • Config artifacts in the atlas — CI workflows, manifests, Dockerfiles become graph nodes, so forge impact lists the configs a change can break.
  • Instructions layer — end-to-end rules section compiled to every tool by forge sync; handoff/sync-docs/catchup skills; doc-sync crew agent.
  • Fix — cortex.sh entry resolution silently no-opped every cortex hook in symlink (non-plugin) installs; both shims now resolve through the symlink (pwd -P).

Checklist

  • npm test passes (Node 18/20/22) — 594 tests, 592 pass / 2 skipped, 49 new
  • npm run check passes (Biome lint + format)
  • New public functions have a test
  • Conventional commit message (feat:/fix:/docs: …)
  • CHANGELOG.md updated under ## [Unreleased]
  • No new runtime dependency (dev deps ok)
  • Substrate/docs updated if this changes forge substrate, forge impact, router/gate, or MCP substrate tools — GUIDE (gate decision table, three new command sections, env rows), ARCHITECTURE §5, README; forge docs check passes on this tree

Risk & rollback

  • Risk level: medium — this is the first Stop hook allowed to block. Mitigations: block-at-most-once marker, stop_hook_active loop protection, fail-open on every error path (garbage stdin / no git / missing baseline / internal errors all allow — each has a test), FORGE_STOPGATE=0 kill switch, test-only changes never block.
  • Rollback plan: revert the branch commits; or operationally set FORGE_STOPGATE=0 / remove the completion-gate.sh entry from the Stop arrays of hooks/hooks.json + global/settings.template.json to disable just the gate.

Extra checks (tick if applicable)

  • npm run typecheck passes
  • Input validated at boundaries; errors handled (no swallowing) — hooks are deliberately fail-open by contract; refusal paths (secrets, empty input) return typed reasons
  • Authorization/ownership checked (if it touches access) — n/a
  • Logs contain no secrets/PII — handoff/decide/ledger refuse secret-shaped content at write; test fixtures runtime-assembled
  • If AI-assisted: I understand it, verified the package APIs, and it has tests

🤖 Generated with Claude Code

https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2

Generated by Claude Code

claude added 13 commits July 10, 2026 08:18
@claude
feat(atlas): config artifacts join the impact graph
3de9257 
CI workflows (.github is now walked), manifests, and Dockerfiles become
config: nodes with references edges to the code paths they name — a code
change now lists the configs it can break. Lockfiles stay out (generated
churn). RULES/DOC_EXTS/CODE_EXTS/CONFIG_* are exported as the ONE
classification registry the completion gate and docs sweep reuse.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
feat(memory): forge handoff + forge decide — state that survives sess…
7292636 
…ions

handoff rewrites .forge/state.md (bounded ≤150 lines: goal/phase, criteria,
done, next, gotchas, recorded assumptions, in-progress git files) — snapshot
semantics, injected at every session start so the next session resumes
instead of re-assuming. decide appends ADR-lite D-#### entries to
.forge/decisions.md (log semantics — supersede, never edit) and mints a
machine-readable decision ledger twin. Both refuse secrets at write.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
feat(session): git baseline anchoring + rehydration + artifact pruning
8cfb49f 
SessionStart records HEAD once per session (.forge/sessions/<sid>.base —
a resume never moves the anchor), prunes week-old session artifacts, and
the rehydration block carries recent commits + uncommitted changes so a
fresh session orients on evidence. sessionPath() becomes the one naming
rule for every per-session artifact (log, baseline, marker, intent).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
feat(docs): forge docs sync — the diff-driven stale-docs sweep
4f91902 
docs check reconciles registries; docs sync answers the diff-shaped
question: changed identifiers (paths + definitions + called symbols, from
added AND removed lines, via the same RULES grammars the atlas parses)
swept against every doc artifact → UPDATED / STALE (file:line hits) /
VERIFIED-UNAFFECTED with the reason recorded. Advisory by default,
--strict for CI, --base <ref> to widen. CHANGELOG + decisions.md exempt
(append-only history). Symbols come only from non-test code files and
only code-shaped names scan — dogfooding on this very branch caught the
prose-parenthesis false-positive class.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
feat(gate): the completion gate — a deterministic floor under 'done'
8648afd 
A synchronous Stop guard (the detached cortex.sh stop can never answer)
blocks a session ONCE when code changed since the session baseline but no
doc or state artifact moved with it — the reason IS the repair checklist
(forge docs sync / handoff / decide + CUSUM drift alarm). Loop-safe
(stop_hook_active + once-per-session marker), fail-open on every error
path, FORGE_STOPGATE=0 kill switch. Classification derives from the atlas
registries + shared isTestFile — no parallel regex lists. state.md is
gitignored, so its signal is mtime-vs-baseline. Registered in both hook
manifests (plugin + init template, lockstep-tested).

Also fixes cortex.sh entry resolution in symlink installs: ~/.forge/src/…
pointed at the nonexistent global/src/, silently no-opping every cortex
hook outside plugin mode — both shims now resolve through the symlink
(pwd -P), same as secret-redact.sh.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
feat(intent): protocol cards routed by exemplar k-NN, not a keyword DFA
b803d3e 
The prompt is classified by the same math as model routing — a labeled
bank (English + Hinglish rows) under overlap similarity with a confidence
gate. Work intents (bugfix/feature/refactor/release) inject a ~6-line
protocol card once per run of that intent; questions get no ceremony,
below-confidence prompts get nothing. intentGrams deliberately differs
from route's contentGrams: generic task verbs are complexity noise but
exactly the intent signal — same math, different stop-set data.
FORGE_INTENT=0 kill switch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
feat(evidence): recorded assumptions + goal-drift series wire the loop
fb21987 
Preflight now RECORDS what it only displayed: once a goal is anchored,
every prompt appends its graded driftScore to the session log (cusum —
until now test-only math — accumulates the series and a sustained alarm
rides the gate's block reason); proceeding under assumptions appends a
record the advisory names and the next handoff surfaces. A guess can
never silently become a fact. Hook entrypoint gains the stop-gate mode
and the session-start baseline + snapshot + rehydration injection.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
feat(instructions): end-to-end rules, three skills, and a doc-sync agent
081b3b5 
source/rules.json gains an end-to-end section (Definition of Done, no
silent assumptions, decision log) that forge sync compiles into every
tool. New skills — handoff, sync-docs, catchup — teach the workflow; the
doc-sync crew agent repairs stale docs in its own context (never code)
and joins the plugin agents list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
docs: document the end-to-end reliability layer everywhere it lands
b85e904 
CLI dispatch + command registry for handoff/decide/docs-sync; README
command rows + feature bullet; GUIDE sections (handoff, decide, docs
sync, the completion-gate decision table, env rows FORGE_STOPGATE +
FORGE_INTENT); ARCHITECTURE §5 (the reliability layer, incl. the
deliberate checkpointCadence deferral); CHANGELOG [Unreleased] entries;
CLAUDE.md test count. forge docs check passes on this tree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
fix(gate,memory,docs): harden per two-angle adversarial review — 12 v…
2d78515 
…erified defects

Gate: the changed set is now SESSION-SCOPED — files from commits with
committer time >= session start plus worktree changes minus the dirt
snapshotted at SessionStart — so pre-existing edits, branch switches, and
git pulls are never pinned on the agent (three demonstrated false-block
classes). All git parsing moved to -z NUL output (C-quoted unicode/space/
arrow paths classified correctly). The block-once marker is written BEFORE
blocking and an unwritable marker stands down instead of nagging every
turn; a missing session_id disables gating (no shared 'default' state);
SessionStart prunes BEFORE anchoring so a >7-day resume re-anchors instead
of losing its baseline; vendor trees never enter the changed set.

Memory: readState no longer truncates at a '<!--' inside snapshot rows
(only the exact provenance line is stripped); forge decide takes an atomic
mkdir lock so concurrent appends can't mint duplicate D-#### ids or
interleave headers, and a failed append reports instead of half-succeeds;
recorded assumptions dedupe and cap before entering the bounded snapshot.

Docs sweep: .forge/state.md left the scanned set (handoff writes changed
paths into it by design — scanning it was an unfixable self-reference);
docs touched in the diff still answer for REMOVED symbols (the rename
case); all-lowercase symbols count only inside backtick code spans; an
unknown --base errors instead of silently diffing the index.

Every fix carries a regression test (605 total, 0 failures).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
fix(types): changedSet options need explicit JSDoc for tsc
e03ce50 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@claude
Merge remote-tracking branch 'origin/master' into claude/forge-work-s…
5c271c8 
…ystem-setup-p26ka5
@claude
chore(changelog): keep unreleased work out of the v0.9.0 section afte…
1fa7834 
…r merge

The v0.9.0 rotation on master renamed the [Unreleased] header this branch's
entries sat under, so the textual merge filed unshipped work as released.
Moved this branch's Added/Fixed entries back under [Unreleased]; [0.9.0]
now lists exactly what the tag shipped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2
@CodeWithJuber CodeWithJuber marked this pull request as ready for review July 10, 2026 09:54
@CodeWithJuber CodeWithJuber merged commit 4d0a399 into master Jul 10, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@CodeWithJuber @claude