agent-bios 0.9.9 → 0.11.0

package/codex/guides/coding-staged-workflow.md

@@ -7,7 +7,7 @@ use_when:
   - architecture changes, new features, cross-module or ontology changes, review-driven fixes
   - the user asks to design ("설계") before implementation
   - judging materiality of review findings and deciding when to stop or redesign
-  - choosing the per-domain verification mix (code, ontology, config/data, spreadsheets, docs)
+  - deciding where a stage's verification points and review gates belong in the work plan
 ---
 
 # Coding Guidelines: Staged Workflow
@@ -16,7 +16,12 @@ This guide is a scoped extension of the global Coding Guidelines. Use it for mea
 
 It operates inside the existing global rules for requested scope, concept economy, LLM/tools/code boundary, verification discipline, and documentation hygiene.
 
-For trivial edits, use the lightweight inspect-edit-verify path from the global Coding Guidelines.
+For trivial edits, use the lightweight inspect-edit-verify path, defined here in full:
+read the surface you are about to touch before changing it; if the request admits more
+than one reading, state the reading you act on; make the surgical edit — every changed
+line traceable to the request, adjacent code left alone; verify with the narrowest
+reliable check that would fail if the edit were wrong; clean up only what your own
+change introduced. The stages below are for work that outgrows that sentence.
 
 When the user asks to "설계" or design, stay in design mode. Focus on high-level design and implementation-process design, then present the plan, tradeoffs, review gates, and implementation trigger. Move to implementation after the user asks to implement or approves the plan.
 
@@ -32,8 +37,45 @@ When the user asks to "설계" or design, stay in design mode. Focus on high-lev
 2. Implementation-process design: turn the design into an ordered work plan with dependencies, verification points, review gates, and redesign triggers.
 3. Implementation: make the smallest viable functional changes that satisfy the approved design and process plan.
 
+**Minimum** limits surface area, configuration, abstractions, optional scope, and implementation spread. It must not reduce required behavior, runtime authority, evidence quality, or verification depth — a change that ships less of those is not smaller, it is less finished, and "smallest viable" becomes the excuse rather than the discipline.
+
+**Viable** means real behavior: the change runs against real inputs, real authority, and the intended runtime path. Mocks belong to tests, fixtures, and explicitly requested simulations — a mock-backed path supports verification but does not count as product completion, even when nothing labels it a mock; the full boundary lives in `${CODEX_HOME:-$HOME/.codex}/guides/mock-realization-boundary.md`.
+
+Define the success criteria before multi-step work starts, then verify against those criteria rather than against what you ended up building. Criteria written afterwards describe the implementation, so they cannot fail it.
+
 When simplifying a pipeline, moving processing downstream and dropping captured source fields are separate decisions: relocation is free simplification, but reducing captured information is riskier and needs explicit confirmation — "no current consumer" is not evidence of no future value.
 
+## Making the change
+
+Deciding what to build and building it are different disciplines. This one is about leaving a
+change that reads as the change that was asked for.
+
+**State the assumption before you act on it.** Most wasted implementation is not a wrong answer to
+the question; it is a right answer to a question nobody asked. Where the request admits more than
+one reading, say which one you took and keep going — surfacing it early costs a sentence, and
+surfacing it after the work costs the work.
+
+**Surgical means legible, not minimal.** Touch what the request requires, follow the file's
+existing style rather than your preferred one, and leave adjacent code alone even when it is
+worse than what you are adding. A diff carrying an unrequested refactor forces the reviewer to
+separate the two by hand, and the improvement is the part that gets dropped when they run out of
+patience.
+
+**Clean up what this change introduced, and only that.** Dead code, unused imports, and debris
+your own edit created belong in the same change. Debris you found belongs in a sentence: name it
+so it is visible, and leave it where the person who owns it can decide.
+
+**For a bug, reproduce before you fix, when that is practical.** A test written after the fix
+proves the code does what it now does. A test written before proves you understood the failure —
+and it is the only version that can tell you the fix was unnecessary, or that it addressed a
+different bug than the one reported.
+
+**Fix the cause at its authority, not the symptom where it shows.** Two signals say you are
+patching downstream: compensating code keeps accumulating around bad inputs, and each fix reveals
+another instance of the same defect. The first says go upstream to where the value is produced.
+The second says the instances are a class — single-source the value and fix the class, because
+patching them one at a time is a queue that refills.
+
 ## Review Loop
 
 - At each stage, run review loops as appropriate: self review, subagent review when available, and structured multi-lens review when the repository or domain supports one (concrete tool: Environment Binding below).
@@ -45,57 +87,17 @@ When simplifying a pipeline, moving processing downstream and dropping captured
 - Treat low and info as non-blocking unless requested or promoted by new evidence.
 - When a document declares sections co-authoritative for a rule (fixture blocks, conformance appendices), treat every occurrence as one replicated value: propagate edits to all declared locations in the same pass and check propagation completeness explicitly in review.
 
-## Verification Menus
-
-Per-domain menus for the global Verification Discipline loop; pick the narrowest reliable mix that proves the changed behavior, meaning, or contract.
-
-- Code: a layered mix of unit tests, integration tests for E2E segments, targeted E2E for changed flows, and full E2E for release or high-risk changes.
-- Ontology: static graph checks, concept economy gates, changed-path integration checks, and competency-question E2E checks.
-- Config or data: real parsers, schema checks, fixture validation, and sample transformations.
-- Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
-- Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
-- Release or distribution: after publishing to multiple independently writable channels (signed manifest, object storage, release host, embedded updater), digest-verify every referenced object against the staging original per channel — publish success and upload order are not evidence — and run the real installer/updater through its default path.
-- A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
-- Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
-- Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
-- Irreversible capture switches: when activation itself has unreproducible cost (a capture window that cannot be replayed), prove the downstream consumption path against existing samples before enabling — reversibility of the code path alone is not enough.
-
-### Deriving the case space
-
-A check has two authored halves, and they rot differently. The **verdict** — what the
-answer should be — rots by encoding a belief that was wrong from the start. The
-**space** — which cases exist — rots by staying still while the thing it covers grows.
-Recording the verdict is common practice; deriving the space is the half usually left
-hand-written, and a suite can have every expectation derived and still cover a set
-someone typed once.
-
-- Record the verdict, do not type it. Run the real path and store what came back;
-  drift then shows as a diff instead of as a belief someone has to re-justify.
-- Enumerate the space from the artifact that defines it — the config's entries, the
-  schema's fields, the router's routes, the installer's call sites. Adding one there
-  should widen coverage with no edit here.
-- Derive the exemption rule too. If some cases legitimately have no answer, decide that
-  from a property the artifact carries, never from a list of names: the list is the
-  authored space coming back through a side door, and it absorbs the regression where
-  a case that should have an answer stops having one.
-- Dedupe on the tuple that actually determines the outcome, and report how many
-  collapsed. A coverage count that hides its own truncation reads as more than it is.
-- Split by cost, not by space. When the real path needs money, credentials, or a
-  network, run a cheap stand-in on every commit and the real one on demand — both from
-  the **same enumeration**, so the two can never disagree about which cases exist.
-- Derivation moves authorship rather than removing it: the extractor and the invariants
-  are still written by hand. Give them a negative control, or the derived suite is just
-  a larger unfalsifiable one.
-- Planting a violation to prove a control fires is a write into the working tree, and
-  the restore is not atomic with it: if the probe can time out, abort, or be
-  interrupted, a restore sitting after it never runs and the plant survives into a
-  commit. Plant in a copy where the shape allows it, and when it must be in place, snapshot
-  first and restore from the snapshot as its own step rather than trusting the probe to finish.
+## Verification
+
+Verification is a subject of its own — depth, per-domain menus, deriving the case space, and what
+a green is worth. It lives in `${CODEX_HOME:-$HOME/.codex}/guides/verification-discipline.md`.
+Run it at each stage's verification points, and use its Verification Menus to pick the mix.
 
 ## Stop Conditions
 
 - If the issue boundary expands compared with the previous review, stop and ask the user to choose redesign/rework or continuing the current iteration.
 - Consider the boundary expanded when review reveals a broader affected purpose, failure condition, impact area, concept boundary, architecture boundary, or severity class.
+- When review rounds keep producing material findings, classify each before fixing: a regression the previous round's own fix introduced, or a fresh instance of one pre-existing root cause. Regressions say tighten the increment and continue; recurring instances with zero regressions say instance-patching is a refilling queue — trigger the redesign-versus-continue stop above.
 - Before calling the work done, report the current stage, review results, remaining material issues, verification results, and any stop reason.
 
 ## Environment Binding (edit per environment)
@@ -106,5 +108,5 @@ Binding (2026-07):
 
 | Slot | Binding | Notes |
 |---|---|---|
-| Structured multi-lens review | onto-mcp review (private MCP) | consumes/emits the severity contract defined in Review Loop |
+| Structured multi-lens review | agent-launch review methods: isolated panel + Codex deep exec (`codex exec` at ultra effort) + Claude ultracode workflow | consumes/emits the severity contract defined in Review Loop; personal tools register in the user-owned `review-methods.local.toml` |
 | Subagent review | host CLI's native review mechanism | e.g. Claude Code `/code-review` or Agent-tool reviewers |

package/codex/guides/concept-economy.md

@@ -0,0 +1,187 @@
+---
+guide_id: concept-economy
+language: en
+status: active
+use_when:
+  - naming anything lasting or shared — a feature, entity, type, field, flag, enum value, failure kind, artifact, or documentation term
+  - a review finding or test failure tempts you to add a name to make it go away
+  - deciding whether a value is its own concept or a property of an existing one
+  - deciding what a public surface exposes versus where the truth actually lives
+  - laying out a repository, or judging whether its shape still matches its concept graph
+core_rules:
+  - name the nearest existing concept before adding one, then choose reuse / extend / rename / split out loud
+  - every fix has a concept-surface sign — reducing, preserving, or increasing; say which before making it
+  - one value has one owner, and every other surface is generated from it rather than restated
+---
+
+# Concept Economy
+
+A scoped extension of the global Concept Economy section. Use it when you are about to introduce
+or change a name that will outlive the change that created it.
+
+The cost this guide manages is not disk or tokens. It is the reader's working set: every distinct
+name in a system is something a person or a model must hold, disambiguate, and keep aligned with
+its siblings. Two names for one behavior is not redundancy — it is a standing invitation to edit
+one and not the other, and that divergence is silent until something breaks in production.
+
+## What Counts As A Concept
+
+Anything **lasting or shared**. The list is deliberately long because the expensive additions are
+rarely the ones that feel like architecture:
+
+features, entities, variables, types, helper modules, artifacts, config keys, CLI flags, MCP/tool
+fields, public response fields, artifact fields, enum values, failure kinds, retry/recovery
+tokens, process names, documentation terms.
+
+What is *not* a concept: transient locals, generic containers (`items`, `result`, `tmp`), and
+layout a framework or tool imposes on you. The binding test is whether a second person has to
+learn the name to work here. A loop variable never crosses that line; a new failure kind always
+does, even when it is one string in one enum.
+
+The trap is scale-blindness. A field added to a response is one line of diff and a permanent
+addition to every consumer's mental model — including consumers you have not met.
+
+## The Four Paths
+
+Before adding or changing a concept, find the nearest existing one and choose a path **explicitly**.
+Choosing silently is how near-duplicates arrive: nobody decided to add a second name, they just
+did not look for the first.
+
+| Path | Choose it when | What you owe |
+| --- | --- | --- |
+| **Reuse** | an existing concept already covers this behavior | nothing — this is the default and needs no justification |
+| **Extend** | the existing concept covers it once you add a property | the property, and a check that existing readers tolerate its absence |
+| **Rename** | the behavior is right and the name has drifted from it | every site, in one change — a half-rename is strictly worse than either name |
+| **Split** | one of the split triggers below actually fired | the parent named, the reason stated, aliases mapped back |
+
+Prefer broad, stable concepts with precise properties over narrow near-duplicates. `Job` with a
+`kind` property beats `ImportJob` / `ExportJob` / `CleanupJob` as long as they share a lifecycle;
+the moment they stop sharing one, that is a split trigger, not a naming preference.
+
+### Finding the nearest concept
+
+The instruction to "find the nearest existing concept" fails when you search for the name you
+already have in mind — the name you invented will not be there, and its absence reads as
+permission. Search for the **behavior** instead:
+
+- Grep the vocabulary the concept would produce, not the concept: the enum values, the failure
+  strings, the field names, the log messages.
+- Read the nearest sibling's full definition, not its name. Names understate coverage; a type
+  called `Session` often already carries the lifecycle you were about to name separately.
+- Ask what would have to be true for the existing concept to be wrong here. If you cannot state
+  it as a behavioral difference, you are adding a synonym.
+- Check the terminology surface the repo already operates — a lexicon, a glossary, a domain
+  manifest — before the code. It is shorter and it is where the deliberate decisions live.
+
+If that search returns nothing, the addition is probably real. Record what you searched, because
+the next person will otherwise repeat it.
+
+## When To Split
+
+A split is warranted when the two things differ in something a caller can observe or must handle.
+These are the triggers; anything else is a preference:
+
+runtime behavior · ownership · lifecycle · validation · failure mode · user-visible behavior ·
+audit/replay requirements · authority · persistence · user control · failure handling
+
+Not triggers: a different call site, a different caller, a longer function, or a reviewer's
+discomfort. Those are reasons to add a property, a parameter, or a comment.
+
+When a split is necessary, three things ship with it or the split leaves debt:
+
+1. **Name the parent.** The concept being split from, explicitly, in the change.
+2. **State the reason.** Which trigger fired, in one sentence, where a maintainer will find it.
+3. **Map the variants back.** Aliases, deprecated spellings, and old values resolve to the
+   canonical concept — otherwise the old name lives on as a second concept nobody declared.
+
+## Derived Values Stay Derived
+
+A value that tools or code can compute from its source is a **property or projection** of that
+source, not a concept of its own. Persisting it creates a second authority that can disagree with
+the first, and it will: the source moves and the copy does not.
+
+The test is whether anything reads the stored value that could not have derived it. If the answer
+is no, the value is a cache at best and a contradiction at worst.
+
+**Authority is not visibility.** These are separate questions and conflating them produces both
+failure modes at once:
+
+| | Question | Wrong answer looks like |
+| --- | --- | --- |
+| Authority | where does the truth live, and who may change it | two writers, or a derived copy that outranks its source |
+| Visibility | what may a given surface see | an internal projection leaked into a public contract, now unchangeable |
+
+A public response may expose a bounded view — fewer fields, coarser precision, a rendered form —
+while the source concept or artifact remains the one truth location. That is a projection, and it
+is correct. What is not correct is treating the projection as the place to fix a wrong value.
+
+Keep internal projections and helper outputs internal unless public exposure is genuinely required
+by user behavior, a product contract, or artifact truth. An exposed field cannot be withdrawn on
+your schedule.
+
+## Reuse The Vocabulary Before Adding To It
+
+Enum values, failure kinds, retry/recovery tokens, and result/failure surfaces are concepts with
+unusually high blast radius: every consumer's branch coverage depends on the set being stable.
+Adding a value obliges every exhaustive reader to handle it; adding a near-synonym obliges them to
+handle it *and* to guess which one they will actually receive.
+
+Check the existing set first, and prefer an existing value whose meaning genuinely covers the case
+over a new one that describes it more precisely. Precision that fragments the set costs more than
+it buys.
+
+## Classifying A Fix
+
+Before fixing a review finding or a test failure, say which way the fix moves the active concept
+surface:
+
+- **Reducing** — the fix removes a name, merges a duplicate, or deletes a branch. Cheapest, and
+  usually available when the finding is "these two do the same thing".
+- **Preserving** — the fix changes behavior inside existing names. The normal case.
+- **Increasing** — the fix adds a name. Legitimate, but it must survive the four-paths question,
+  and a review finding is not by itself a reason to add a concept.
+
+This matters because review findings create pressure toward the increasing path: adding a flag, a
+kind, or a special case makes a finding disappear locally while widening the surface everyone else
+carries. Naming the direction before making the change is what keeps that trade deliberate.
+
+## Migration Compatibility
+
+**Use** fallback paths, compatibility shims, and deprecated alias normalization **when explicit
+migration compatibility is required** — the obligation runs both ways: required compatibility gets
+a shim, and nothing gets one as a default hedge. Each one is a second
+concept surface that must be maintained and eventually removed.
+
+When you add one, the removal condition ships with it: what has to be true for the shim to go, and
+where that is recorded. A compatibility path with no stated end becomes permanent architecture by
+attrition.
+
+## Keeping The Shape Navigable
+
+Let the repository's shape mirror its concept graph. A shared, lasting concept's canonical name
+should be traceable across every layer it appears in — path, module, type/interface, field, public
+API — so the structure is guessable from the concept name instead of from a translation table you
+have to already know.
+
+The working test: someone who knows the concept's name but not this repo should be able to guess
+the path, or find it with one grep. If finding it requires knowing that the concept is called one
+thing in the schema, another in the module, and a third in the URL, the layout has stopped being
+navigable and the names are doing damage rather than work.
+
+This binds shared concepts only. Transient locals, generic containers, and framework- or
+tooling-imposed layout may diverge, and forcing them to conform is its own kind of waste.
+
+## Domain Notes
+
+- **Ontology work.** Check existing entities and relations first — before adding, modifying,
+  removing, or relinking either; the graph is the
+  artifact whose value degrades fastest under duplication, because every added node multiplies the
+  edges a reader must consider.
+- **Code work.** Follow the naming patterns the repository already uses — the file first, then
+  its neighbors — and consolidate the variations
+  your own change introduced before calling it done. A change that leaves three spellings of one
+  idea has added two concepts regardless of intent.
+- **Comments and active docs.** Keep them aligned with current runtime behavior, failure
+  semantics, retry policy, ownership, and authority. A comment describing a superseded contract is
+  not stale documentation — it is a second, false authority, and it reads as current to anyone who
+  finds it first.

package/codex/guides/documentation-hygiene.md

@@ -0,0 +1,112 @@
+---
+guide_id: documentation-hygiene
+language: en
+status: active
+use_when:
+  - writing a comment, and deciding whether it earns its place
+  - recording why something changed, an alternative that was rejected, or a migration's rationale
+  - deciding whether an active document should link to a historical note
+  - authoring a rule, guideline, or instruction others will follow
+  - choosing where change history and implementation context belong
+core_rules:
+  - prose about the past and prose about the present need different addresses, not different tenses
+  - a comment earns its place by carrying what the code cannot say about itself
+  - phrase a rule as the behavior you want, because a prohibition describes everything except what to do
+  - a continuously overwritten "current state" file claims to be now and is no particular time
+---
+
+# Documentation Hygiene
+
+A scoped extension of the global Documentation Hygiene section. The subject is placement: **prose
+about the past and prose about the present need different addresses.**
+
+The cost this manages is misreading, not tidiness. A sentence describing how something used to
+work, sitting beside code that works differently now, reads as a present fact — to a person
+skimming and to a model retrieving. Nothing marks it as history except a tense, and a tense is not
+a signal anyone checks. Moving it is cheaper than maintaining the reader's suspicion.
+
+## The two addresses
+
+**Active surfaces** — runtime code, comments, the docs someone reads to operate the thing — carry
+current behavior, current decisions, current contracts, current authority, current failure
+handling. Nothing else.
+
+**Isolated paths** — `docs/`, `design/`, `archive/`, `deprecated/` or whatever the repository uses
+— carry backward-compatibility notes, deprecated behavior, migration rationale, historical
+alternatives, change narratives, and handoff logs.
+
+The test for any sentence: *if this stopped being true, would anyone notice?* Active surfaces are
+where the answer must be yes, because something breaks. History is where the answer is no, which
+is exactly why it must not sit in the first place.
+
+## Comments carry what the code cannot
+
+A comment earns its place by saying something the code cannot say about itself:
+
+- Non-obvious current behavior — why this looks wrong and is right.
+- An invariant a reader could break without noticing they broke it.
+- A constraint that comes from outside the file: a protocol, a rate limit, an ordering another
+  system depends on.
+- A risk that still applies. Not one that used to.
+
+What does not earn its place: restating the line below it, narrating the change that introduced it
+("changed this to fix the bug"), or describing a contract that has since moved. That last one is
+not stale documentation — it is a **second, false authority**, and to whoever reads it first it is
+simply the answer.
+
+Comments describing superseded behavior are the highest-yield deletion in most files. They are
+also the hardest to find, because nothing fails when they are wrong.
+
+## History has its own address
+
+When you have something worth recording that is not current behavior — why an alternative was
+rejected, what a migration was compensating for, what a session handed off — write it in an
+isolated path rather than beside the code.
+
+Two properties make such a record useful:
+
+- **It is written once.** A record that is edited whenever things change stops describing any
+  particular moment. If it must be updated, the honest move is a new record that supersedes the
+  old one, not an overwrite.
+- **It carries its own point in time.** A timestamp in the filename cannot rot, because the age is
+  on the label. A file called "current state" makes a claim it cannot keep.
+
+That second point generalizes past records. Any continuously overwritten "the state of things"
+document claims to be now and is, in practice, no particular time — the last person to touch it
+decided how current it is, and nobody else can tell. Where the underlying facts are derivable,
+give the reader the command that re-derives them instead of a number someone typed.
+
+## Linking back
+
+Link from active material to a historical note only when the current task needs that history, or
+when the reference genuinely helps a future maintainer — usually because the present design looks
+arbitrary without it.
+
+A link is a small permanent cost: it invites the reader to leave, and it must stay resolvable. An
+active document that links to five historical notes has partly become one.
+
+## Writing rules people follow
+
+Phrase a rule as the behavior you want, not as the thing you are afraid of. A prohibition
+describes everything except what to do, and leaves the reader to invent the positive form —
+usually at the moment they have the least attention to spare.
+
+- "Pin the interpreter when a bash-specific feature is needed" beats "don't rely on the default
+  shell".
+- "State the assumption you are proceeding under" beats "don't guess".
+
+Two more properties of a rule that survives contact:
+
+- **It says when it fires.** A rule with no trigger is advice, and advice is followed when
+  convenient.
+- **It says what it costs.** A rule whose expense is hidden gets quietly dropped the first time
+  someone is in a hurry, and nobody records that it was dropped.
+
+## Where change history belongs
+
+Prefer the established homes over inventing one per change: a changelog for released behavior, a
+current-state dashboard for architecture and risk, handoff notes for what a session left unfinished.
+
+Keep their jobs distinct. A changelog that accumulates design rationale becomes unreadable as a
+changelog; a dashboard that accumulates history stops being current. When a document starts
+answering a question it was not built for, that is a signal to split it, not to add a section.

package/codex/guides/review-request.md

@@ -26,10 +26,11 @@ verification_focus:
 This guide is a scoped extension of the global Coding Guidelines. Use it when
 composing what you ask a reviewer for — the request, the evidence bar, the
 verdict shape. It does not cover when to review, how deep, or what counts as
-material (the staged-workflow guide's severity ladder and review loop own that),
-which reviewer kind to route to (the multi-model guide's convergence heuristic),
-or how to phrase a prompt for a given model family (the per-family prompting
-guides).
+material (the severity ladder and review loop in `${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md` own that),
+which reviewer kind to route to — the convergence heuristic in
+`${CODEX_HOME:-$HOME/.codex}/guides/verification-discipline.md` owns that. Phrasing a prompt for a specific model
+family is out of scope here; where that guidance ships, the rule that needs it
+points at it.
 
 The rules below are derived from ~330 real multi-lens review sessions run in
 this environment. That corpus is one model family in practice, so nothing here
@@ -80,8 +81,9 @@ So state the floor in the request: **do not report a finding you would rate low.
 It will be discarded; spend the effort on a medium-or-above finding instead.**
 This is not a quality bar on the reviewer, it is a cost decision — the corpus
 shows the discard happens regardless, so the only question is whether you pay to
-generate it first. (What counts as each severity is the staged-workflow guide's
-ladder, not this guide's.)
+generate it first. (What counts as each severity is the ladder in
+`${CODEX_HOME:-$HOME/.codex}/guides/coding-staged-workflow.md`, not
+this guide's.)
 
 ## Forbid carry-forward findings
 
@@ -128,7 +130,7 @@ nicely: the submit schema refuses output without them. The result is a corpus
 where reviewers are right about existence (0.3% of issues end unresolved after
 argument) and where "found nothing" is a verified statement rather than silence.
 
-This is the general rule from the capability-boundary guide applied to review:
+This is the general capability-boundary rule applied to review:
 when output must have a property, make it unavailable without it. If your review
 route has a schema, put the anchor there. If it does not, the demand belongs in
 the request — but expect the weaker result that a request-only rule gives you.

package/codex/guides/session-distill-workflow.md

@@ -50,9 +50,9 @@ Run in order; each stage reads the previous stage's `out/`:
 2. `digest.py` — one secret-redacted digest per session with deterministic
    6-criteria signals. Screen ALL digests; triage orders, never drops.
 3. Provider-affine screening against the concatenated live baseline
-   (CLAUDE.md + guides): `screen-claude.js` (Workflow) and
-   `screen-codex.js` (ultracode). Novelty is judged against real baseline
-   text, not memory.
+   (CLAUDE.md + guides): `screen-claude.js` (Claude sessions) and
+   `screen-codex.js` (Codex sessions), both dynamic-workflow scripts.
+   Novelty is judged against real baseline text, not memory.
 4. `consolidate.js` — dedup + independent novelty verification. Rank by
    strength (recurrence × materiality), never by self-reported confidence.
 5. `bundle_final.py` — tiered bundle. Merge new candidates into

package/codex/guides/tooling-gotchas.md

@@ -108,6 +108,16 @@ depends on it, pin it explicitly instead of trusting the environment.
 
 ## Git operations
 
+- **A stale local base inflates the range**: before reasoning about what a branch
+  contains or opening a PR, `git fetch`, then ask against the remote rather than the
+  local tracking ref — `git log origin/<base>..HEAD` for which commits are yours, and
+  the merge-base form below for the diff. On a shared repo the local base lags until
+  you pull, so `<base>..HEAD` quietly folds in work that already merged. When a range
+  looks surprisingly large, suspect the base before the branch.
+- **"Mergeable" is measured against the base, not against siblings**: the platform
+  flag says each PR merges into the base, and two PRs can both be clean while
+  conflicting with each other. Before choosing a merge order, diff their changed-file
+  sets and simulate the sequence.
 - **Two-dot diff semantics**: `git diff A..B` is a direct snapshot
   comparison — unlike `git log A..B` it excludes nothing, so a lagging
   merge-base injects unrelated upstream changes into the diff. For PR/review