Author SHA1 Message Date
bchanot 19dfe7eb86 feat(doctrine): done and triage levers
Done = oracles green, reopened only on reproducible evidence; MINOR fold-or-drop, security never dropped; challenge skip for a placed user decision; contract dry run with run-base before dispatch; TODO loop on a frozen list; TODO +n / -m in the memory-commit report; verifier counts run artifacts in scope.
2026-11-20 15:06:52 +01:00
5 changed files with 107 additions and 8 deletions

No files matched your search

+2 -1
View File
@@ -113,7 +113,8 @@ code" wins. Repo-specific instructions override both.
- Once it qualifies: plan before code → one subtask = one coherent change
→ check off as you go → high-level note at each milestone. A plan a skill
persists (`.claude/tasks/plans/`, contract) satisfies the rule; TODO.md
then carries one line per run.
then carries one line per run. A TODO loop notes its start SHA in TODO.md,
runs that list + user adds; new items: report, run if one breaks its work.
## After code changes
1. Run tests, lint, build, type-check if available. Report what was
+9 -2
View File
@@ -101,8 +101,15 @@ Parse the single `FLOOR GUARD:` line:
## STEP 4 — SCOPE CHECK
List the files actually touched (`git diff --name-only` over `DIFF`).
Compare against the contract's `FILE SCOPE`. Report every out-of-scope
file. Disposition is NOT your call: the orchestrator treats each one as a
Compare against the contract's `FILE SCOPE` (`git diff --name-status`
plus untracked files). Run artifacts are in scope by default, whatever
`FILE SCOPE` says: a plan file the diff ADDS under `.claude/tasks/plans/`
or `docs/superpowers/plans/`; on an existing plan, appended
`MINOR dropped:` lines only; the CONTRACT you were handed, whole when
untracked or added, else only its `EVIDENCE:` lines, `- run-base:` line and
`[gated]` entries. Any other change to a plan or a contract stays out of
scope. Report every other out-of-scope file.
Disposition is NOT your call: the orchestrator treats each one as a
gap — the dev removes it or justifies it, and an accepted justification
only enters the contract through a human micro-gate.
+19 -3
View File
@@ -63,14 +63,30 @@ never a shell argument.
- `chore(memory): BLK-010 resolved — bugfix profile path`
- `chore(memory): journal — hotfix copy typo` (journal-only, nothing else)
Then, still before step 2, count the run's TODO movement as `<todo>`:
`TODO +n / -m`, the open TODO items the run added and removed (closed or
dropped); a reworded open item counts on both sides. `run_base` is a SHA,
never the gitflow base branch: the contract's `- run-base:` line
(`lib/verify-secure-loop.md` § BEFORE THE FIRST DISPATCH), else
`git rev-parse HEAD` now (shortcut: without a contract only the pending
TODO edits count; edits committed earlier in the run are missed). A
failing `git diff` → `TODO n/a`, never a silent `+0 / -0`.
if d=$(git diff --no-color --no-ext-diff "$run_base" \
-- ':/.claude/tasks/TODO.md' 2>/dev/null); then
n=$(printf '%s\n' "$d" | grep -c '^+ *- \[ \]')
m=$(printf '%s\n' "$d" | grep -c '^- *- \[ \]')
todo="TODO +$n / -$m"
else todo="TODO n/a"; fi
2. Commit surgically via the helper, capturing the memory-commit hash it prints:
mem_hash=$(bash "$HOME/.claude/lib/memory-commit.sh" commit "<message>")
rc=$?
3. Report by (rc, mem_hash):
- rc 0, mem_hash non-empty → `✅ mémoire committée <mem_hash>`
- rc 0, mem_hash empty → `CAPITALIZE: rien à committer` (helper no-op)
3. Report by (rc, mem_hash). Every report line ends with `· <todo>` (step 1):
- rc 0, mem_hash non-empty → `✅ mémoire committée <mem_hash> · <todo>`
- rc 0, mem_hash empty → `CAPITALIZE: rien à committer · <todo>` (helper no-op)
- rc 3 → unsafe git state (detached / merge in progress);
memory stays in the working tree for a manual
commit — surface the helper's stderr.
+25
View File
@@ -30,6 +30,27 @@ SOLID, synthesis is a no-op. It only costs more when a lens lands a real finding
The main loop's advisor call before the dispatch (below) is the costliest
single item: once per skill run.
## SKIP: a placed decision
A run that only places a decision the user already made skips this phase:
no challengers and no plan advisor call. Three conditions, all required:
the exact text or change is dictated by that decision (no new design); the
decision's text is the user's own words, or was challenged in the run that
wrote it; and the caller runs `lib/verify-secure-loop.md` after its
dispatch, so the gates still run. The test is whether the run settles an
open choice of its own (a mechanism, a condition, a threshold, wording the
user did not dictate), never code versus text; in doubt, challenge. The
skip is this include's own path (user decision 2026-11-20): a skill's
challenge step that reads this section runs as written, and the skip
discharges the plan point (`lib/effort-shift.md` § Advisor). The caller prints
`Challenge: skipped (placed decision: <the user's decision, date>)` in
place of its CHALLENGE SUMMARY.
Challenged or skipped: when the flow wrote a contract with `CHECK:` lines,
before the executor dispatch the main loop records `- run-base:` in the
contract and runs `gates.sh run` on a `mktemp -d` copy of it
(`lib/verify-secure-loop.md` § BEFORE THE FIRST DISPATCH).
## DISPATCH — three fresh challengers, in parallel, blind
**Advisor first (main loop).** Before the first dispatch, with no main-loop
@@ -88,6 +109,10 @@ Parse each `CHALLENGE — LENS: … — VERDICT:` line and merge the FINDINGS:
- **Severity-driven, not consensus.** Any `[BLOCKER]` from ANY single lens is
must-address — the lenses are orthogonal, so a lone security/rollback finding
is real, never outvoted by lens-count. Cross-lens agreement only RANKS the MINORs.
Each MINOR is folded into the plan now or dropped: a drop is one
`MINOR dropped: <finding>` line in the report and the plan file, nothing
in TODO.md or a registry; a security finding goes to the user
(`lib/verify-secure-loop.md` § MINOR triage).
- **RE-THINK the aspect the challenge pointed at.** For each BLOCKER (and each
MAJOR you accept): revise the plan on THAT aspect — a NAMED, diffable change to
the plan, never a self-authored "addressed" line. A BLOCKER you consciously keep
+52 -2
View File
@@ -1,6 +1,7 @@
# Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails, a11y)
Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes. Turns a
Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes (its first
section runs before the dev step is dispatched). Turns a
finished diff into a verified, security-cleared change through two fresh
gates and bounded loops. Loop decisions live here, in the main loop
(LRN-083: subagents = execution + report). The dev step is a dispatched
@@ -17,6 +18,26 @@ Nominal path is cheap — a free floor run, then
one verifier dispatch + one security dispatch, done. The loop only costs
more when it actually loops.
## BEFORE THE FIRST DISPATCH: contract dry run (main loop)
When the flow wrote a contract with `CHECK:` lines, the main loop does two
things before the dev step is dispatched:
1. Records the run's start commit in the contract header, once:
`- run-base: <git rev-parse HEAD>` (a SHA, never a branch name;
`lib/capitalize-commit.md` counts the run's TODO movement from it).
2. Copies the contract to a `mktemp -d` path and, from the project root,
runs `bash ~/.claude/lib/gates.sh run <copy>`, so the real ledger stays
`pending`. Expected: no `ERROR(n)` (malformed ledger: fix it here),
NOT-MET rows only where the work is not done yet, each failing for that
reason and not for a syntax error, a missing tool or a wrong path. A row
already MET is valid only when the work must keep it green (a suite, a
line cap); any other is vacuous. A marker that can never match fails
like undone work: for oracles that grep prose, apply the planned text
to a scratch copy of the repo and run the CHECKs there (LRN-296).
A bad oracle is fixed in the contract here, before any floor loop.
## GATE 0 — DETERMINISTIC FLOOR (no dispatch, no model)
Before spending a verifier dispatch, execute the oracles the contract itself
@@ -92,7 +113,8 @@ Parse its single `VERIFY — VERDICT:` line:
cannot fix unverifiability); do not spend a loop on it.
- Out-of-scope files: a dev justification is accepted ONLY through the human
micro-gate that appends `[gated <date>]` to the contract's FILE SCOPE;
otherwise the dev removes the file.
otherwise the dev removes the file. Run artifacts are in scope by
default (`agents/verifier.md`, STEP 4).
- Structural failure (`ERROR(…)`, missing/duplicated VERDICT line,
unparsable, crash, `CONFORME` without `PROOF` or without `FLOOR`) → retry
ONCE with a fresh verifier; a 2nd structural failure → human escalation.
@@ -147,3 +169,31 @@ verifier's verdict meaningless. REQUEST conformity is
always re-checked BEFORE security on any re-loop — a security fix that breaks
the feature must not slip through because only the security gate re-ran.
Never the reverse order.
## DONE: oracles green, reopened only on evidence
A run is done when its oracles are green: GATE 0 MET (the suite criterion
included), GATE 1 CONFORME and GATE 2 PASS on the same diff. After done, a
review (the end-of-run advisor call, a code review, a re-read) reopens the
run only with reproducible evidence: a command that fails on HEAD, or real
output shown wrong. A plausible scenario alone does not reopen the run:
the main loop tries once to turn it into a failing command, and if it
cannot, the finding is a MINOR (below). A behavioural claim ("agents obey
the rule") is done at its locks green, one live probe and one dated
measurement: a TODO line that carries the date and the tripwires that
would reopen it.
## MINOR triage: fold before dispatch, or drop
A MINOR finding on the run's plan or diff (from a challenger, a review, an
advisor) is either folded into the plan before the dispatch or dropped. No
fix round after the gates for a MINOR: it costs a full gate cycle. A drop
is one line, `MINOR dropped: <finding>`, in the run report and appended to
the run's plan file; nothing goes to TODO.md, BUGS-FOUND.md or any
registry. The backlog takes only findings with reproducible evidence, or
what the user asks for. Never a droppable MINOR: a security finding (a
GATE 2 `REPORTED` item, a secret, an injection, authorization or exposure
issue from any review) goes to the user, who decides fix or record.
Untouched by this triage: doc-syncer's `[MINOR]` patch class, the safety
guardrails, every gate, and the user's questions on visible, public-name
and scope choices.