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.
This commit is contained in:
1 parent
68a4d8b805
commit
19dfe7eb86
5 files changed
+107
-8
No files matched your search
+2
-1
@@ -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
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user