From ec7c29938bcf0ae41f87f529bbabd051e009ec82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabor=20K=C3=B6rber?= Date: Thu, 15 Oct 2026 22:01:49 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20grotto=20orientation=20bas?= =?UTF-8?q?eline=20report=20and=20session=20journal?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude --- .../journals/2026-10-15-21-grotto-work.md | 34 +++ ...26-10-15-21-grotto-orientation-baseline.md | 266 ++++++++++++++++++ 2 files changed, 300 insertions(+) create mode 100644 docs/workpad/journals/2026-10-15-21-grotto-work.md create mode 100644 docs/workpad/reports/2026-10-15-21-grotto-orientation-baseline.md diff --git a/docs/workpad/journals/2026-10-15-21-grotto-work.md b/docs/workpad/journals/2026-10-15-21-grotto-work.md new file mode 100644 index 0000000..e200405 --- /dev/null +++ b/docs/workpad/journals/2026-10-15-21-grotto-work.md @@ -0,0 +1,34 @@ +# Grotto work — Igor Session Journal + +**Date**: 2026-10-15 +**Topic**: grotto work +**Worktree/branch**: main (no worktree) + +## Log + + + +- 21:23 — Session start. Adept roster empty (no `adepts/` folder). No "grotto" mention found in repo `.md` files by a quick grep. +- 21:25 — User feedback (first field reports of the new Athanor on a Python project): build went well. Gap: the placeholder planner (non-grotto Spire stand-in) missed a constraint documented in the project's CLAUDE files; the superpowers plan writer caught it, arguably by luck (different cat command surfaced a hint), and the planner planned in an illegal feature. User's ideas, as proposals not decisions: + - A small systematic orientation probe before design/plan: look where the design would land, gather local project docs. + - Alternatively/additionally: make the attacker read more around the project (its job is mostly ingesting). + - Human analogy: look up local docs; if the task feels overwhelming, look for similar implementations; working on a serializer's reader → skim the writer's docs. Done as a dedicated, separate step with notes kept apart. Return to those notes after the plan, or during it when stuck / facing unknowns. + - User asked Igor to read up on the topic before ingesting their words. +- 21:26 — Dispatched orientation research (see Artifacts) to establish what "grotto" is and how planner/attacker/design orient today. +- 21:26 — User: the grotto data hasn't been committed yet. Stopped the orientation research before it wrote a report (none on disk). Waiting for the user's incoming files. +- 21:3x — Pulled. Local main had diverged from origin (local a039478 Dirigent reports vs. remote 8028411 planning research), so I rebased the local commit onto origin (now b881162). It's not pushed. 13 new workpad files: goals (drop-superpowers-0.2.2, lean-athanor-0.2.1), brainstorm, journal, Fable opinion report, Dirigent reports, 4 research docs. +- Re-dispatched the orientation research (researcher, model: opus) over the new files → reports/2026-10-15-21-grotto-orientation-baseline.md. +- Report back: reports/2026-10-15-21-grotto-orientation-baseline.md (stamped claude-opus-5-5). Grotto exists only as decisions in goals/drop-superpowers-0.2.2.md, with no code yet. No planning role reads project docs systematically. Hypothesis: nested CLAUDE.md files load lazily (only when a path under them is touched), so the planner sees constraints only along the paths it happens to open. That would make the superpowers "luck" structural. Superpowers itself has one checklist line for this. The report lists 7 placement options and gives no verdict. Unverified: the details of the Python project, superpowers v7, and whether nested CLAUDE.md files load in subagents. +- User: the one superpowers sentence ("Explore project context — check files, docs, recent commits") may be load-bearing. The 0.2.2 session found that single sentences steer Opus 5.5 more than expected. There's precedent: a misread sentence contributed to the chatgpt-importer blow-up (counted under "even 0.2.0 athanor had issues"). An experiment is running in the other project, comparing plan + implementation from Spire 0.2.2 against superpowers. Igor's observation, a hypothesis not a decision: the planner's one orientation line says "Read the code the plan touches", which names code and not docs. That may actively narrow attention, so the gap could be the wording rather than a missing stage. + +## Adepts + +- Roster empty at boot. No adepts relevant yet. + +## Artifacts + +- docs/workpad/reports/2026-10-15-21-grotto-orientation-baseline.md — orientation baseline for grotto (what exists, how roles orient, placement options) + +## Open threads + +## Graduation candidates diff --git a/docs/workpad/reports/2026-10-15-21-grotto-orientation-baseline.md b/docs/workpad/reports/2026-10-15-21-grotto-orientation-baseline.md new file mode 100644 index 0000000..5600114 --- /dev/null +++ b/docs/workpad/reports/2026-10-15-21-grotto-orientation-baseline.md @@ -0,0 +1,266 @@ +# Grotto orientation baseline: how Spire's planning roles read a target project today + +**Date**: 2026-10-15 (21:33 from `date`) +**Model**: Opus 5.5, model id `claude-opus-5-5` (from my system prompt) +**Method**: read-only. I read all the material named in the brief, the Spire role agents (`planner`, `attacker`, `reviewer`, `athanor`, `adept`), `skills/implementation/**`, `skills/igor/SKILL.md`, `skills/project`, `skills/knowledge`, `skills/init` and the 2026-09-22 cycle design. I grepped the whole repo for "grotto" and searched git history (`--grep` and `-S`). I also read the locally cached superpowers 6.4.1 `brainstorming` and `writing-plans` (`~/.claude/plugins/cache/claude-plugins-official/superpowers/6.4.1/skills/`). No web fetches and no agents. This report is the only file I wrote. +**Register**: this report gives findings and options only. The user decides. +**Naming**: `docs/workpad/CLAUDE.md` does not exist. I followed the `workpad` skill (`plugins/spire/skills/workpad/SKILL.md:72`, `YYYY-MM-DD-hh-.md` in `reports/`), which matches the path in the brief. + +--- + +## Summary + +1. **Grotto** is a plugin that has been named but not built. No code, no directory and no commit message mention it. The settled points are: it is its own plugin, it works standalone, its storage location is the user's to define, it carries the design / plan / handoff procedure, and it is the input to Spire 0.3.0. Everything else is listed under "Later". +2. **No Spire planning role reads project docs systematically.** The planner's whole orientation rule is "Read the code the plan touches". The attacker and the reviewer read "the code as it is now". None of the three mentions `CLAUDE.md`, conventions or neighbouring code. A systematic fallback procedure does exist (`spire:knowledge`: glob `**/CLAUDE.md`, follow links, read topic docs), but no role agent preloads it. +3. **Why the field failure fits this setup.** Claude Code loads a nested `CLAUDE.md` only when a file under its directory is touched. Ancestor files load at start. So a planner sees exactly the constraint files that sit on the paths it happens to open. That matches the user's "a different cat command surfaced the hint". This is a hypothesis: I did not see the Python project. +4. **Superpowers is no more systematic.** Its context gathering is one checklist line ("Explore project context — check files, docs, recent commits") plus "follow existing patterns". Its catch in the field looks like generic exploration that happened to touch the right path, not a dedicated step. +5. **The new docs touch both options without deciding either.** They also contain several tensions an orientation probe would have to handle: drift, cost per stage, "a reviewer handed a checklist confirms the checklist", and the conditional attack. The word "orientation" is already taken by the user's Step 2 "Architectural Orientation", which is a different thing. + +--- + +## 1. What grotto is + +### Status + +- **Not built.** `plugins/` has no `grotto/`. The marketplace has no entry. `git log --all -i --grep=grotto` is empty. `git log -S grotto` hits only `8028411` ("📝 Document Spire planning research and 0.2.2 decisions", the workpad docs). All mentions are in workpad markdown: the 0.2.2 goal, two journals and the tasks research. +- The name was settled in the 10-15 morning session: `journals/2026-10-15-11-superpowers-opus55-era.md:48` "USER DECISION: plugin name is **grotto**". It went through batcave, belfry and undercroft first (`:167-170`). + +### Decisions already taken (all from the user, 2026-10-15) + +From `goals/drop-superpowers-0.2.2.md` §Decided (lines 54-60) and the journal: + +- **Own plugin, standalone-capable.** "The design / plan / handoff procedure becomes its **own plugin**, so Spire doesn't get overblown. It works standalone too (storage location then defined by the user); most of the time it runs with Spire, and a project may have Spire without it." (goal :59; journal :49-50) +- **Relation to Spire.** "0.3.0 — Spire adopts the `grotto` plugin's design / plan / handoff procedure" (goal :6). "The full procedure is grotto / 0.3.0" (:12). +- **Name rationale.** "a cave — the batcave without Batman: no superpowers; where Igor fetches the plans" (:60). +- **Positions it inherits:** "Designs and plans are transitional; code is truth. A design is not a spec." (:58) Grilling belongs to the brainstorm, not to design (:56). Where ADRs live is a per-project decision (:57). +- **Fable's advice was overruled.** Fable argued for "inside Spire, and start as references, not skills … Extract to a plugin never" (`reports/2026-10-15-13-fable-opinion-superpowers-direction.md:29`). The user decided the opposite at 13:35. + +### Intended scope (the goal's "Later" list, not yet decided in detail) + +`goals/drop-superpowers-0.2.2.md:63-67`: +- "Guidance for: writing a design, writing a plan, keeping handoffs and journals (general and harness-specific)." +- "Drift (two-way, incl. positive drift) and audience per artifact as known forces — not fixed rules." +- "Retrospectives from the lean Athanor runs feed grotto's refinement." The user pushed back on Fable here: the problems also hit the lean Athanor (journal :51). +- "May take several iterations." + +### Inputs queued for grotto + +- The user's brainstorm `brainstorm/2026-11-15-implementation_thoughts.md` (goal :51, box still open). Its four steps are Design, Architectural Orientation, Plan and Attack. Fable notes the filename says November; the content dates from 10-15. +- Matt Pocock's skills, grilling especially (goal :50, open). +- The plan-anatomy lean skeleton (`research/2026-10-15-12-superpowers-plan-anatomy.md` §4), marked "PROPOSAL … not a decision". +- From the tasks research (`research/2026-10-15-14-claude-code-tasks-and-pcvelz.md:14, 161-188`): native Tasks are "at best a **complement**, never the handoff substrate". Option A ("Format only": Goal/Files/AC/Verify plus `blockedBy`, with a status line per task in the handoff) is framed as the user's call. +- The Dirigent reports (`reports/dirigent/README.md`). +- Today's journal `journals/2026-10-15-21-grotto-work.md:12-15` records the field report and options (a) and (b) "as proposals not decisions". + +--- + +## 2. How each stage orients on a target project today + +### Planner (stage 4), `plugins/spire/agents/planner.md` + +- Its only orientation rule (:20): "Read the code the plan touches before you write it. If earlier phases already landed, plan against the code as it is now, not as the design imagined it." +- Preloaded skills (:9-12): `spire:project`, `spire:workpad`, `spire:implementation`. Not `spire:knowledge`. +- No self-check. Its final message (:35) returns the path, the phases and the `**Assumed:**` points. +- Igor's brief: `igor/SKILL.md:99` says "(4) Plan — the `planner` … produces steps with completion criteria, at the plan altitude in `spire:implementation`." `model-tiers.md:11` says "Reads the code". Neither says anything about project docs. + +### Attacker (stage 4b), `plugins/spire/agents/attacker.md` + +- (:22) "Test the plan adversarially against the code as it is now". It checks for blockers, design errors, wrong root causes, missed consumers, staleness and missing function (:24-28). +- Its "blockers" are defined against code: "things the plan assumes that the code does not allow" (:24). Documented project rules (policy, product rules, "never do X") are not named as a source. +- Same three preloaded skills. `implementation/SKILL.md:26-34` restates the same scope. + +### Reviewer (stage 6), `plugins/spire/agents/reviewer.md` + +- (:24) "The attack's risk list is not your scope. Look where the code tells you to." +- It runs gates, traces scenarios, answers every handoff flag, hunts weakened checks and tests that cannot fail, and lists unplanned work (:19-23). It has no check against project docs or conventions. + +### Design (stage 3) + +- There is no design agent. `igor/SKILL.md:99` says: "(3) Design — independent Opus agent produces one buildable approach." The cycle design (`designs/2026-09-22-development-cycle.md:27`) gives the inputs as "goal + research". No orientation instruction exists. The coupling research confirms: "Spire defines no content for a design" (`research/2026-10-15-11-spire-superpowers-coupling.md:74`). + +### Athanor (stage 5), for comparison + +- `agents/athanor.md:23`: "Project-specific knowledge is loaded by the `spire:project` skill at agent startup. Read it before intake. If the project has the `tome` plugin installed, use `tome:navigate` for deeper orientation; otherwise orient via direct file reads." +- Intake (:31): "Read the build plan, the run log so far, and the code the phase touches. That reading is your trunk." Trunk notes are written next to the run log. This is the closest Spire analogue to "notes kept apart", but it happens at build time, after the plan is fixed. + +### `spire:implementation` and its references + +- `SKILL.md` contains no `CLAUDE.md`, "conventions" or "project docs" (grep over `skills/implementation`, `planner.md`, `attacker.md` and `reviewer.md` returns nothing). +- The one "look around" rule is for bugs only (:63): "**Explore before you focus.** Look one or two layers up from the symptom, skim recent commits in the area, check where the same pattern recurs". This is close to the user's "similar implementations", but scoped to debugging. +- Project settings (:82) include "standing brief constraints for sensitive areas". The `## Build` template has a `**Brief constraints**` field: "sensitive areas, e.g. generated files, migrations" (`igor/references/project.md:33`). This is a manual, curated channel for constraints, filled only if the user writes them in. +- `references/models.md`, `run-log.md`, `spawning-claude-code.md` and `superpowers.md` say nothing about orienting on project docs. + +### Mechanisms that exist but are not wired to the planning roles + +- **`spire:knowledge` fallback** (`skills/knowledge/SKILL.md:32-41`) is close to the probe the user describes: "1. Read the root CLAUDE.md / AGENTS.md … 2. Follow @-includes and links … 3. Check for module-level CLAUDE.md … 4. Use `find` or `glob` for `**/CLAUDE.md` to discover what documentation exists 5. Read topic docs". It names "Igor, adepts, athanor" as its audience (:11). No agent lists it in `skills:`. +- **Igor's setup** (`igor/SKILL.md:185`): "Skim the project's architecture entry point (`project.md` names it; otherwise the root CLAUDE.md/AGENTS.md) so you can catch misconceptions later." That is the root only, read by Igor, and not passed on to the planner. +- **Adept genesis** (`agents/adept.md:50-55`) is a full orientation probe for one domain. It orients via the knowledge skill or direct reads, writes `key-files.md` plus optional `conventions.md`, `architecture.md` and `gotchas.md`, and keeps a genesis journal with an "orientation trace". Adepts are separate notes, revisited on consultation, with a drift check (`:70`). The planner and attacker are leaves and do not consult adepts. Only Igor would relay. + +### How `CLAUDE.md` reaches a subagent (harness behaviour, from repo evidence) + +- "ancestors load eagerly, descendants load lazily when files in them are read" (`reports/2026-05-11-17-skill-engines-cross-tool.md:79`). +- Confirmed in Spire's fact-check, including for Bash access: "running `ls plugins/spire/agents/` caused the harness to inject `plugins/spire/CLAUDE.md`" (`reports/2026-09-18-adept-discovery-factcheck.md:13`). +- Observed in this session: as a subagent I received the repo-root `CLAUDE.md` at start, and `plugins/spire/CLAUDE.md` did not appear in my context while I read files under `plugins/spire/` with Read and Bash. I list this as an observation and did not test it further. It means the lazy loading is not fully predictable either. + +### Where this falls short for the field failure + +Assume the constraint sat in a non-root `CLAUDE.md` or a doc it links to (the user said "CLAUDE files", plural). Then: +- The planner loads it only if it touches a file under that directory. "Read the code the plan touches" means the plan's own guess about where it lands decides what constraints it sees. A feature that is illegal *because* of a rule documented elsewhere (in a sibling module, a parent area, or a `docs/` page that a `CLAUDE.md` links to) is invisible by construction. +- The attacker has the same blind spot. It tests against "the code", and a documented policy is not a code fact that "the code does not allow". It may load the same nested file by luck, in the same way. +- The reviewer comes after the build. By then the illegal feature exists, and "Look where the code tells you to" does not point at policy docs. +- The builders might trip over the nested file while editing. Under the closed-door rule they would take the "conservative default, flag it" (`implementation/SKILL.md:42`), which is too late to un-plan a feature. +- Unknown: whether the constraint was in the root `CLAUDE.md`. If it was, the planner had it in context and the failure is attention rather than access. A probe would then help mainly by turning the rule into an explicit checklist line. I could not tell which case it was. + +--- + +## 3. What the new docs say about context gathering before planning, and how superpowers does it + +### Superpowers (local 6.4.1 cache, plus the plan-anatomy research for v7) + +- `brainstorming/SKILL.md:116, 123, 130`: step 1 of every path (spike, bounded, architectural) is "**Explore project context** — check files, docs, recent commits". At :201: "Check out the current project state first (files, docs, recent commits)". At :233: "Explore the current structure before proposing changes. Follow existing patterns." The HARD-GATE allows "Read-only project exploration" before approval (:54-55). +- `writing-plans/SKILL.md:24-32`, **File Structure**: "Before defining tasks, map out which files will be created or modified … In existing codebases, follow established patterns." The executor is told about "docs they might need to check" (:10). +- **Global Constraints** (`writing-plans` :70-75) are copied "verbatim from the spec". Constraints flow design → plan → every task brief. The plan-anatomy research gives the rationale: constraints get lost in per-task briefs, and the section measured "0/5→5/5" plus "a `go 1.26.1` floor violation shipped because none did" (`research/2026-10-15-12-superpowers-plan-anatomy.md:46, 89`). The catch: Global Constraints holds only what the *spec* captured. Project-doc rules enter only if brainstorming's exploration found them. +- **Read**: superpowers has no dedicated project-doc probe and never names `CLAUDE.md`. Its gathering is one unstructured instruction at brainstorm time plus the harness auto-load. That fits the user's "seemingly by luck". +- **Gap**: the plan-anatomy research cites v7.0.0 brainstorming (rebuilt, intent-level design, `sp:skills/brainstorming/SKILL.md:145-154`). The `/tmp/sp-research/` clones are gone, so I could only check 6.4.1 directly. Whether v7 kept "Explore project context" unchanged is unverified. + +### Matt Pocock (from `research/2026-10-15-11-superpowers-alternatives.md`) + +- `grilling`: "Finding *facts* is your job, never the user's", with sub-agents dispatched for lookups (:126). +- `domain-modeling`: challenge terms against `GLOSSARY.md` and "cross-check claims against code" (:131). +- `code-review` has a **Standards** sub-agent that reads "repo docs plus a Fowler smell baseline, where 'the repo overrides'" (:147). This is a project-docs check, placed at review time. +- `retro` suggests changes to "steering files" after a session (:150). That is a path for feeding a missed constraint back into project docs. + +### Dirigent reports + +- **A plan that broke a project rule, caught by an adversarial pass.** "Plan A (4.6) misidentified the H0 root cause … That is a silent break of the archive backward-compatibility rule" (`reports/dirigent/2026-10-01-lean-process-report.md:199`). It was caught by the plan comparison, "the cheapest quality gate of the day" (:223; step described as "adversarial against the code", :239). This is the closest precedent to the field failure, and here the attack-like step caught it. +- **Project rules need an injection point.** "projects need a place for **standing brief constraints**, injected into every brief whose scope touches a given area" (:481), derived from the archive-compat memory note. This is the origin of the `## Build` `Brief constraints` field. +- **Consumers are discovered in a distributed way.** "Plans list every consumer of a changed semantic, not only the files that change" (:231). Addendum A.1 adds "The plan seeds the list, each block greps the consumers of its own change … and the end review checks the list" (:275). +- **The attack can be skipped.** "It is redundant when the plan was written by Opus 5.5 in the same session, after research that traced the code paths the plan changes" (:273). A drift check against a recorded plan-base commit replaces it. This is Dirigent's process; in Spire the attack is still a fixed stage (`igor/SKILL.md:99`), and `implementation/SKILL.md:12` lets one-go work skip the cycle. +- **CLAUDE.md files carry project rules.** The importer design honoured "the CLAUDE.md archive refinement: never silently lose archived data" (`reports/dirigent/2026-10-14-chatgpt-importer-retrospective.md:216, 250`). The lean finish makes crate `CLAUDE.md` files "20–50 line navigation maps … API detail goes to trunk notes or `docs/`, never into `CLAUDE.md`" (`reports/dirigent/2026-10-15-chatgpt-importer-handoff-lean-finish.md:22`, rule 8). So in Dirigent, rules may sit one link away from `CLAUDE.md`, in `docs/architecture/…`. A probe that reads only `CLAUDE.md` files and does not follow links would miss them. +- **Pre-build cost.** Pre-build docs took about 19% of active time (retrospective :177). For builds that size, the policy is: "Skip design + plan + attack when research already names the format and the seams. Write one combined design-plan of 100–150 lines instead" (:258). + +### Reliquary research and opinion + +- Coupling research gap list: "**What the planner must verify in code** before writing (root cause traced, consumers enumerated). This is left entirely to the attack." (`research/2026-10-15-11-spire-superpowers-coupling.md:94`). Its proposed `spire:plan` outline starts with "**Verify before writing.** Trace root causes and consumers in the code" (:230). Its design outline starts with "**Inputs.** A goal (read-only), research, a brainstorm. State which ones were used." (:215). Neither mentions project docs. +- Plan anatomy: Spire's plan should carry "Consumers of changed semantics, each with a file:line evidence pointer" and a header with "Links: goal · design · orientation · research" (§4). Here "orientation" means the user's Step 2 architectural document, not a context probe. +- Fable (§5, :91): "'Evidence with file:line for every claim' … is also the fastest-staling content and the thing that tempts a 5.5 planner to read everything. Keep it, scoped to root-cause and consumer claims only." + +--- + +## 4. What already touches options (a) and (b), or conflicts with them + +### Supports or overlaps (a), a systematic orientation probe before design/plan + +- **The user's brainstorm, Step 2** "Architectural Orientation … should help to situate the solution in the code: modules, files, structs / classes … traits / interfaces" (`brainstorm/2026-11-15-implementation_thoughts.md:5-13`). This is an *output* that shapes the solution. Option (a) is an *input* that gathers what the project already says. They are related, and both need "where would this land". But they are different artifacts with different audiences and different rates of going stale. +- **Name collision**: "orientation" already means three things here. The brainstorm's Step 2 artifact; Igor's "Orienting is not deciding" (`igor/SKILL.md:62`), which is about conversation mode; and agents "orienting" on a codebase (athanor, adept, knowledge). A probe called "orientation" would be the fourth. +- **Superpowers' "Explore project context"** as step 1 is precedent for gathering before design. It is unstructured, and it sits at brainstorm time. +- **Adept genesis**, the knowledge fallback and Athanor trunk notes are all existing Spire-native forms of "probe, then keep notes apart". +- **Dirigent's standing brief constraints** (:481) is the same need, met statically per project instead of per change. +- **The journal's own framing of (a)**: "Done as a dedicated, separate step with notes kept apart. Return to those notes after the plan, or during it when stuck / facing unknowns." (`journals/2026-10-15-21-grotto-work.md:14`) + +### Supports or overlaps (b), the attacker reading more around the project + +- The Dirigent precedent: the project rule break was caught by the adversarial plan comparison (lean report :199, :224). +- The attacker already lists "Missing function" and "security" (`attacker.md:28`), so it is the stage that asks what is missing beyond the code. +- The journal: "make the attacker read more around the project (its job is mostly ingesting)" (`journals/2026-10-15-21-grotto-work.md:13`). + +### Tensions and conflicts + +| Tension | Source | Bears on | +|---|---|---| +| **Drift**: up-front artifacts go stale, and orientation-type content (files, structs, traits) drifts fastest. Fable: "A third interdependent artifact in the 1→2→3 chain is exactly the drift the user named." | Fable :73; journal 10-15-11 :163 | (a) as a separate artifact. Probe notes on *docs and rules* probably drift slower than notes on *structure*, but this is untested. | +| **Cost per stage**: pre-build docs were 19% of active time. Dirigent's policy skips stages for builds of that size. | Retrospective :177, :258 | (a) as a mandatory stage. Note that the retrospective blames *scope*, not missing context. | +| **Checklist bias**: "a reviewer handed a checklist tends to confirm the checklist" | `implementation/SKILL.md:32`; lean report :147 | Feeding probe notes to the attacker or reviewer as a list could narrow their adversarial reading. | +| **The attack is conditional**: the attack is skipped when the plan was written by 5.5 after tracing the code; a drift check replaces it | Lean report §A.1 | (b). If project-doc checks live only in the attack, they vanish whenever the attack is skipped. | +| **The attack does double duty**: reformat plus attack is already a concern | Coupling :101; Fable :92 calls it a hypothesis | (b) adds a third duty. | +| **Late detection**: an illegal feature found at the attack means the planner's work, and possibly the design, are wasted. "Approach is wrong → back to design." | `igor/SKILL.md:106` | (b) alone catches the problem but does not prevent it. | +| **Read-everything temptation**: a 5.5 planner reads broadly when asked to cite evidence | Fable :91 | (a) needs bounds on what it reads, or it becomes unbounded reading. | +| **Grotto must be standalone** without Spire's agents, project file or knowledge skill | Goal :59 | If the probe lives in grotto, it cannot depend on `spire:project` or adepts. | +| **Code is truth; designs are not specs** | Goal :58; journal 10-15-11 :155-157 | Probe notes are a *read* of the docs, not a new source of truth. Where docs and code disagree, the notes have to say so. | + +I found nothing in the new docs that rules out (a) or (b) outright. + +--- + +## 5. Options for where an orientation probe could live + +These are options, not recommendations. Each one names the stage, who runs it, what it leaves behind, how it gets revisited, and the trade-offs. They can be combined. + +### Building blocks, whichever option is chosen + +- **Probe scope** (the user's list, journal :14): where the change would land; local project docs (`CLAUDE.md` chain, linked `docs/`, ADRs, glossary); similar existing implementations; sibling docs (the writer when working on the reader). The knowledge fallback (`knowledge/SKILL.md:36-40`) already covers the doc half, including `glob **/CLAUDE.md`. That step removes the reliance on lazy loading. +- **Notes shape (one possible form)**: landing zone (paths); rules found (a quote plus path for each, which matches "evidence pointers"); look-alikes and siblings (paths plus one line on why each is relevant); conflicts between docs and code; unknowns. Keeping the notes separate from the design and plan keeps them out of the 1→2→3 drift chain. They are an input, not a link in the chain. +- **Revisit triggers**: (1) a planner self-check, "every rule in the notes is honoured or explicitly fenced out"; (2) on getting stuck or hitting an unknown mid-plan, re-read the notes before guessing; (3) the attacker gets the notes as an input; (4) the Athanor intake includes them in the trunk. + +### Option 1: a separate probe stage in Igor's cycle (between research and design, or 2b/3a) + +- **Runs it**: a read-only agent (`researcher` or `scout`, or a new pinned `prober`), dispatched by Igor. +- **Artifact**: `research/YYYY-MM-DD-hh--orientation-notes.md`, or a ticket `context.md` (the workpad already allows ticket-level `context.md`, `workpad/SKILL.md:66`). +- **Revisit**: Igor names the notes in the design, planner and attacker briefs. +- **For**: a fresh reader with no stake in a solution. Separate notes, as the user described. It also serves design, plan and attack. This matches the separation rule (`igor/SKILL.md:101`). +- **Against**: one more dispatch and stage, against the Dirigent cost evidence. It lives in Spire, so it does nothing for grotto standalone. Igor has to remember to pass the notes on. + +### Option 2: probe as grotto's first step (procedure text in grotto, consumed by design and plan) + +- **Runs it**: whoever runs grotto's design/plan procedure. That is the designer or planner under Spire, or the main session standalone. +- **Artifact**: an orientation-notes file in grotto's user-defined storage, next to the design and plan. +- **Revisit**: grotto's plan guidance holds the self-check and the "return when stuck" rule. +- **For**: it works standalone, which is a settled requirement, and it travels with the procedure that needs it. It fits "Spire adopts grotto's procedure" in 0.3.0. +- **Against**: if the same agent probes and plans, there is no independent reader, and the notes may be shaped by a solution it already has in mind. Grotto has to define the notes format without Spire's `project.md`. + +### Option 3: probe at planner intake (planner agent body plus self-check) + +- **Runs it**: the `planner` itself, before writing. +- **Artifact**: notes beside the plan (`plans/…-notes.md`), or a "Sources read" header block in the plan. +- **Revisit**: the planner's final self-check. The attacker can check the notes for coverage. +- **For**: the cheapest option, with no new dispatch. It is a few lines in `planner.md` plus preloading `spire:knowledge`. It addresses the "luck" mechanism directly (glob `**/CLAUDE.md` instead of relying on lazy load). +- **Against**: Fable's "tempts a 5.5 planner to read everything". It does not serve the design stage, which comes earlier. The planner's notes are not independent of its plan. + +### Option 4: the attacker reads around the project (option b) + +- **Runs it**: the `attacker`. Its procedure gains "project rules and docs around the touched area" as an attack source, next to code. +- **Artifact**: a "Rules checked" section in the build plan. +- **Revisit**: none upstream. Findings go back to plan or design. +- **For**: there is a precedent (Dirigent Plan A caught by the comparison). It needs no new stage. The attacker is already a fresh, adversarial reader. +- **Against**: it is late, so the plan and maybe the design are wasted. It disappears when the attack is skipped (§A.1). It adds a third duty to the attack. It only detects, it does not prevent. + +### Option 5: project-level static channel (Spire config plus skill preload) + +- **Runs it**: nobody per change. The `spire:project` file names doc entry points and constraint sources, `Brief constraints` is populated, and the planner, attacker and reviewer preload `spire:knowledge`. +- **Artifact**: `.claude/spire/project.md` fields. +- **Revisit**: always loaded, because skills preload at agent start. +- **For**: almost free per run, and it follows the Dirigent "standing brief constraints" lesson. +- **Against**: it only catches rules someone remembered to register. It goes stale with the project. It does nothing for look-alikes or siblings. It is Spire-only. + +### Option 6: an adept as the probe + +- **Runs it**: Igor spawns or resumes an adept for the area. Its genesis is already a probe, producing key-files, conventions, gotchas and an orientation trace. +- **Artifact**: `adepts//…`. It persists and has a drift check. +- **Revisit**: Igor consults the adept after the plan, or when the planner reports unknowns. Leaves cannot consult it directly. +- **For**: the probe outlives one change, and the mechanism already exists and has been fact-checked. +- **Against**: it is heavyweight for a single change and depends on Igor. The roster is empty in this repo and adepts are rarely used. It is Spire-only. + +### Option 7: review-time standards check (in the style of Matt's Standards reviewer) + +- **Runs it**: the phase `reviewer`, or a second reviewer, reads the repo docs for the touched area. +- **For**: it catches rules the build broke even when the plan was clean. +- **Against**: it is the latest and most expensive point to find an illegal feature. It conflicts with "Look where the code tells you to" only if the docs are handed over as a checklist. + +### Revisit mechanics compared + +| Mechanism | Cost | Reliability | Risk | +|---|---|---|---| +| Planner self-check against the notes | a few lines | high if the notes exist | rubber-stamping | +| "When stuck, re-read the notes" instruction | one line | low: depends on the model noticing it is stuck | unused | +| Attacker receives the notes as an input | brief change | medium | checklist bias (`implementation/SKILL.md:32`) | +| Notes become part of the Athanor trunk | brief change | medium | stale notes reach builders | +| Igor checks the notes against the plan before stage 4b | Igor reads two docs | medium | Igor starts doing expert work (`igor/SKILL.md:60`) | + +--- + +## Gaps and things I could not verify + +- **The Python project itself.** I do not know where the violated constraint lived (root vs nested `CLAUDE.md`, or a linked doc), what the illegal feature was, or which command the superpowers writer ran. The lazy-load explanation is a hypothesis consistent with FC-1. It is not a confirmed cause. +- **Superpowers v7 brainstorming.** Only 6.4.1 is cached locally, and the v7 clone is gone. +- **Lazy-load reliability for subagents.** It was confirmed once for Bash `ls` (FC-1), but in this session a nested `plugins/spire/CLAUDE.md` did not visibly load while I read under `plugins/spire/`. The trigger conditions are not pinned down. +- **Whether a probe pays off** is untested. No run has measured a probe, and the Dirigent evidence is about scope and loop cost, not about missing context. Fable's §6c warning applies: grotto is being shaped before lean-Athanor runs were mined (the 0.2.1-goal box "Learn from the first 0.2.0 runs" is still open, `goals/lean-athanor-0.2.1.md:10`).