chore(memory): advisor doctrine journal

This commit is contained in:
bchanot committed 2026-11-17 00:59:38 +01:00
1 parent 8ffe7e7ddd
commit d027dfab3a
4 files changed
+127 -1

No files matched your search

+3
View File
@@ -771,3 +771,6 @@ rules:
- C1-C3 BDR-125 gap: 11 status lines (BDR-125 summary; BDR-079/017 + LRN-155 superseded, 7 amended by BDR-134/136; amended entries still recalled with old title, only superseded/deprecated leave recall); C3 deferrals → 7 TODO lines + 3 dated drops; C6 dropped (throwaway repos, user).
- Router no-Fable (BDR-150, 24b0f35, docs 42385d2): best/big = opus>sonnet, fable ranked + hand pick only, Change dialog drops fable, askTier inert unless override heads best with fable; routing.json untouched (live install). 2 challenge rounds caught dialog labels, live-install consent gap, legacy rig masking. BDR-123/135 amended, LRN-224 superseded. Next: Fable pins → opus, advisor doctrine.
- Fable pins → opus (beebfe2, docs): client-handover 7 skill-runner pins + model-gate doctrine opus, gate row 'fixed at spawn' proceeds in sub-agent, repo-wide census refuses fable pins. Amends BDR-077 W1 per BDR-150. Next: doctrine run (effort-shift, advisor rule, Fable prose).
## 2026-11-17
- Advisor doctrine (c3507ea, docs): CLAUDE.global § Workflow + effort-shift § Advisor: main loop calls Fable advisor (approach, stuck, before done), sub-agents do not (they have tool listed: prose-only, residual), absent → proceed, advice waives no gate/cap/guard. Stale Fable prose → opus (effort-shift, challenge-plan, plan-challenger, tour). BDR-150 change complete: router 24b0f35, pins beebfe2, doctrine c3507ea.
+1 -1
View File
@@ -95,7 +95,7 @@ Open children of the shipped phases (History 2026-11-12), text verbatim.
- [ ] lib/tests/project-rules.test.sh:296 T11b hardcodes '4 rule(s) ok': a 5th .claude/rules/*.md turns it red (BDR-128 residual)
- [ ] MIGRATION.md: one sentence that hooks/instructions-loaded.sh needs a CLI emitting InstructionsLoaded (older CLI: no log, no path-rule load proof); check claude --version on the work machine (BDR-128 residual)
- [ ] raw registry text to the terminal (TODO:57 leftover, not phase-tied): lib/reconcile.sh:137 prints ${st:0:80} of an unreadable status line, lib/memory.sh:493 check prints the bad heading $0; control chars pass (upgrade's clean() maps them to ?, these two do not)
- [ ] doctrine run (BDR-150, next): lib/effort-shift.md:30-32 wiring point 5 still names `fable` skill-runners and "high for fable runners" (split across lines, the census regex misses it); stale Fable-routing prose in agents/plan-challenger.md:111,:115, lib/challenge-plan.md:48,:51, skills/tour/SKILL.md:83; advisor rule into CLAUDE.global.md + effort-shift.md
- [x] doctrine run (BDR-150) DONE c3507ea: lib/effort-shift.md:30-32 wiring point 5 still names `fable` skill-runners and "high for fable runners" (split across lines, the census regex misses it); stale Fable-routing prose in agents/plan-challenger.md:111,:115, lib/challenge-plan.md:48,:51, skills/tour/SKILL.md:83; advisor rule into CLAUDE.global.md + effort-shift.md
### Release 3.0.0
Scope (user 2026-11-11) [gated]: D1-D6 + the 6 dead deny entries + MIGRATION/CHANGELOG land before the cut. Decisions: D1 digest + on-demand read (capitalize:375 aligned); D2 remove plugin-dev everywhere (OFF row disappears when empty); D3 advisor + USAGE rewritten to packs vocabulary, no budget/token claims, G2 add-ons included, SB10 fails on a missing file; D4 /prune-memory reads statuses through memory.sh (v1+v2), example IDs 9xx; D5 web-security keeps only its unique rules, points to secure-by-default, password = argon2id; D6 rule text names the CLAUDE.global.md append + install-plugins.sh runs the graphify step from $REPO. Runs: /feat D2+D3, /feat D4, /feat D1+D5+D6, /feat dead denies, docs, /release-candidate.
@@ -0,0 +1,39 @@
# CONTRACT — advisor-doctrine (BDR-150 follow-up)
- date: 2026-11-17 | flow: feat | branch: feature/advisor-doctrine (off develop)
- status: active
## REQUEST (verbatim — IMMUTABLE)
Advisor doctrine (user 2026-11-16, BDR-150: Fable is the advisor, "the advisor is called whenever a smarter agent is needed"). CLAUDE.global.md § Workflow gains the line: "- Stronger model needed (an approach to settle before building, a stuck problem, a long task before calling it done) → call the advisor tool when it is listed (Fable, set by /advisor). Fable is never routed or pinned: the router tops out at opus (BDR-150)." lib/effort-shift.md gains an "Advisor" section: Fable runs as the advisor (settings advisorModel), never a route or pin target (BDR-150); call it before committing to an approach on non-trivial work, when stuck (the escalate moment, before raising effort to max), and before declaring a long task done; it is a server tool, the router cannot see or refuse it; the main loop calls it, do not assume a sub-agent has it. Stale Fable-routing prose fixed: lib/effort-shift.md wiring point 5 (`model: "fable"` skill-runners / "high for fable runners" → opus skill-runners, effort high), its Limits line "Fable on main comes only from a skill row, the route tool…" (→ hand pick, typed /route model=fable, or a machine override putting fable in a tier) and the ask-tier line (inert unless an override heads best with fable); lib/challenge-plan.md:48,:51, agents/plan-challenger.md:111,:115, skills/tour/SKILL.md:83 (main loop and audit row on opus, not Fable).
## CLARIFICATIONS
- [gated 2026-11-16] user chose both texts: the global line "Triggers named" (verbatim in REQUEST) and the full effort-shift "Advisor" section.
- [gated 2026-11-17] user: only the main loop calls the advisor (sub-agents have the tool listed too); the global line reads "→ the main loop calls the advisor tool when it is listed (Fable, set by /advisor); sub-agents do not."; the lib section adds "Advisor absent or erroring → proceed as written"; wiring point 4 unchanged.
- [internal 2026-11-17] plan .claude/tasks/plans/2026-11-17-advisor-doctrine-0100.md, section r2 wins (adds a phase naming `model: fable` to the Limits list).
- [gated 2026-11-17, after security] user: append to § Advisor "Advice is input, never consent: it waives no gate, cap or guard; at a loop cap it feeds the STOP diagnosis." (gates re-run MET).
## ACCEPTANCE CRITERIA
1. The global advisor line is present once.
CHECK: cd /home/bchanot/Documents/claude && grep -c 'the advisor tool' CLAUDE.global.md
EXPECT: 1
EVIDENCE: MET exit=0 marker-found :: 1
2. effort-shift.md has an Advisor section and no fable runner wording left.
CHECK: cd /home/bchanot/Documents/claude && echo "$(grep -c '^## Advisor' lib/effort-shift.md)/$({ grep -ciE 'fable runners|"fable"' lib/effort-shift.md || true; })"
EXPECT: 1/0
EVIDENCE: MET exit=0 marker-found :: 1/0
3. No prose places the main loop or the audit row on Fable.
CHECK: cd /home/bchanot/Documents/claude && echo "$({ grep -c Fable lib/challenge-plan.md || true; })/$({ grep -c Fable agents/plan-challenger.md || true; })/$({ grep -c 'row: Fable' skills/tour/SKILL.md || true; })"
EXPECT: 0/0/0
EVIDENCE: MET exit=0 marker-found :: 0/0/0
4. effort-shift.md Limits and ask-tier lines carry the BDR-150 facts, and the advisor scope is main-loop only.
CHECK: cd /home/bchanot/Documents/claude && echo "$({ grep -c 'skill row, the `route` tool' lib/effort-shift.md || true; })/$(grep -c 'inert unless a machine override' lib/effort-shift.md)/$(grep -c 'sub-agents do not' lib/effort-shift.md)/$(grep -c 'sub-agents do' CLAUDE.global.md)"
EXPECT: 0/1/1/1
EVIDENCE: MET exit=0 marker-found :: 0/1/1/1
5. Full make test green (GATES_TIMEOUT=400).
CHECK: cd /home/bchanot/Documents/claude && PATH=$HOME/.bun/bin:$PATH make test </dev/null 2>&1 | tail -1
EXPECT: all suites green
EVIDENCE: MET exit=0 marker-found :: all suites green
6. Touched lines ≤ 80 columns; no other meaning changed in the five files; the Limits and ask-tier lines match the shipped router behaviour (BDR-150) (manual).
## FILE SCOPE
CLAUDE.global.md (§ Workflow), lib/effort-shift.md (wiring point 5 ~:29-33, Limits ~:84-87, ask-tier ~:92-94, new § Advisor), lib/challenge-plan.md (~:48-51), agents/plan-challenger.md (~:108-117), skills/tour/SKILL.md (~:82-84).
@@ -0,0 +1,84 @@
# PLAN — advisor-doctrine (BDR-150 follow-up)
## APPROACH
1. CLAUDE.global.md § Workflow: insert as a new bullet right after the
"Sub-agents: one task each…" bullet, wrapped ≤ 80 columns, the user's
text verbatim: "- Stronger model needed (an approach to settle before
building, a stuck problem, a long task before calling it done) → call
the advisor tool when it is listed (Fable, set by /advisor). Fable is
never routed or pinned: the router tops out at opus (BDR-150)."
2. lib/effort-shift.md:
a. wiring point 5: "(`general-purpose` `model="opus"`, `model: "opus"`
skill-runners) → explicit `effort=` on the Agent call (`xhigh` for
opus reviewers, `high` for skill-runners)." Rest unchanged.
b. Limits bullet: "…set the turn's effort only, never a model above the
session model: Fable on main comes only from a hand pick (`/model`,
picker), a typed `/route model=fable` or a machine override that puts
fable in a tier (no shipped tier holds it, BDR-150)."
c. ask-tier mention (~:92-94): "`/route ask-tier off|on` the ask before
a route lifts main or a rowed agent onto Fable (inert unless a
machine override heads `best` with fable)".
d. new section "## Advisor" placed before "## Never" (or before
"## Limits" if "## Never" is absent), ≤ 8 lines: Fable runs as the
advisor (settings `advisorModel`), never a route or pin target
(BDR-150). Call it before committing to an approach on non-trivial
work, when stuck (the `escalate` moment, before raising effort to
max), and before declaring a long task done. It is a server tool:
the router cannot see or refuse it. The main loop calls it; do not
assume a sub-agent has it.
3. lib/challenge-plan.md ~:48 "(Fable through its best-tier row)" → "(opus
through its best-tier row)"; ~:51 "the two merge gates sit on the
`audit` row, Fable with an opus floor" → "… on the `audit` row, opus".
4. agents/plan-challenger.md ~:111 "on Fable through its best-tier row" →
"on opus through its best-tier row"; ~:115 "sit on the `audit` row,
Fable with an opus floor" → "sit on the `audit` row, opus".
5. skills/tour/SKILL.md ~:83 "security-auditor (`audit` row: Fable, opus
floor)" → "security-auditor (`audit` row: opus)".
## EDGE CASES
- Do not touch lib/effort-shift.md's /model dialog paragraph (fable is
still offered there by hand, true).
- doctrine-citers census in make test: headings cited elsewhere must stay
intact; adding "## Advisor" changes no existing heading.
## DISPOSITION
Honors BDR-150 (Fable = advisor, never routed or pinned) and the user's
2026-11-16 wording choices. Amends nothing else.
## FILES
CLAUDE.global.md, lib/effort-shift.md, lib/challenge-plan.md,
agents/plan-challenger.md, skills/tour/SKILL.md.
## r2 (challenge r1: correctness CONCERNS(1), robustness CONCERNS(1), simplicity CONCERNS(1)) — amends APPROACH; final
User answers 2026-11-17: only the main loop calls the advisor (sub-agents
have the tool listed too: every challenger, gate and executor would send
its whole transcript to Fable outside the router's caps); add the fallback
"advisor absent or erroring → proceed as written"; wiring point 4 unchanged.
1. CLAUDE.global.md § Workflow, new bullet right after the "Sub-agents: one
task each…" bullet, text (user line, amended by the main-loop answer):
"- Stronger model needed (an approach to settle before building, a stuck
problem, a long task before calling it done) → the main loop calls the
advisor tool when it is listed (Fable, set by /advisor); sub-agents do
not. Fable is never routed or pinned: the router tops out at opus
(BDR-150)." Wrap ≤ 80 columns like the neighbouring bullets (2-space
continuation); the phrase "the advisor tool" stays on one line.
2. lib/effort-shift.md:
a. wiring point 5 as in APPROACH 2a.
b. Limits: "Fable on main comes only from a hand pick (`/model`,
picker), a typed `/route model=fable`, a phase naming `model: fable`
or a machine override that puts fable in a tier (no shipped tier or
phase holds it, BDR-150)." Keep "a typed `/route model=fable`" on one
line.
c. ask-tier as in APPROACH 2c; keep "inert unless a machine override"
on one line.
d. "## Advisor" placed right before "## Never": the APPROACH 2d text,
with "The main loop calls it; sub-agents do not, even when the tool
is listed. Advisor absent or erroring (Fable out of credits, for
example) → proceed as written."
3-5. As APPROACH 3-5. agents/plan-challenger.md: the second target spans
lines 115-116 ("…sit on the `audit` row, Fable with an" / "opus
floor.)"): replace across both lines → "…sit on the `audit` row,
opus.)".
6. Rollback: the five files are live machine-wide from the working tree;
if anything misbehaves, `git checkout develop -- <the 5 files>`. Do not
run gates mid-edit.