model-orchestrator 0.1.35 → 1.0.0

package/templates/common/protocols/build-protocol.md

@@ -1,143 +1,128 @@
-# Build Protocol
+# Build protocol: from the request to a change in use
 
-**Three phases, eight stages, and every gate is a question that can be answered wrong.**
+When a task builds, codes, implements, migrates or deploys, follow this procedure. For a lookup, prose edit, bulk classification or one-line configuration change, use the relevant routing rule and verify the result directly.
 
-Fires on any task that builds, codes, implements, migrates or deploys. Rough test: if it would earn a second-opinion audit or a tracker issue, it runs this.
+When a check controls a decision, first demonstrate an input that makes it fail. When a tool reports a finding, reproduce it before treating it as evidence. Keep every step proportional to the approved scope.
 
-> **The one rule underneath:** a gate you cannot fail is not a gate. If a stage's exit reads like "confirm it looks good", it is written wrong and it will pass every time, including the times it should not.
+## Pre-build
 
-Three corollaries:
-1. A check nobody has watched fail is not known to work. Prove a gate can go red before trusting green.
-2. A tool's output is a claim, not a fact. Scanner findings, audit reports and exit codes get read and reproduced before they are repeated.
-3. A gate that fires on unrelated things gets bypassed, and a bypassed gate certifies what it never checked.
+### 1. Frame the request and probe the runtime
 
-| Phase | Master question | Stages |
-|---|---|---|
-| 1 Pre-build | What exactly are we building, what do we need first, and what does this touch or break? | 0 Route · 1 Map · 2 Judge |
-| 2 Build | Is it secure, built on current code, and correct without hidden flaws? | 3 Build · 4 Scan · 5 Challenge · 5b Ship gate |
-| 3 Post-build | Did it land everywhere, is it proven against the real thing, and is it recorded? | 6 Verify · 7 Record |
+- Quote each acceptance-critical clause from the user's request and write the observable property that must hold in the final artifact.
+- Give each property an **acceptance check**: a command that exits zero when the property holds, or an explicit manual procedure. Store checks using `ACCEPTANCE_CHECKS.json` and `protocols/acceptance-checks.md`.
+- Probe the tools, models, access and services available now. Use the tool's own command or capability listing and record which surface it covers.
+- Freeze acceptance-critical availability facts as checks too. When a dependency or permission changes, rerun the affected probe before work that assumes it.
+- When the approach depends on a risky assumption, spike it on the actual runtime before building. Carry the measured value, method and date into the task brief.
+- When requirements conflict, mark the affected check unresolved and obtain a decision before dependent work proceeds.
+- Record decisions as they are made with **Did / Why / Serves / Rejected** in `DECISIONS.md`; see `protocols/decision-log.md`.
 
-The two seams are the point. Pre-build to Build: nothing is written yet, changing your mind costs a conversation. Build to Post-build: the ship, the only irreversible step, the only one that needs an explicit human yes.
+**Exit:** the ask, scope, checks, availability evidence and risky assumptions have named records and verifiers.
 
-## Phase 1 · Pre-build
+### 2. Apply the ordering function
 
-### Stage 0 · Route
-1. Do we have everything needed to start? Every key, access path and asset **verified present by a live probe**, not assumed from a doc.
-2. Is this actually a build, or a quick fix, doc edit, or question that needs no plan?
+When choosing the next step or resource, apply this ordering:
 
-**Gate:** classified, and every required input confirmed to exist and work. Verify access here, never at ship time. A missing credential found at Stage 0 costs a message; found at Stage 5b it costs the session.
+1. Satisfy dependencies before their consumers.
+2. Check invalidators earliest: availability, permission and whether the build is needed.
+3. Use cheap deterministic probes before model judgment.
+4. Run independent units together within the available concurrency and scope.
+5. Put irreversible actions last.
 
-### Stage 1 · Map
-1. What does this touch, improve, scale, or replace? Docs, indexes, tracker issues, tool servers, devices, scheduled jobs, hooks, other repos.
-2. What already-working thing could this break, and does something already do this?
+When a step is unnecessary, record the skipped step and the evidence for skipping it. Select resources from the live probe when their capabilities serve the task.
 
-Four bounded questions, not four exhaustive scans. **The builder maps; the judgment tier does not.** Retrieval is mechanical and the builder holds the local tooling and the map stays in its context for the build. Paying top-tier rates for a file list is the most expensive routing mistake available.
+### 3. Research bounded questions
 
-**Gate:** a written map naming affected files, systems and issues.
+- Write the questions, search ceiling and stop condition before research.
+- Read current official documentation for changing external interfaces and inspect relevant open-source approaches.
+- Vet a repository before reading its implementation: reputation, usage, age, maintenance, author and answered issues.
+- When signals are strong in a hard domain, surface adoption versus reimplementation to the user before adding the dependency.
+- When signals are adequate, extract the technique and its limits. When signals are weak, exclude the source and record why.
+- Return the technique, what it does, its implementation location and licence. Treat documentary claims as assumptions until runtime or source verifies them.
+- When research could remove the need for the build, complete it before mapping. Otherwise run it beside independent mapping work.
 
-### Stage 2 · Judge (Checkpoint 1)
-Ask the judgment tier, on the finished map:
-1. Is this the simplest way to build it, or are we overcomplicating?
-2. What is most likely to go wrong, and what did the request miss?
+### 4. Write one context file
 
-**Gate:** **one named weak spot** and **one gap in the request**. Approval alone is not an exit; an advisor asked only to approve will approve. If a consult comes back mostly restating the map, the brief asked it to retrieve when it should have asked it to decide.
+- Read the project rules, relevant records and current task state within the authorized scope.
+- Map the affected files, interfaces, users and connected surfaces with bounded searches.
+- List necessary steps, recorded skips and the facts already answered by existing sources.
+- Batch remaining questions that would change the build before dependent implementation.
+- Write one `CONTEXT.md` per run. Every task brief points to that **context file**; verify a sample of its claims against source. See `protocols/context-file.md`.
 
-## Phase 2 · Build
+**Exit:** a reader can reconstruct the approved scope and current evidence from one context file.
 
-### Stage 3 · Build
-"Up to date" means two things. Ask both.
-1. Is our repo clean and current? No stray uncommitted work, on a branch, base ref recorded.
-2. Am I writing against an external API or SDK, and have I read its actual source this session? Never from recall. Read the installed dependency, which is what actually runs.
-3. Does the new code follow existing conventions and pass typecheck, tests, or dry-run?
+### 5. Assign by fit
 
-**Gate:** clean baseline recorded, every external-API claim traced to source read this session, build green. Check a reference clone's date before trusting it: a stale clone read as current is worse than no clone.
+- Before each build dispatch, check the lane's live model roster and compare configured pins with its current default. Flag a pin that has fallen behind, then choose model and effort for this job.
+- Select by reasoning depth, tool reach, context window and remaining capacity. Assign sections separately when different resources fit them better.
+- Record the lane, model, effort and reason, including why a cheaper eligible route would be insufficient.
+- Give each builder the whole scope, its own section, the context file, acceptance checks, holds/lacks inventory, measured assumptions, non-goals, interfaces to preserve, order of work and a coverage-table report contract. Use `TASK_BRIEF.md` (`aunx brief`).
+- Run the availability probe and frozen checks before starting work that depends on them.
 
-### Stage 4 · Scan (automatic, no judgment)
-1. Any secret, key or token in the new code?
-2. Any vulnerability or vulnerable dependency in the lines we added?
+{{BUILDER_HANDOFF_NOTE}}
 
-Secret detection, static analysis and dependency scanning, filtered to lines this diff added. Refuses by default: a missing or erroring scanner exits non-zero, never a silent green.
+## Build
 
-**Gate:** zero flags on added lines. Pre-existing flags are reported, never inherited as blockers, and never waved through unread. A scanner finding is a claim; read the code before calling it anything.
+### 6. Implement and verify
 
-### Stage 5 · Challenge (Checkpoint 2, one pass, never two)
-1. Can bad input or a bad actor break it, and what happens when a dependency fails?
-2. Did the build stick to the approved plan, or did unintended changes sneak in?
+- Record the starting branch, base revision and existing changes before editing.
+- Use the selected build model at high effort; use xhigh where supported for architecture, security or irreversible work. Choose the model from the current roster.
+- Use the lane's available tools and authorized capabilities, including independent subagents when useful.
+- When an external interface may have changed, consult current official sources and trace each API claim to a source read during this run.
+- When a sandbox or permission boundary refuses a write, hand the required patch and evidence to an authorized writer and continue independent work. A refusal is a handoff, never a reason to widen permission silently.
+- For every background task, arm a **heartbeat** at launch: check it every five minutes for liveness and output growth. After two consecutive checks with no growth, diagnose the stall, stop blind waiting and report the measured cause.
+- Run checks appropriate to the change, including relevant secret, static and dependency scans. Read each finding and report scanner errors as unverified coverage.
 
-Route by shape: security-shaped diffs (auth, tokens, routes, deletion, bulk mutation, untrusted input) go to a second-opinion reviewer, ideally a **different model family**. Architecture-shaped diffs go to the judgment tier reviewing build against plan. Never both on one diff.
+### 7. Split and merge
 
-Findings do not go straight to a repair. Hand them to the **finding-verifier**, whose job is to DISPROVE each one: read the cited line, state what would trigger it, then hunt for the guard, caller or test that makes it impossible. It returns one of three verdicts per finding, and rounding between them is the failure mode to watch for.
+- When splitting the build, put the whole scope and all section owners in every brief.
+- Give each lane its own write boundaries and shared interface contracts.
+- Have the assigning agent merge the sections into one artifact and name every conflict and its resolution.
+- Replay acceptance checks on the merged artifact. Use that artifact for the audit.
 
-| Verdict | Meaning | What happens next |
-|---|---|---|
-| CONFIRMED | reproduced, or a concrete path nothing blocks | it earns a repair |
-| NOT_REPRODUCED | something prevents it, named and located | dropped, and not narrated |
-| INCONCLUSIVE | not settleable read-only | say what it would take; never round it to either side |
+## Post-build
 
-Use a different model family from the one that produced the finding where you have one: a family asked to check its own claim tends to agree with itself.
+### 8. Audit once, with a companion consult
 
-**Gate:** every finding **verified** before it reaches a human, and only CONFIRMED findings trigger a change. Hard cap one re-audit. `CLEAN` is a valid success state; an auditor that is not allowed to say so manufactures something, and so does a verifier that is expected to confirm.
+Run one audit pass against the final diff: build versus approved scope, correctness, and the final acceptance checks. The auditor is a different author and a different model family from the builder. When a suitable independent reviewer is unavailable, report the audit as pending and obtain the required review before shipping.
 
-### Stage 5b · Ship gate
-1. What is the rollback target? Record it before shipping.
-2. Has the human authorised this specific change going live?
+Skip this pass only when commands prove **all three** conditions: the diff is docs-only with no executable file touched; it changes no auth, secret, migration, route, mcp or policy path; and it is below the project's recorded line threshold. When a threshold or proof is absent, run the audit.
 
-**Gate:** rollback identifier written down, and an explicit yes. Authorisation is per change and does not carry over.
+In the **same step**, run a companion consult asking a different question: scope versus the user's ask, including omissions and unnecessary work. This companion is a second reviewer, independent of optional companion software. If the assigning agent authored a section, have the companion cover that section's build against its scope as well.
 
-## Phase 3 · Post-build
+- Raise review effort with the measured diff scope; use xhigh where supported for auth, tokens, OAuth, middleware, routes, MCP, untrusted input, deletion or bulk mutation.
+- Reproduce every finding or drop it. Preserve inconclusive findings with the evidence needed to settle them. `CLEAN` is a valid result.
+- Assign confirmed fixes to a non-author and add one regression per fix, first shown failing against the unfixed behavior.
+- Record dated ROUND 1 dispositions. Verify fixes with their regressions and acceptance checks; **no second audit pass** on the same diff.
 
-### Stage 6 · Verify
-1. Did it land across ALL connected surfaces? Re-grep the OLD identifier everywhere and expect zero except named historical records.
-2. Can we prove it works against the real thing, including when a dependency fails, and has each check been *seen* to go red?
+### 9. Ship into use
 
-**Gate:** real-world test passes, the negative test behaves, every gate proven capable of failing. Prefer a local reproduction of the real fault over inducing it in production.
+- Record the rollback identifier before shipping.
+- Confirm the user's authorization covers the concrete change and destination. When it does, continue; when authorization is missing, present the checked result and request it.
+- Replay all active acceptance checks against the final artifact immediately before the irreversible action.
+- Wire the change into every approved surface that makes it usable, then verify live behavior on each surface.
+- Treat shipped as a state: **in use**, with the carrying surfaces named and evidence that a real invocation reaches them.
+- When rendering, packaging or deployment can change a checked property, replay the checks against the materialized artifact too.
 
-### Stage 7 · Record
-1. Where is the ONE doc that traces this end to end? Name the path.
-2. What watches this thing? Name it, or write "nothing".
-3. Are the docs, indexes, memory and tracker updated with evidence rather than claims?
-4. Is the plan doc deleted?
+### 10. Record and report
 
-**Gate:** the end-to-end doc exists at a named path in the folder that owns the domain, with that folder's index corrected in the same pass (`protocols/memory-and-record.md`); the watcher is named or its absence is written down; the tracker is Done with evidence and read back; then the plan doc is deleted, not archived. "Nothing watches it" is a valid answer and usually the valuable one: writing it down turns an invisible gap into a tracked one.
+- Write one end-to-end operations document for anything that runs independently or supports another system: purpose, trigger, invocation chain, dependencies, reads, writes, feedback loop, failure modes, manual verification and source of truth.
+- Name what watches it; write `nothing` when there is no watcher.
+- Update documentation and indexes, then attach artifact evidence to any authorized tracker update and read the final state back.
+- Retire a temporary plan only after its operational knowledge is preserved under the project's retention policy.
+- Return a coverage table with one row per requirement and evidence. State what was built, where it is in use, how future sessions reach it, and what remains unverified.
 
-## Roles, as capabilities
+## Tools and fallbacks
 
-| Role | Does | Does not |
-|---|---|---|
-{{ROLES_BUILDER_ROW}}
-| Judgment tier | Stage 2 and the architectural arm of Stage 5. Argues with a finished map | Perform the retrieval |
-| Second-opinion reviewer | The security arm of Stage 5. Reviews the diff | Fix anything |
-| Mechanical gates | Stage 4 and any always-on guard | Be overridden without reading |
-| Cheap workers | Bounded sub-parts: bulk passes, wide searches, long loops | Own a stage |
-| Human | Stage 5b, and any irreversible or architectural call | Be the first line of review |
+When optional companion software is selected, use codecalc for computation, Context7 for documentation, and obsidian-tc for the record store. When one is absent, use the local runtime or test suite, official documentation or installed source, and repository files with search and version control respectively. These substitutions preserve the checks. A missing capability needed by a check remains explicitly unverified until an authorized tool or person can verify it.
 
-{{BUILDER_HANDOFF_NOTE}}
+## Roles
 
-## Checklist
-
-```
-PRE-BUILD
-[ ] 0  Inputs and access verified by live probe, not assumed
-[ ] 0  Confirmed this is a build and not a quick fix
-[ ] 1  Everything it touches written: files, systems, issues
-[ ] 1  Asked what could break, and whether this already exists
-[ ] 2  Judgment tier named a weak spot AND a gap in the request
-
-BUILD
-[ ] 3  Repo clean, on a branch, base ref recorded
-[ ] 3  External API claims traced to source read this session
-[ ] 3  Typecheck / tests / dry-run green
-[ ] 4  Scan clean on ADDED lines; pre-existing flags read, not inherited
-[ ] 5  One audit pass, findings reproduced, plan drift reviewed
-[ ] 5b Rollback target recorded
-[ ] 5b Human authorised this specific ship
-
-POST-BUILD
-[ ] 6  Old identifier re-grepped everywhere, zero hits
-[ ] 6  Real-world test passes; negative test goes red
-[ ] 6  Every gate proven capable of failing
-[ ] 7  End-to-end doc exists at ONE named path
-[ ] 7  "What watches it" answered, even if the answer is "nothing"
-[ ] 7  Tracker Done with evidence, state read back
-[ ] 7  Plan doc deleted (only after the end-to-end doc exists)
-```
+| Role | Responsibility | Boundary |
+|---|---|---|
+| Assigning agent | Scope, resource selection, section ownership, merge and reporting | Granted scope |
+{{ROLES_BUILDER_ROW}}
+| Planning model | Resolve ambiguity using prepared context and evidence | Read-only planning |
+| Independent reviewer | Audit the merged build against scope and acceptance checks | Review and report |
+| Companion reviewer | Check scope against the ask in the same audit step | Independent question |
+| Cheap workers | Bounded retrieval, classification and mechanical work | Assigned section |
+| Human | Resolve missing mandates and authorize irreversible actions | User decisions |

package/templates/common/protocols/context-file.md

@@ -0,0 +1,10 @@
+# Context file: one shared source for a run
+
+- When a build begins, scaffold `CONTEXT.md` with `aunx context` and fill it from the approved request and bounded source reads.
+- Record the live state, affected files, acceptance checks, resource inventory, measurements, dependencies and resolved decisions once.
+- When sending a task brief, point it at this context file and give the receiving worker access to the content.
+- When a source fact changes, update the file and rerun the affected verifier before dependent work continues.
+- Verify a sample of the context file's claims against original source paths or runtime output.
+- When the task ends, record final evidence and unresolved limits where the next reader can find them.
+
+When a shared record tool is available, use it within the granted scope. Otherwise keep the file with the project and use version control to preserve edits.

package/templates/common/protocols/decision-log.md

@@ -0,0 +1,9 @@
+# Decision log: the choice and its evidence
+
+- When deciding an approach, record **Did / Why / Serves / Rejected** in `DECISIONS.md` while the choice is current.
+- Name what was chosen, the evidence supporting it, the user requirement it serves, and the alternatives set aside.
+- Keep the explanation at the level a reviewer needs to assess the choice. Private chain-of-thought stays out of the record.
+- When a decision changes, append its replacement with the new evidence and identify what it supersedes.
+- When a workflow step is skipped, name the step and the reason in the same record.
+
+When a record-store companion is absent, use a project Markdown file and version control. One writer owns the shared record; other lanes return proposals with evidence.

package/templates/common/protocols/deep-research.md

@@ -1,44 +1,30 @@
-# Deep research: parallel engines, then triage
+# Deep research: bounded questions and verified sources
 
-Two research lanes, not three. The old "quick fact / known source / deep" split was ceremony.
+When one lookup or a known source answers the question, retrieve it and answer directly. When the source set is unknown, several sources need reconciliation and the result will be cited later, use this procedure.
 
-| Lane | Entry condition | Output |
-|---|---|---|
-| **Search** | You can name the source, or one lookup answers it | Inline answer, no artifact |
-| **Deep** | All three: the source set is unknown, several sources must be reconciled, and the output must survive being cited later | A dated, cited artifact |
+## Prepare and run
 
-## The shape of a deep run
+1. Write the research questions, source standard, authorized scope, search ceiling and stop condition.
+2. Break the question into independent sub-questions and check that each serves the user's ask.
+3. Vet sources before relying on them. For implementation sources, inspect reputation, usage, maintenance, authorship and licence.
+4. Run independent questions on available authorized engines, then open primary sources supporting material claims.
+5. Search existing records before adding a new durable report.
+6. Write one dated synthesis with citations, claim status and unresolved questions.
+7. Name the practical next step supported by the evidence: use, prototype, monitor, reject or take no action.
 
-```
-0 CHARTER   what topics, what counts as a source, what is worth interrupting a human for
-1 PLAN      decompose into sub-questions   <- highest leverage stage; a mis-scoped question
-                                              produces a confident report about the wrong thing
-2 RUN       fan out to independent engines
-3 TRIAGE    reconcile disagreement against primary sources you open yourself
-4 DEDUPE    check what you already have BEFORE writing (semantic search; see memory-and-record.md)
-5 BRIEF     one dated artifact with marks (below)
-6 ROUTE     adopt / prototype / watch / pass / no action
-```
+## Mark each claim
 
-## Marks every claim carries
+- **CONFIRMED:** verified against a primary source, with independent corroboration where required by the question.
+- **DISAGREEMENT:** keep competing readings and name the evidence that would settle them.
+- **REPORTED:** attribute a source's statement to that source.
+- **UNVERIFIED:** name the absent evidence or access.
 
-- **CONFIRMED**: at least two independent engines agreed AND you opened the primary source.
-- **DISAGREEMENT**: engines conflicted. Record the verdict and the rejected reading. Never average.
-- **REPORTED**: a named person's post, a forum thread, a tool's self-report. Quoted, not trusted.
-- **UNVERIFIED**: plausible, single-source, or unsourced precision. Do not cite as fact.
+When engines agree, inspect their shared premise. When they disagree, keep the difference visible until source evidence resolves it. When a figure affects a decision, compute it or verify its source.
 
-Agreement is weak evidence. Disagreement is the signal.
+## Select available research tools
 
-## Level 1: one agent
+{{RESEARCH_SELECTION_ADVICE}} Have one writer reconcile the outputs and maintain the durable report. Give every engine the context file, task brief and stopping condition.
 
-You still get the shape. Run PLAN as its own turn and inspect it before spending anything. Run the sweep. Then run a **fresh-context second-opinion turn** with a brief that says "question the premise; list what this report would get wrong if its sources were stale". Plant one deliberately wrong figure in the brief and see whether it corrects it: if it does not, its confirmations are worth less than they look. Mark every claim.
+When only one engine is available, use a fresh context to question the sources and coverage, and report that limit. When Context7 is absent, use official docs or source. When a computing companion is absent, use the local runtime for numerical checks. When a record-store companion is absent, use project files and version control.
 
-## Level 2 and up: selected engines, one triager
-
-{{RESEARCH_SELECTION_ADVICE}} The orchestrator triages: it opens the primary sources itself, marks each claim, and writes the brief. Only the orchestrator writes the durable record; every other engine proposes.
-
-Known failure shape: one engine will return confident unsourced numerics and claim full coverage. Downgrade those to hypothesis. The engines that report their own gaps honestly are the ones to weight.
-
-## Measure
-
-Count **dispositions**, not briefs. A week that produced seven briefs and zero decisions is a failure.
+When evaluating a research method itself, use a labelled false-premise fixture and confirm that the method rejects it. Keep fixture claims separate from the factual report.

package/templates/common/protocols/docs-then-prove.md

@@ -1,26 +1,21 @@
-# Docs, then prove: documentation is a lead, never a verdict
+# Docs, then prove: verify interfaces on the runtime
 
-**Why this is not `numbers-and-logic.md`.** That protocol is scoped to arithmetic, comparisons and complexity claims. This one is scoped to a different failure: trusting what a library, SDK, API or CLI is documented to do instead of checking what it actually does on this version, in this codebase. Two different mistakes, two different tools, one rule underneath both: a model that feels finished is not the same thing as a model that checked.
+When coding against a changing library, SDK, API or CLI, read current documentation for the version in use, then run a check against the actual runtime.
 
-Companion tool for this rule: **Context7** (Upstash), {{CONTEXT7_STATUS}}. It pairs with **codecalc**, {{CODECALC_STATUS}}: Context7 tells the agent what the library is SUPPOSED to do (current, version-aware docs); codecalc runs the code and proves what it actually does. Docs never stand as proof on their own, and where a doc and a run disagree, the run wins and the source settles it.
+Optional companions: **Context7** (Upstash), {{CONTEXT7_STATUS}}, for documentation; **codecalc**, {{CODECALC_STATUS}}, for execution checks.
 
-## When calling is mandatory
+## Check an interface
 
-| You are about to | Use |
-|---|---|
-| write code against a library, SDK, API or CLI you have not confirmed the current signature for | Context7 (`resolve-library-id` then `query-docs`, or `ctx7 library` / `ctx7 docs`), then write the call |
-| claim a documented behaviour is what the code actually does | run it (`execute_code`, the project's own test suite, or a REPL), never the doc alone |
-| a doc and a run disagree | the run wins. Say so, and say what the doc got wrong (a stale version, a changed default, a deprecated flag) |
-| training-data recall of a library's API surface, with no source open | treat it as a guess until a doc or a run confirms it; version drift and renamed APIs are the common failure, not a rare one |
+1. Identify the library and installed or requested version.
+2. Read its current official documentation or source. With Context7, resolve the library ID before querying its docs unless a verified ID is already available.
+3. Write the smallest representative call and run it through the local runtime, test suite or codecalc.
+4. When docs and runtime disagree, inspect the implementation and version, record the difference, and base the build on verified behavior.
+5. Name the source, version, runtime check and result in the task evidence.
 
-Trivial, unversioned standard-library calls you would bet the build on are exempt. Anything with a version number attached to its behaviour is not.
+## Official-source and local-runtime workflow
 
-## How to report a documentation-derived claim
+When Context7 is absent, use the vendor's documentation, README, changelog or installed source. When codecalc is absent, use the project's own interpreter or tests. When neither path can verify the needed behavior, mark that assumption UNVERIFIED and route the probe to a lane with authorized access.
 
-Name the library, the version if Context7 returned one, and that it came from docs, not a run: "per Context7, `/vercel/next.js@14.0.0`'s middleware API takes X" reads differently from "Next.js middleware takes X", because the first can be checked against a version and the second cannot. If the claim was then verified by running it, say that too, and which one actually settled the question.
+When reporting a documentation-only claim, label it as such. When a run verifies it, cite the check separately. Keep consequential arithmetic under `numbers-and-logic.md`.
 
-## Without Context7
-
-The rule still binds. Read the vendor's own README, changelog or source before writing code against it, the same way this repository's own `AGENTS.md` asks: read the actual API, not a recollection of it. What is not allowed is code written against a remembered shape of a library that was never opened this session.
-
-Source: https://github.com/upstash/context7
+Companion source: https://github.com/upstash/context7

package/templates/common/protocols/gap-analysis.md

@@ -1,28 +1,22 @@
-# Gap analysis: the second pass
+# Gap analysis: compare scope with the request
 
-**On any comprehensive task, run a second pass that hunts for what is MISSING, not just verifies what is there.** Comprehensive means research, audits, plans, builds, and multi-file work.
+When a task covers several requirements or surfaces, compare the result with the user's ask and the prepared map. For a build, run this as the companion consult in the same audit step; it asks scope versus ask while the auditor checks build versus scope.
 
-Verification asks "is what I did correct?". Gap analysis asks "what did I not do?". They are different questions and the second one is the one a first pass cannot answer about itself.
+## Check coverage
 
-## The shape
+1. Enumerate the actual files, tests, configured lanes, jobs and sources within scope.
+2. Map every clause of the request to evidence in the result.
+3. Identify missing requirements, unintended additions and changes omitted from the map.
+4. Check the behavior expected when a dependency is absent or unavailable.
+5. Return one coverage row per requirement with IMPLEMENTED, PARTIAL, MISSING or OUT-OF-SCOPE and a source path or check.
 
-1. **Enumerate what exists.** The live state, not the plan: files written, tests present, lanes configured, jobs scheduled, sources consulted.
-2. **Diff it against the ask and the map.** Every clause of the original request maps to at least one thing you did. Every item on the Stage 1 map maps to a change. A clause with no step is dropped scope; a step with no clause is invented scope. Say both.
-3. **Hunt the absences.** For each category: what would a reader expect to find here that is not here? What does the source say that the output does not? What fails if a dependency is down?
-4. **Report the gaps as findings**, not as apologies. Each one: what is missing, where it should be, and whether you are closing it now or naming it as open.
+## Choose the reviewer
 
-## Who runs it
+- When an independent reviewer is available, give it the whole ask and scope with the final artifact.
+- At level 2 and above, consider this selected lane: {{GAP_ANALYSIS_LANE}}
+- When only one agent is available, use a fresh context for the coverage question and identify the independence limit. A build's required independent audit remains pending until an eligible reviewer can perform it.
+- For a recurring capability check, enumerate live state and compare it with the documented configuration on the configured schedule.
 
-- **Level 1 (one agent):** the same agent, in a fresh turn, with a brief that says "you are looking for what is missing; do not re-verify what is present". Fresh context matters more than a different model.
-- **Level 2 and up:** {{GAP_ANALYSIS_LANE}}
-- **Level 3:** make it recurring. A weekly audit job enumerates live state (lanes, jobs, services, model lists), diffs it against the plan, and files a report. It catches the dead lane and the silently renamed model nobody noticed.
+## Resolve reported gaps
 
-## The second half: analyze, compare, suggest
-
-Once the gaps are named, for each lane or component: what does it give, is there a cheaper, better or faster alternative, and what is the best paid option beside the free default. Parked is fine; unshown is not.
-
-## Anti-patterns
-
-- Treating a green test suite as a gap analysis. Tests verify presence; they cannot see absence.
-- Asking the model that wrote the thing whether it is complete, in the same context. It will say yes.
-- Reporting gaps you did not verify. A gap is a finding; it needs the same evidence a bug does.
+When a gap is reported, verify the claim against the artifact before assigning a change. Keep unverified observations separate. When a gap changes the approved scope, return the decision to the user; when it is already in scope, complete it and rerun its acceptance check.

package/templates/common/protocols/memory-and-record.md

@@ -1,30 +1,31 @@
-# Memory and record: the store is part of the change
+# Memory and record: keep durable information findable
 
-Every protocol here ends in a write: the end-to-end doc, the rename that lands everywhere, the research brief, the gap report. A write that nothing indexes is a note in a drawer. This protocol says how the store is kept honest, whatever the store is.
+When writing durable information, search existing records, update their index and use one writer for the shared record.
 
-Companion tool for this rule: **obsidian-tc**, {{OBSIDIAN_TC_STATUS}}.
+Optional companion: **obsidian-tc**, {{OBSIDIAN_TC_STATUS}}.
 
-## Rules
+## Record a change
 
-1. **Search before you write.** A research brief, a decision, a rule: check whether it already exists (`semantic_search` for the concept, `search_text` for the exact phrase). Duplicates are how a store starts lying: two notes, two answers, and a reader picks one.
-2. **The folder index is part of the change, not a follow-up.** Every folder has one index file that says what is in it and what state it is in. Any write, edit or delete reopens that index in the same pass and corrects whatever the change made untrue. A stale index is worse than a missing one because agents believe it.
-3. **One writer per run.** Several agents may propose; one records. If you are not the writer, produce the file and name it in your report.
-4. **Machine output stays out of the index.** Scan dumps, logs, traces embed well and outrank the thing they describe. Keep them outside the searchable store, or in a folder the index excludes.
-5. **A record is not present state.** A note, a ticket, a checkbox is a dated observation. Re-read the live thing before you act on it.
-6. **Inferred content is marked as inferred.** A conclusion an agent reached, rather than copied from a source, carries `source: agent-synthesis` (and, with obsidian-tc, goes through its poison scan before it lands). A reader must be able to tell a quote from a guess.
-7. **Compare-and-swap on overwrite.** Read, then write with the hash you read. A blind overwrite of a note someone else changed is a lost update nobody notices.
+1. Search for the concept and exact phrase before creating a new record. When a matching record exists, update it within the granted scope.
+2. Read the owning folder's index and correct any description, status or link changed by the work.
+3. Assign one writer; have other lanes return proposed edits with evidence.
+4. Keep machine logs and raw traces outside the curated record index, or in an explicitly excluded folder.
+5. Before acting on a dated record, probe the current state it describes.
+6. Mark synthesis and inference distinctly from source quotations.
+7. Before overwriting, verify the current version or content hash. If it changed since the read, reconcile the changes first.
 
-## Where the other protocols touch the store
+## Connect records to work
 
-| Protocol | Store call |
+| Workflow | Record action |
 |---|---|
-| Propagate, step 1 | `get_backlinks` on the thing being renamed; `search_text` for the literal old term; after the change, `find_unresolved_links` |
-| Build, Stage 7 | the end-to-end doc goes in the folder that owns the domain; its index is updated in the same pass |
-| Deep research, step 4 | `semantic_search` before the brief is written; a hit means append to the existing note, not a second note |
-| Gap analysis | the "what exists" enumeration starts from the store, then diffs against the live state |
+| Shared rename | Search references and backlinks, then check for unresolved links |
+| Build report | Store the operations document in its owning folder and update the index |
+| Research | Search existing coverage and attach new verified evidence |
+| Coverage check | Compare recorded scope against the current artifact |
+| Decision | Record Did / Why / Serves / Rejected with evidence |
 
-## Without obsidian-tc
+## Local record workflow
 
-The rules still bind. `grep -rn` is your literal search, a folder README is your index, `git` is your compare-and-swap. What is not allowed is a write nobody can find again.
+When obsidian-tc is absent, use scoped file search, a folder README and version control. Before editing, compare the file with the version you read; version control alone does not prevent a concurrent lost update. Keep writes within the task's authorized paths.
 
-Source: https://github.com/The-40-Thieves/obsidian-tc
+Companion source: https://github.com/The-40-Thieves/obsidian-tc

package/templates/common/protocols/numbers-and-logic.md

@@ -1,35 +1,29 @@
-# Numbers and logic: compute, never guess
+# Numbers and logic: compute decision inputs
 
-**Never do arithmetic in your head when being wrong would matter.** Money, rates, percentages, margins, budgets, token and cost counts, any comparison you are about to state, any complexity or equivalence or speedup claim, anything past 2^53. A wrong number that looks right is worse than no number, because it gets acted on.
+When a number or logical claim affects a decision, compute it with an appropriate tool. This includes money, rates, percentages, budgets, token counts, comparisons, complexity, equivalence and performance claims. Trivial single-digit sums can be stated directly.
 
-A model that is confident about `0.1 + 0.2` does not feel uncertain. It feels finished. The tool exists so the feeling is not the check.
+Optional companion: **codecalc**, {{CODECALC_STATUS}}.
 
-Companion tool for this rule: **codecalc**, {{CODECALC_STATUS}}.
+## Select the check
 
-## When calling is mandatory
-
-| You are about to | Use |
+| Claim | Verification |
 |---|---|
-| state a number someone will act on | `evaluate_expression` (exact rationals, no float drift) |
-| say A is bigger, cheaper, faster than B | compute both, then compare; never eyeball |
-| claim two programs behave the same (a port, a rewrite) | `verify_translation` |
-| claim an optimization preserved behaviour | `verify_optimization` |
-| state a Big-O, or that something scales | `analyze_complexity` (static) or `benchmark` (measured) |
-| assert a logical property holds, or that a set of constraints is satisfiable | `z3_check` (SMT) or `truth_table` |
-| run a snippet to see what it actually does | `execute_code` (31 languages, sandboxed) |
-
-Trivial single-digit sums are exempt. Everything else is not.
-
-## How to report a computed figure
-
-Give the exact form and the decimal, and say which tool produced it. `37/210 = 17.62%` reads differently from `about 18%`; the first can be checked, the second cannot. If a tool returned `unenforced` or a grade below its top, say so beside the number.
-
-## Logic flow
+| A figure someone will act on | Exact arithmetic with a calculator, interpreter or spreadsheet |
+| One option is cheaper, larger or faster | Compute both values and their comparison |
+| A port preserves behavior | Relevant tests or `verify_translation` |
+| An optimization preserves behavior | Regression checks or `verify_optimization` |
+| Complexity or scaling | Source analysis or `analyze_complexity`; benchmark measured performance |
+| A logical property or constraint holds | An appropriate solver such as `z3_check` or a truth table |
+| A snippet behaves a certain way | Run it with `execute_code` or the project's local runtime |
 
-Reasoning scaffolds help models that have no native reasoning mode and add nothing to models that already think before answering. So: do not narrate a chain of thought as evidence. **The authorising evidence is the computed outcome, not the thought log.** When a decision hangs on a logical claim, encode the claim and check it (`z3_check`); when it hangs on behaviour, run it (`execute_code`); when it hangs on a figure, compute it. A trace that was never checked is a story.
+When using a companion command, probe that tool's current schema before calling it. When codecalc is absent, use the local runtime, test suite, spreadsheet or a suitable calculator.
 
-## Without codecalc
+## Report the evidence
 
-The rule still binds. Use whatever computes: a shell `python3 -c`, a spreadsheet, the vendor's built-in interpreter. What is not allowed is the number that came from nowhere.
+- Give the input, exact result and useful decimal representation, with method and source.
+- For measurements, name the script, sample size, environment and date.
+- When a tool reports a limit or an unenforced property, state it beside the result.
+- When a claim cannot be computed or checked from available evidence, mark it UNVERIFIED.
+- When a decision depends on logic, report the checked property and result. Keep private chain-of-thought out of the evidence record.
 
-Source: https://github.com/The-40-Thieves/codecalc
+Companion source: https://github.com/The-40-Thieves/codecalc