control-surface/protocol/AGENTS.shared.md at main · apexSolarKiss/control-surface

Source-of-Truth Boundaries

Repo = project truth: artifacts, decisions, docs, templates, examples.
AGENTS.md = workflow rules for repo execution, resolved as: this shared core + applicable profiles + opt-in fragments + repo-local delta.
Grounding note (external) = repo-external context: intent, audience, philosophy, foundational premises, durable loose threads.
Per-conversation / task state (ChatGPT thread history, task lists, in-flight session context) = ephemeral; does NOT belong in the grounding note.
Private agent memory (e.g. Claude Code's MEMORY.md) = non-authoritative operator context. It MAY retain ASK-authorized incidents, anti-re-derivation pointers, worked examples, refusal/supersession records, tool/vendor occupancy, and other operator context within that memory's authorized owning surface — but it NEVER owns durable project truth or workflow protocol (see §Verification Claims). Wall-bound material remains on the owning side of the wall; this rule creates no cross-wall read, copy, or retention authority. Retention conditions and the authorization required for any memory write are governed by §Learning Disposition and §Private-Memory Write Gate.

Aging-Rate Principle

The split between repo, AGENTS.md, grounding note, ephemeral per-conversation / task state, and non-authoritative private agent memory is separation by aging rate.

A doc that tracks state ages fast and must be refreshed often.
A doc that points to state ages slowly and stays useful across many sessions.
A rules doc that contains rules only ages slowly.
A context doc that contains context only ages slowly.
A doc that mixes rules, context, and state ages at the rate of its fastest-aging contents — usually badly.

If a statement would become stale when a PR lands, a chain closes, or a next path changes, it does not belong in this file or in the grounding note.

The same principle governs pointers and state. A pointer that copies state it does not need becomes a tracker of state it does not own, and ages at that source's rate; a pointer that drops an identity something depends on removes the only means of noticing the source moved.

A discovery reference names the exact locator, role and owner, and is read live.
Where continuity, comparison, review, authorization or recovery depends on a particular prior state, retain a sufficient identity of the exact bounded prior state the operation depends on, read the owner live at use, and reconcile any movement before proceeding.
The governing gate or owner contract defines that identity. Where neither does and the operation still depends on detecting movement from a prior state, use a full SHA-256 of the exact bounded bytes. Add byte size only where truncation or incomplete transport is a named failure mode. If the operation needs only current truth, no prior-state pin is required — ordinary discovery does not acquire a hash merely because its source is mutable. An identity used to satisfy a gate is full-length. A prior pin is prospective evidence: never reconstruct a missing pin after the interval it was supposed to guard; where that interval matters to the decision, report it as unverified and stop.
A shorter owner-qualified provenance reference may aid navigation where the owning contract permits it, but it is not gate evidence until resolved to the full identity.
A manifested package is normally referenced by its manifest identity; repeat a member identity only where that member independently changes the decision, or becomes the separately approved or landed byte source.
Freeze mutable state only where comparability requires it — blind parallel reconstruction, for example — and freeze only the bounded state needed.
Do not add metadata unless it changes a decision, detects a named failure mode, or supports recovery from a named failure.

Evidence localization and pointer economy. Declare each load-bearing identity once, in the nearest block that owns the gate, and use a stable local label afterward. As applicable, that block names the review object, the prior-state base, the operative target set, the authoritative representation of the change, and the proof result.

Do not recopy full paths, hashes, byte sizes, baselines, target inventories, or unchanged-surface inventories merely to make later sections appear self-contained. Repeat an evidentiary field only where that occurrence independently changes a decision, detects a named failure mode, supports recovery, crosses a separate consumer or transport boundary that cannot resolve the original declaration, or is required by a specialized contract.

Use the minimum identity sufficient for the pointer's function:

discovery reference        exact locator + role + owner
exact review identity      locator + full SHA-256, declared once
stale-base gate            owner/ref + exact state identity
truncation-risk transport  byte size + full SHA-256
later narrative reference  stable local label

A hash is not the default companion to every path. Byte size is not the default companion to every hash. Repetition is not corroboration: every duplicated evidentiary fact is another claim that can drift, and localizing evidence reduces the number of independent surfaces on which the same fact can be wrong.

Specialized contracts keep their own field sets. This rule governs what a pointer carries in general. §PR Creation, §Advisor-Readable Review Objects, the inter-session coordination runbook, a registry's structural contract, and a package's own manifest each define the fields they require, and those govern where they apply.

Movement of a mutable source is classified on two axes — never from net growth, shrinkage, mtime, or actor attribution alone:

EVIDENCE
  ACCOUNTED                  every changed limb is bounded and explained by a
                             named durable owner, PR, receipt, restore operation
                             or row-scoped state transition, and required
                             structure and protected invariants still hold
  UNACCOUNTED / DESTRUCTIVE  any changed limb lacks a durable explanation,
                             expected material disappeared, structure, parity or
                             identity failed, or the change escaped its claimed
                             scope

AUTHORITY
  COVERED                    the current ASK envelope and applicable review
                             window cover proceeding from the resulting live state
  NOT COVERED                the movement may be legitimate, but it moved beyond
                             the authorized or reviewed state

ACCOUNTED + COVERED          reconcile and proceed
ACCOUNTED + NOT COVERED      stop for fresh ASK authority and/or review
UNACCOUNTED / DESTRUCTIVE    stop, regardless of authority

Learning Disposition

When a reusable learning appears — a correction, a discovered constraint, a convention, a calibration, a failure and its remedy — classify it before deciding where it is retained. Classify per claim limb: one observation often carries a shared rule, a local exception, current state, and historical provenance at once, and those limbs do not share a destination.

Route each limb to its visible durable owner:

shared workflow rule → the owner canonical at apexSolarKiss/control-surface/protocol/; classify it as shared core, an applicable profile, an opt-in fragment, or an explicit hold before changing any resolved consumer
project-local workflow rule or exception → the owning repo's AGENTS.md local delta
project truth, guidance, architecture, implementation contract, or maintained procedure → the owning repo's code, tests, or docs
cross-surface maintenance state, pins, obligations, propagation, or currency → the applicable operator ledger; ordinary project state remains with the owning repo
event, experiment, failure, review disposition, or closure evidence → the owning surface's scratch, a PR record, or a named closure artifact
slow external intent, audience, or durable external constraint → the owning grounding note
temporary task state → current task state only, then no retention
an unearned generalization → an explicit nomination or hold
material that earns no durable retention → no retention

Private agent memory is not a durable owner, protocol-candidate inbox, state ledger, or pre-absorption staging surface. It becomes a candidate only after the visible-owner test establishes either:

a durable owner has intentionally omitted the non-operative residue; or
no visible owner is appropriate because the payload is machine-local, wall-bound, or deliberately non-operative.

The absence of a visible owner never authorizes memory to carry knowledge required for correctness.

Subject to §Private-Memory Write Gate, private memory may retain narrowly scoped origin or incident history, refusal or supersession evidence, worked examples, evidence of a local exception whose operative rule or constraint is visibly owned, machine-local calibration, machine-local or deliberately non-operative tool/vendor occupancy whose structural role and durable procedure are visibly owned, anti-re-derivation pointers, and wall-bound residue within the memory's authorized owning surface.

Removing private memory may make an executor slower. It must never make an executor wrong. If a decision cannot be made correctly without a memory entry, that entry carries operative knowledge and is in the wrong place.

A generic request to "remember this" requests durable retention, not a predetermined storage surface. Classify and propose the appropriate owner. Only a request that explicitly names private agent memory, followed by ASK's approval of the exact target and payload, authorizes that destination.

Private-Memory Write Gate

Default deny. A private-memory mutation is a separate approval unit. It may occur inside an explicitly scoped memory-maintenance operation, but it is never incidental to another task, inferred from another approval, or added during task closure.

For this rule, a private persistent mutation means creating, editing, or deleting any governed auto-memory, subagent-memory, user-instruction, user-rule, or gitignored local-instruction artifact. References below to a private-memory mutation use that broader meaning.

This gate governs private persistent agent surfaces: auto-memory stores and their indexes, subagent memory, and private instruction files that load across sessions without repo review — user-scope instructions and rules, and gitignored local instruction files. A checked-in repo adapter is not one of these: it is a visible carrier under ordinary diff and review gates.

A private persistent instruction imported from any other path is governed by this gate as well. It must not be used unless its exact path is declared, a matching Edit(...) ask rule is installed, and the active-session receipt classifies it as covered. A private import outside the standard guarded paths is a stop condition.

Any governed private persistent creation or edit requires all of:

the learning has been classified under §Learning Disposition and its visible owner has been named;
a stated reason the visible owner is insufficient for the residual payload;
the exact target and exact proposed mutation, shown before execution: full payload for creation; exact diff or replacement payload for an edit;
explicit ASK authorization of that exact target and exact mutation;
a recorded aging or review trigger.

Any governed private persistent deletion requires all of:

the artifact's current role and disposition have been classified, including its visible owner or a no-retention result;
a stated reason deletion is warranted — for example unauthorized creation, supersession, owner absorption, or expiry of its review trigger;
the exact path plus a pre-deletion size/hash receipt and, when restoring a prior state, the exact baseline bytes or diff;
explicit ASK authorization of that exact deletion;
a post-operation absence receipt, or exact restored-byte/hash verification when deletion is one step in a rollback.

Approval of a plan, a diff, a PR, a merge, or a task completion is not authorization of that private persistent mutation. Neither is advisor agreement.

Authorization is per artifact. Approval of a topic file does not authorize an index entry, and approval of an index entry does not authorize the topic file. Every created, modified, or deleted artifact requires its own displayed change or deletion receipt and its own ASK decision. Never select a session-wide or standing approval for a governed private persistent path, including "allow Claude to edit its own settings for this session."

Live credentials, authorization tokens, private keys, and other secrets are never admissible payloads for a private persistent surface or for any disposition record.

Specifically prohibited without the authorization above:

banking "one durable note" at task close;
using memory as a protocol-candidate inbox;
post-merge memory mutation framed as cleanup;
automatic index (MEMORY.md) updates.

Do not bypass the gate through Bash, Python, Node, another subprocess, a helper agent, or an alternate write tool. Subagents, census agents, staging agents, and read-only workers never perform private persistent mutations; they return the candidate learning and proposed disposition to the parent coordinator.

Denial stops the mutation, not unrelated work. When ASK denies, withholds, or has not supplied authorization for a private persistent mutation, do not retry it through another tool or surface. Omit that mutation and continue the unrelated task to the extent the task remains independently authorized and technically possible. Stop the broader task only when its completion actually depends on the prohibited mutation, and state that dependency explicitly. This narrows only the response to the denied mutation itself; every pre-flight coverage requirement and stop condition of this gate is unaffected.

Before memory-bearing work, confirm that the required ask rules are active and that every governed private persistent path — including the effective auto-memory root and every loaded private instruction import — is covered. Missing rules, unmatched rules, or an uncovered governed path are stop conditions.

Do not perform private persistent-context maintenance in a mode that disables the runtime's safety checks. This is defense in depth: explicit ask rules currently still apply in that mode, but the gate must not depend on one product carve-out while other checks are disabled.

Where the runtime enforces this gate with a permission prompt, treat the prompt as the technical gate only. The visible disposition above is the semantic gate, and a runtime status message is not evidence that a write did or did not persist — verify the filesystem.

Required Reading Before Meaningful Work

Before any meaningful repo work, read:

this repository's README.md;
this AGENTS.md — the shared execution-protocol core and this repo's own Required Reads named in its local delta;
the repo-local Required Reads and architecture docs that delta names.

For external context, read the grounding note. Then read whatever templates, prompts, examples, milestones, or findings are relevant to the task.

A named-but-unread governing source is a defect, not a caveat. Retrieve it before producing the governed output. If the active authority explicitly waives the read or the source is technically unavailable, state that fact, the reason, and the resulting limit in the same turn.

A declared read order is not a cost-benefit input. Skip it only on explicit waiver or unavoidable unavailability. Never silently substitute a live sufficiency judgment or close by proposing the required read as future work.

Inbound Handoff TBI Marker

-TBI is human ASK's terminal outstanding-feed-obligation overlay. It answers one operator question from a directory listing: does this exact artifact still need to be fed into an active recipient-project thread? It means the current feed obligation remains unsatisfied — no attempt has yet succeeded for this obligation, whether because none has occurred or one failed to produce ingestion. It says nothing about earlier successful feeds or prior ingestion history. It is not a statement about disposition, repo ownership, or pending repo work. Copy + suffix do not authorize implementation.

The overlay is orthogonal, not a lifecycle step. -TBI sits above whatever the artifact already is — a fresh routed handoff, a provenance transcript, an ordinary report, a canonical carrier, or an artifact already carrying a durable disposition — and importing it borrows no other class's lifecycle. It is always the final token before .md, because it is the flag ASK scans a directory for.

Route on approval; feed/ingest later. Once ASK approves a recipient-facing handoff memo's substance, the origin routes the recipient -TBI copy immediately unless ASK explicitly directs that routing itself be held. Routing is complete when the exact copy exists at the declared intake path. Routing is not feeding or ingestion: it places the artifact in ASK's logical outstanding feed-obligation queue, and ASK separately decides when to feed it into the recipient's active surface. Do not defer routing until the recipient is ready, its workload clears, or a later operator pass. This timing rule expands no write authority: use a declared ingress aperture where one exists; otherwise return the exact recipient artifact to ASK immediately for routing.

Four events, not two. The full first-ingest-and-classify path for a fresh routed handoff distinguishes four distinct events, each with its own actor and its own evidence:

routing     the origin makes material durably available in the recipient's intake
            — candidate availability, nothing more
feeding     ASK hands the material to the recipient's active surface — the operator-side act
ingestion   the recipient surface reads the exact artifact into active context —
            the resulting state when a feed succeeds, recorded by renaming
            `-TBI` to `-ingested`
disposition the recipient classifies the material and records the resulting durable
            disposition — absorption is one of them, not the name for all of them

A fresh routed handoff may instead exit before ingestion through -supersededA, either before feeding or after a feed that did not result in ingestion; the four-event path is what a fresh handoff traverses when it is ingested and classified, not an inevitability of routing. Anything not currently in that state never enters it — including a routed instance whose first ingestion already occurred — and resolves the overlay under §Resolving the feed-obligation overlay instead. Collapsing any adjacent pair of the four is the failure this rule corrects.

Feeding and ingestion are paired but not atomic. Feeding is ASK's act; ingestion is the recipient-side state that results when the feed succeeds. Ingestion is not a proactive election by the surface — the surface does not decide to ingest, it ingests because it was fed. A feed can fail, be deferred, or be superseded before the recipient acts. Feeding therefore expresses the intent to have the material ingested and is never itself ingestion evidence — queue exit occurs on recipient-side ingestion, not on the feed attempt. Ingestion is likewise not disposition, and disposition is not implementation authority.

Feeding by value or by reference. ASK feeds either by attaching or pasting the content, or by supplying the exact path, which the recipient then resolves through a connector or by reading the filesystem. Both are valid feeds; a bare exact path addressed to an active surface is a feed. Ingestion still requires the recipient to retrieve and read the artifact:

path resolves    ≠ content read
content read     ≠ exact-byte identity proven

A failed retrieval, or a path resolving only to metadata, has not produced ingestion. A lossy or normalized view may constitute content read under a bounded fidelity claim; where the omitted portion could affect classification, obtain an adequate representation first.

The relay envelope governs force and scope. Feeding is a relay that carries an external payload, and the envelope — not the payload — determines whether the recipient is to read, classify, review, execute, hold, or otherwise act. Mere inclusion of an artifact does not make every proposition inside it operative intent.

The state machine.

-TBI  →  -ingested                 ingested — content read into active context;
                                   the rename records it, it does not cause it
-TBI  →  -supersededA              ASK-side PRE-ingestion retirement disposition:
                                   retired before ingestion, never consumed
-ingested  →  terminal disposition -absorbed · -held · -declined · -withdrawn ·
                                   -routed · -no-route · -closed · -supersededP

For a fresh routed handoff, the recipient's first lifecycle mutation after successful content read — before any classification work begins — is the in-place rename from -TBI to -ingested. Rename only; it records nothing about what was later absorbed, held, declined, routed, or superseded. For anything not currently in that state, the same read removes only -TBI: a feed-obligation filename mutation, not a routed-instance lifecycle mutation.

Disposition is not absorption. Absorption is one possible disposition; -held, -declined, -withdrawn, -routed, -no-route, -closed, and -supersededP record different outcomes. ASK may retire a fresh routed handoff before ingestion; the recipient owns post-ingestion disposition.

Resolving the feed-obligation overlay. A successful content read of the marked payload, by the intended active recipient surface, under ASK's feed satisfies the current feed obligation. A source-side inspection — reading a governing record, verifying bytes, or consulting an inspection copy — does not satisfy it, though it may supply the identification or verification evidence the preflight below requires. The filename resolves once governed role and prior lifecycle state are established; the read and the rename are distinct events:

verified fresh routed handoff awaiting first ingestion
    -TBI becomes -ingested

anything else with established role and prior state
    remove only -TBI; the underlying role and durable disposition survive unchanged

role or prior state unresolved
    stop before feeding

Establish governed role and prior lifecycle state; do not infer either from the filename. Stripping -TBI and finding no other suffix does not establish a fresh routed handoff, and neither does inbox residency. Role alone is not enough: a known routed handoff whose prior ingestion state is unresolved leaves the branch unresolved, because the discriminator is the fresh-awaiting-first-ingestion state, not the artifact class — topic-absorbed-TBI.md → topic-absorbed.md is a routed instance by class and still takes the removal branch. An unresolved role or prior state is a stop condition, and removal-only is not a safe default there, because the unresolved artifact might be a fresh routed handoff — and one may never become bare and unmarked. Identify and establish are the verbs for this operation; classification is reserved for the later recipient-owned disposition decision.

Truth preservation and contractual locators. An in-place overlay is valid only where resolving it leaves an underlying filename whose claims remain true and no contractual locator breaks. Two cases fail that test, and their remedies differ by which operation does the damage: a historical -supersededA artifact is falsified by the recipient-surface read, so preserve the original untouched and feed an addressed copy or a reference-bearing derivative — source-side verification and the copying needed to build it are unaffected; a fixed-path carrier (_INDEX, _STATE.md, a grounding-note canonical, any locator another surface resolves by exact path) is broken by the rename, so feed the original by reference at its stable path and leave its name alone.

Already-read recovery. If an unidentified marked artifact was read into the intended recipient surface anyway, the feed obligation is already satisfied and a retained -TBI no longer states it truthfully — but removing it and appending -ingested are both still unavailable, because either would assert a role or prior state that has not been established. Record the successful read and the unresolved-role/state exception, treat terminal -TBI alone as temporarily non-authoritative feed-obligation evidence, and resolve the overlay immediately once role and prior state are established. The demotion is confined to that axis: the underlying artifact identity and any truthful durable-state marker remain authoritative under their own rules. This is bounded error recovery, not a second normal path.

A re-feed is a genuine new ingestion event. It does not reopen, reclassify, erase, or advance the underlying durable disposition, and it converts no artifact class into another. Removing a satisfied feed obligation is not a disposition change.

Canceled feed obligation. ASK may cancel an overlay without any content read, by removing terminal -TBI alone. Cancellation is ASK-side and touches nothing but the flag: it is not ingestion, not a disposition, and not a decline — decline is the recipient's classification verb and maps to -declined. It is available only where the underlying artifact already has an independently complete identity or durable state. A fresh routed handoff may never become bare and unmarked this way — it still requires an explicit pre-ingestion disposition, and -supersededA remains the named-successor displacement case.

Closure and the terminal rename are one bounded operation. Every transition from -ingested to a terminal disposition suffix requires a durable disposition record made in the same operation — a dated scratch memo or an appended terminal section in an explicitly maintained program or status record; do not create an artifact solely to satisfy form. A rename is not a disposition record, and a record without the rename leaves the filename lying. -supersededA is the one exit needing no absorption closure, because no recipient absorption occurred — but it still requires an explicit lineage or current-status record naming the successor.

Marker grammar. Terminal -TBI is always the final token before .md. Everything else belongs to the underlying filename and precedes it — stem, _vN version index, artifact-role marker (-PTX), addressee marker (-4ASK, -4TMK), and durable lifecycle state:

<otherwise-complete-underlying-filename>-TBI.md

topic-PTX-TBI.md        →  topic-PTX.md        role survives resolution
topic-PTX_v2-TBI.md     →  topic-PTX_v2.md     role + version survive
topic-absorbed-TBI.md   →  topic-absorbed.md   disposition survives
topic-handoff-TBI.md    →  topic-handoff-ingested.md   fresh handoff only

Within the underlying filename the lifecycle suffix is last, and an addressee marker precedes it and is never stacked after it. A -PTX may carry the overlay: feeding a transcript does not make it a routed handoff, and resolving the overlay returns it to its role marker unchanged. Ordinary disposition words are lower-case; supersession uses the lower-case superseded stem plus the ruled uppercase phase qualifier A or P.

Structural artifacts inside a declared intent inbox. Within a declared intent inbox, an artifact is exempt from the routed-instance lifecycle only when the surface's current structural contract explicitly names it as structural. A leading _ alone confers no exemption. Before ingesting a routed artifact, the recipient surface reads and honors any current inbox-state carrier that contract declares. Structural artifacts take no handoff lifecycle suffix and are excluded from routed-artifact queue counts.

This lifecycle grammar is prospective. Historical filenames retain the conventions in force when they were created and are not normalized; legacy tokens do not acquire the meanings defined here.

The queue is logical, not a folder. The one marked payload may sit in an ASK-side staging area, an origin scratch location, a transit surface, or the recipient's declared intake path. That describes where the designated payload may be located; it does not place a retained sender or provenance copy in the queue. The -TBI marker attaches when that payload enters the queue, wherever that is; relocation within the queue is not a lifecycle event and neither applies nor re-applies a marker. Arriving in the intake folder is a move within the queue, not an entry into it and not an exit from it. A fresh routed handoff leaves the queue by ingestion (-TBI → -ingested) or by pre-ingestion retirement (-TBI → -supersededA); any other artifact leaves it when the overlay is resolved or canceled, its underlying filename unchanged.

One obligation, one marked payload. -TBI attaches only to the exact artifact instance ASK intends to feed. In a two-copy handoff, the retained origin or provenance copy stays unsuffixed; only the recipient-bound copy carries the overlay. Byte-identical files at two paths are two artifact instances. Location alone never creates queue membership, and one outstanding feed obligation is represented by exactly one live marked artifact instance.

Move is not copy. A byte-preserving move or rename of the designated payload within the queue preserves the same marked instance and is not a lifecycle event. Copying creates another artifact instance and neither transfers nor duplicates designation by itself. If ASK designates the new copy as the payload, the same bounded operation must leave exactly one marked instance: a retained origin or provenance copy stays or becomes unsuffixed; any former temporary transport instance is removed or resolved according to its underlying role and prior state. A fresh routed handoff is never left bare merely to transfer designation. A file in origin scratch may carry -TBI only where that exact file is itself the designated payload — for example, a PTX, report, or other independently complete artifact ASK intends to feed — or a distinct temporary recipient-bound transport instance.

Recipient lifecycle does not mirror onto provenance. -ingested, -supersededA, -supersededP, and terminal routed-handoff dispositions belong to the recipient routed instance. A retained origin or provenance copy is not renamed to match them; the recipient outcome is recorded through the recipient artifact and any separate lineage or disposition record.

Supersession has two phases, and the marker encodes which. This applies to a fresh routed handoff awaiting first ingestion; anything not currently in that state exits the queue by overlay removal or cancellation, never by acquiring a supersession suffix. For such a handoff, ingestion is not the only exit: at any point before ingestion — including after a feed the recipient surface never ingested — ASK may instead retire it as -supersededA. A -supersededA artifact was never ingested and never absorbed; it carries no pending work and remains in the intake only as lineage, typically beside an active successor carrying its own -TBI. A -supersededP artifact was ingested — its lineage records that the recipient read it before a successor displaced it, which is a materially different history and is why the phase is encoded rather than flattened. Neither disposition authorizes implementation, and neither is reactivated, re-ingested, or renamed off merely because the file remains physically present in the intake.

Historical body versus current disposition. A received handoff body is byte-immutable: it is not edited on ingestion, on supersession, or at closure. A sender-authored in-body status line records the routing-time state and stays historical evidence; it is not rewritten because the recipient later ingested or superseded the artifact. Current evidence sits on two axes, and they are not interchangeable:

underlying filename       artifact identity / role + PRIMARY durable-state marker
                          where the class has one — `-ingested` read-but-not-closed ·
                          terminal disposition suffix · `-supersededA`
                          retired-unconsumed · `-supersededP` ingested-then-displaced

terminal -TBI             INDEPENDENT, FASTER-AGING evidence of ASK's outstanding
                          feed obligation. Not a disposition; excluded from the
                          disposition-agreement check below

disposition / lineage     SECONDARY current evidence — must agree with the
record                    UNDERLYING DURABLE-STATE MARKER, never with terminal -TBI

received body             HISTORICAL — immutable, plus any sender routing-time status

Every current disposition carrier must agree with the underlying durable-state marker and with every other current carrier. Terminal -TBI neither participates in nor overrides that check — topic-absorbed-TBI.md asserts two simultaneously true things on two axes: durable disposition absorbed, feed obligation outstanding. An immutable body's historical routing-status string is not required to match a later recipient disposition; successor linkage belongs in a disposition or explicit lineage record, never in a post-receipt edit to the received body.

Do not create a -TBI addressed to a surface the acting surface already operates — as a handoff marker. Moving between repos inside one operating surface is a hard repo-boundary reset — read that repo's grounding note and AGENTS.md, verify live state, work under its own branch, diff, review, and merge gates. A handoff addressed back to the surface that authored it tracks nothing: the destination already has the material, so no cross-surface handoff boundary was crossed.

Two boundaries, not one. That prohibition is about the handoff, not the overlay:

cross-surface handoff boundary   crossed when material moves between separately
                                 operated surfaces — what -TBI-as-handoff tracks

active-context ingestion         crossed when a particular active thread reads a
boundary                         payload into its context — what a feed produces

Same-surface movement crosses the first not at all. It may still require a feed into a particular active thread, and when that thread reads the payload under ASK's feed, ordinary active-context ingestion occurs — creating no handoff, no candidate source-of-intent relation, and no repo authority. ASK may therefore apply the orthogonal terminal -TBI overlay to an eligible same-surface artifact, or to an addressed copy of one, when that exact artifact still needs to be fed or re-fed.

Separate repo authority is real and unaffected by this rule. It does not create a separate cross-surface handoff boundary. Pending owner classification or repo action is repo state — carried by the closure, the relay, or task state — not -TBI state.

Method-altitude articulation: method-ASK/docs/source-of-intent.md §Inbound handoff TBI marker.

Provenance Transcript PTX Marker

A filename ending in -PTX.md or -PTX_vN.md identifies an ASK-assembled Provenance Transcript: a record of a source conversation or cross-surface exchange, retained for lineage and later verification.

The -PTX segment is the artifact-role marker. An optional _vN suffix records the version of the transcript artifact itself. It does not make the artifact a model draft or draft-zero, and it confers no lifecycle state or authority.

A -PTX artifact is not a canonical, a model draft or model draft-zero, a versioned canonical snapshot, a handoff, an approval or execution instruction, or an ingestion-state marker.

-PTX.md is an unversioned singleton transcript.
-PTX_vN.md is a numbered member of an explicit transcript version lineage. _v0 means the first numbered PTX version, not draft-zero.
Infer version precedence only from an explicit _vN, never from the -PTX marker itself.
Neither -PTX nor _vN establishes whether the transcript is still being assembled, complete, closed, or frozen. PTX lifecycle and version progression are ASK-owned; do not edit, extend, rename, close, freeze, or advance a PTX unless ASK explicitly directs the exact operation.
The PTX files are themselves the lineage; do not create a separate canonical-plus-snapshot chain for them.
Do not absorb a PTX as project truth without classification.
If the transcript creates work for another surface, route a separate handoff for that work. A -PTX may itself carry the terminal -TBI overlay when ASK still owes a feed of that exact transcript, but doing so flags a feed — it does not turn the transcript into a routed handoff, and resolving the overlay removes only -TBI.
The convention is prospective. Historical transcripts are not renamed for conformance, so the absence of -PTX does not establish that a file is a model draft — classify an unmarked artifact from the file and its scratch context before versioning or superseding it.

Forms:

YYYY-MM-DD_<surface-or-subject>_<topic>-PTX.md
YYYY-MM-DD_<surface-or-subject>_<topic>-PTX_vN.md

-TBI, -PTX, and _vN do not share an axis: -TBI is a terminal feed-obligation overlay — for a fresh routed handoff its resolution is -ingested, or -supersededA on pre-ingestion retirement, and for every other artifact it is simply removed; -PTX is an artifact role, retained throughout any version lineage and through overlay resolution; _vN is an optional version index for the transcript artifact. Because they are separate axes, topic-PTX-TBI.md and topic-PTX_v2-TBI.md are valid — a transcript with a feed owed, not a routed handoff. Neither -PTX nor _vN confers state, authority, or canonical status.

Cross-Surface Change Routing

Before choosing direct operation or -TBI routing, first establish whether the material crosses an operating-surface boundary at all. Only then classify the change's authority and the surface's write jurisdiction.

Destination inside the same operating surface → no -TBI as a handoff marker, under any authority class. Change repo context through a hard repo-boundary reset and operate the owning repo directly under its own gates. Answer this test first; a yes disposes of the routing question on its own, and the authority and jurisdiction tests below never run. It does not dispose of feeding: ASK may still apply the orthogonal terminal -TBI overlay to a same-surface artifact that must be fed or re-fed into an active thread.
Candidate source-of-intent, project-specific direction, or other material whose recipient must classify → preserve the origin record, route a recipient copy into the recipient's intent inbox — at the exact live path that surface's index declares, intent-INbox/ being the target convention — with -TBI, and let the recipient surface own ingestion and post-ingestion disposition. This branch presumes the recipient is a different operating surface; recipient-owned classification inside one surface is a hat swap, not a handoff.
ASK-authorized conformance to a protocol owned upstream → propagate directly only where the active surface has write jurisdiction over the consumer. Apply the change through the consumer repo's own branch, diff, PR, review, and merge gates. Do not create a -TBI handoff merely to carry an already-authoritative protocol update.
No direct write jurisdiction → route to the owning surface even when the upstream protocol is authoritative. Protocol ownership does not pierce a wall, create a grant, or bypass a surface boundary.

Write jurisdiction may be standing or explicitly granted by ASK for the scoped conformance change. Neither protocol ownership, connector capability, nor this rule itself creates write jurisdiction over another surface.

A declared ingress aperture plus ASK's exact relay is sufficient for the scoped placement. Where a recipient surface's owner declares a create-only ingress aperture, ASK routes by relaying the exact routing operation to the authorized executor — the relay is the routing grant, and neither ASK nor the recipient owner is asked to authorize the same route again. Any ASK-operated origin surface — including a separately operated one — may use the aperture where the recipient's declaration covers that origin class. ASK relays authority and need not become the byte courier for a placement the aperture already authorizes. Aperture placement satisfies routing only: routing remains distinct from feeding, ingestion, disposition, and implementation authority, and the aperture confers nothing beyond the one exact create. The declaration's bounds govern payload class as well as origin class and operation shape: material outside the declared payload class — for example private-bearing content through a wall-safe-only aperture — is not covered, and routes through ASK or the recipient's own executor instead.

Direct propagation authorizes only the scoped conformance change. It does not authorize unrelated changes to the consumer's project truth, architecture, source of intent, or implementation.

Conformance targets canonical state, not literal carrier strings. Name the owner canonical by path — and SHA where available — as the authority. Quoted recipient text is a search anchor or illustration, not an exhaustive change target unless that carrier has been verified byte-identical to the owner. The acting or recipient surface reads its live carrier, corrects every materially equivalent occurrence within the explicitly named clause or section, and re-syncs that bounded scope to canonical substance without widening beyond the authorized rule. When the originating surface cannot inspect the recipient carrier — across a wall, for example — the handoff leads with the canonical re-sync instruction and marks any quoted find-and-replace text explicitly non-exhaustive.

Method-altitude articulation: method-ASK/docs/source-of-intent.md §Scope guard: handoff routing vs protocol conformance.

Verification Claims and Evidence Boundaries

A verification statement is bounded by the evidence actually gathered.

For claims such as clean, complete, current, zero residue, byte-identical, or verified, name the exact carrier set, path or query, ref or time boundary, and property actually tested.
Verify the measurement target at the point of execution. A passing, failing, or zero-result check is not evidence until the command's repository or worktree, carrier or path set, ref or time boundary, and query or predicate are explicit and independently confirmed. Do not rely on inherited cwd, a preceding cd in a compound command, or an earlier attachment check in cross-repo or multi-root work. When the claim concerns change across a mutation, capture the baseline before editing; a clean post-edit result cannot establish the pre-edit state.
Verify execution completion and result semantics. Confirm that a verification check actually executed before interpreting its output. Distinguish a valid no-match from an execution error; preserve the raw completion status before any pipe or transformation; quote or otherwise validate paths, globs, and input expansion. State whether a count measures files, matched lines, occurrences, records, or claim units. Empty output from a failed or unrun check is no evidence.

The boundary of a search is the boundary of the claim. Absence from one folder, one pattern, one connector result, or one carrier class is not absence from the corpus.
A check verifies only its direct result. Separate observation from inference; do not attach an inference to a checked fact and label the composite verified.
A bounded-region or inverse-transform proof establishes only the transformation it directly checks. It is not evidence that no intervening write was overwritten: the proof is evaluated against the operation's recorded preimage and resulting bytes, so it can pass even when a different state existed immediately before replacement.
Pattern lists are hypotheses about how a defect may appear, not exhaustive evidence. An exhaustive claim requires enumerating and dispositioning the actual occurrence or carrier set.
Where coverage is partial, state the result as: no unexplained findings in <exact set tested>.
Artifact function sets the correction threshold. A live corpus artifact — repository content, a canonical, an operator-side reference, a maintained diagram, a current instruction, or another durable product surface — remains subject to ordinary quality correction. Aesthetic defects, redundant metadata, harmless but inferior wording, and internal inconsistency may be non-blocking for the current operation while still warranting correction in the owning corpus. Correct them when they are inside the authorized scope; otherwise route or schedule them under ordinary scope discipline. The frozen-record threshold below governs adversarial process artifacts and historical evidence — proposals, review packets, receipts, temporary matrices, audits, closures, provenance records, and prior generations. It prevents process residue from being repeatedly polished after it has served its function, and must not be used to excuse a known defect in a live corpus surface. Never "correct" the corpus by rewriting historical evidence, and never polish historical evidence as a substitute for correcting the corpus.
Frozen-record correction threshold. If a completed audit, closure, provenance record, or other frozen record overstates its evidence in a way that can affect a future decision about action, authority, safety, recovery, or durable interpretation, preserve the original statement and append a correction — do not silently tidy the audit trail. A non-material imperfection — one below that threshold — is dispositioned in the current review or closure record as NON-BLOCKING / NO ACTION and does not reopen, append to, or generate a successor for the frozen object. A MATERIAL NON-BLOCKING finding is recorded once in the current record; append to the frozen object only where future readers materially depend on the corrected interpretation, not merely because the discrepancy exists.
If a live canonical or current instruction overstates its evidence, correct the operative statement under that carrier's version and snapshot discipline, preserving the prior state in its lineage — rather than leaving a false current instruction in force.

Blocking requires a named failure mode. Classify each discrepancy: BLOCKING — it can change the authorized action, live state, authority, safety, recovery, or a durable interpretation another decision depends on; name the credible failure mode and correct it before proceeding. MATERIAL NON-BLOCKING — real and worth recording or scheduling, but it does not prevent the authorized action; record it once in the current record and continue. NON-MATERIAL — it cannot change the current decision or live result; disposition NON-BLOCKING / NO ACTION, creating no successor artifact, append, or seal whose only purpose is to document that none is needed. This classification governs discrepancies in evidence about an operation, which block only through it, never by default; a materially misleading frozen evidentiary claim remains governed by the frozen-record correction threshold above, and a false live canonical or current instruction by its carrier's version and snapshot correction discipline.

Correction loops terminate. Before any further correction or republication round, name: the decision or real-world failure mode the round can change; the genuinely new evidence or method it adds; and the exact operative object set it evaluates. If any of the three cannot be named, the round does not open. When a round's defects are predominantly introduced by the correction process itself, or two consecutive rounds fail to converge, stop carry-forward patching. After two correction rounds on the same object family, before a third cross-surface handoff: re-anchor to the current live owner or baseline, reconcile or rebuild only the operative set, reread the complete affected frame, validate derivative summaries against source data, run the internal challenge of §Structured Change Summary where available, and leave preserve-only generations immutable. Regenerating a whole package to repair a non-operative string is the defect, not the diligence.

Runtime-capacity claims are not verified state. An executor cannot verify its own remaining effective capacity from workload, conversation length, estimated token use, accumulated tool output, perceived complexity, or a subjective sense of having "spent itself." A runtime-emitted capacity readout is verified runtime state, but a readout alone establishes neither exhaustion nor a new gate, and neither a readout nor an estimate creates a stop condition, transfer recommendation, recap obligation, program interruption, or ASK decision. Where the runtime reduces context automatically — by compaction, summarization, or equivalent — or the operator can trigger that reduction, ordinary context pressure is a continuation path: continue the current authorized unit up to its configured review gate. Where no reduction path exists — the runtime declares no automatic reduction and no operator-triggerable reduction exists, a reduction path being presumed to exist wherever either is unknown — an objective readout becomes decision-relevant only where the runtime declares a fixed limit and the executor names the exact readout value, that declared limit, and an already-observed capacity failure of an operation required to reach the next gate. A projection of remaining work is not a demonstration. Then stop at the current safe point. Preserve state through an existing durable owner only where that write is already inside the authorized operation; otherwise report the stop, the exact failed operation, and the recovery requirement to ASK. This rule creates no recap, registry, checkpoint-artifact, or other write authority. An upcoming already-authorized checkpoint may be used only where it is reachable without retrying, bypassing, or depending on the operation that already failed; do not perform additional work merely to reach a preferable stopping place. The readout still manufactures no new transfer gate. On capacity grounds specifically, interrupt the unit before an existing configured gate only when the runtime emits an explicit blocking signal or a failure of its reduction, or the declared-fixed-limit case above is established on its own terms. Propose transfer only when the runtime emits an explicit blocking signal or a failure of its reduction; required material is demonstrably unavailable after the normal recovery path; a defect is named against an exact artifact, output, or reproducible observation under the bullets above, a self-assessment of one's own output quality not being such a defect; or ASK directs transfer. The fixed-limit case is not among them: it earns an orderly checkpoint, never a transfer. Stop conditions declared elsewhere in this protocol are unaffected. Reduction is not assumed lossless. Report a possible fidelity loss as the exact missing material, recovered from its durable owner — never as a capacity estimate. Freshness as method is unaffected: independent critique, reconstruction from durable truth, a deliberate successor after a completed execution context, and an ASK-directed transfer remain legitimate, and none of them is evidence that the current thread reached a limit. A freshness proposal names its method reason and must hold at the start of a fresh thread; one that would not be proposed there is a capacity claim wearing a method label.

Any context-reduction path must preserve or re-establish, before further action:

the current ASK authorization and approved scope;
explicit non-actions;
the current gate and intended terminal state;
exact durable-owner, review-object, PR, and artifact locators, each carrying the load-bearing state identity that makes it reviewable — PR base and head SHA, commit, version, or hash, as applicable. Read mutable owners live at use, reconcile them against that pin, and classify the movement on the evidence and authority axes before proceeding (§Aging-Rate Principle);
unresolved blockers and write-aperture state.

Recovery is not uniform across that list, and conflating its limbs is itself a failure mode. Authority: preserve the exact ASK relay or envelope; where it cannot be independently established after reduction, stop and obtain a fresh ASK relay. Never reconstruct authority from a program row, plan, recap, PR, review object, artifact, durable-state owner, or generated summary — those preserve evidence of the work, never ASK's authorization of it. State and evidence: re-read their durable owners. Mutable objects: re-verify the load-bearing state identity, because a locator without its approved identity does not preserve the reviewed state. A drifted head, version, or hash is outside the previously established reviewed state; it is outside ASK authority only where the current ASK envelope does not cover that drift. Re-establish both the authority boundary and any applicable review window before resuming. A generated summary is continuation context, not an authoritative replacement for those owners. The dangerous case is not detected loss but silent loss — an executor that has forgotten an authorization, a non-action, a blocker, or an aperture does not know anything is missing, so the set is re-established affirmatively rather than reported when noticed.

Private agent memory may record an incident or point to this canonical rule only when ASK explicitly authorizes that memory write. This section does not itself authorize creating, extending, or revising memory. Private agent memory is not the owner of durable workflow protocol. Any retention under this clause remains subject to §Learning Disposition and §Private-Memory Write Gate.

Rule-to-Artifact Conformance Gate

Before adding, materially revising, or applying a workflow rule that changes artifact naming, versioning, snapshots, routing, or lifecycle:

read the current canonical rule;
inspect the current artifacts, relevant lineage, and live citations the rule governs;
test the rule against the artifacts and the artifacts against the rule.

A long-standing written rule may have drifted. Repeated artifact practice may also be wrong. If the rule and governed artifacts disagree, stop and obtain an ASK ruling before mutating either.

Do not retroactively rename, normalize, or rewrite historical artifacts solely to force apparent conformance. After the ruling: if the ruling changes the canonical rule, update that rule first, then conform current active carriers within the authorized scope. If the rule stands, leave it unchanged and conform the current artifacts instead.

Path Migration: Reverse-Consumer Enumeration

Moving or renaming a canonical path breaks every surface that points at it, which is a strictly larger set than the surfaces that move. Enumerate consumers; do not reason about scope.

Before the cutover, list:

objects that move;
direct references inside the owning surface;
every external source index that maps the path;
downstream trackers, adapters, prompts, and routing instructions;
walled or private consumer indexes;
actual Project-source inventories and retrieval behavior — mounted Sources, Instructions, live connector paths, standing mounts, on-demand fallbacks, and any claim about which of those exists;
local launch configs, scripts, agent memory, aliases, symlinks;
human applications keyed to the path;
current locators versus historical event-time paths.

A surface being out of scope for moving does not put it out of scope for referencing. That inference is the characteristic failure: a downstream project keeps its own root, so it is excluded from the migration — and its index, trackers, and prompts keep pointing at an address that no longer exists.

Post-cutover fail-closed claims apply §Verification Claims and Evidence Boundaries. "No stale references remain" is a claim about what was scanned. Name the exact carrier set tested, or the result will be read as broader evidence than the check supports.

Per-line disposition, never a blanket swap. A current locator tells the reader where to find a retained artifact — update it. A historical record states where something lived at event time — leave it. A line doing both keeps its narrative and gets its locator corrected, or states both paths explicitly. Ambiguous function stops for an ASK ruling rather than a guess.

A migration is also an audit. Reading every consumer may surface drift that predates the move — stale bases, retired conventions, or declarations that disagree with disk or Project UI. Record it as adjacent. Repair it only when the active scope explicitly authorizes that correction and the acting surface has write jurisdiction; otherwise flag or route it under §Cross-Surface Change Routing.

Repo Workflow Discipline

Session-Start Discipline

Before any new repo work in a session:

Confirm the working directory is the session-owned worktree or approved repo root for this session. Cross-worktree absolute paths are a known failure surface; verify before any edit, write, or cross-root git -C command.
Verify HEAD is attached to a named branch. Detached HEAD is a stop condition.
Verify the working tree is clean.
If the working tree is not clean, stop. Identify whether the changes belong to the current thread before touching anything. Inheriting another thread's uncommitted state is a stop condition until provenance is established.

This does not replace Branch Freshness or Default Verification. It is the session-entry gate before meaningful repo work begins.

Branch Freshness

For repo implementation work, follow this sequence:

verify local repo attachment
verify clean working tree
git fetch origin --prune
git checkout main
git pull --ff-only origin main
create task branch from refreshed main
stop if any verification fails

Do not start meaningful repo work from a stale, dirty, detached, or ambiguous branch.

Default Verification

Before meaningful work, verify:

pwd
git rev-parse --show-toplevel
git remote get-url origin
git branch --show-current
git status --short

Stop if repo root, remote, branch, or working tree does not match the task requirements.

Terminal-State Discipline — do not conflate

Do not conflate distinct terminal states. Each is a separate, independently verifiable fact:

local edits
exact scoped diff
local commit
pushed branch
PR created
merged PR
branch cleanup

A report that collapses two of these (e.g. "done" for a change that is only committed locally, or "merged" for a change only pushed) is a defect regardless of the vocabulary used.

Terminal-State vocabulary

Use these explicit terminal states by name:

exact scoped diff ready for approval
committed locally only
pushed branch only
PR created
merged
merged branches cleaned up

Explicit Artifact-Lifecycle Verbs

Do not use cut as an operation verb for drafts, changes, files, versions, snapshots, handoffs, releases, or other artifacts. It is ambiguous between creation and destruction.

Name the actual operation instead: draft, write, revise, save, create a version, create a snapshot, copy at byte parity, rename, route, supersede, retire, or delete.

This rule applies to plans, instructions, handoffs, change summaries, and status reports. Historical quotations, provenance records, frozen artifacts, and unambiguous domain terms such as a film's rough cut are not rewritten solely to enforce it.

Exact Scoped Diff Gate

Stop at exact scoped diff unless ASK has already approved commit / push / PR.

The default implementation terminal state is:

exact scoped diff ready for approval

Exact scoped diff review is the mandatory approval checkpoint before meaningful write actions complete. Approval may be given inside the executor session after the diff is reviewed; once given, the executor may complete the remaining git workflow without separate manual GitHub UI ceremony. In the configured paired path, ASK's approval follows advisor Stage-1 review of the published minimum exact object unless ASK explicitly elects direct execution; approval authority does not make ASK the routine first-line reviewer (§Advisor-Readable Review Objects).

Advisor-Readable Review Objects

When exact-byte advisor review is required and the advisor cannot read the executor's session-local scratch, publish the minimum named review object to the narrowest authorized shared-scratch path mapped by the surface's source index (_INDEX). This is the normal transport surface for cross-surface exact review. Use an already advisor-readable exact surface first: a pushed PR is the review object for repo changes once it exists — do not create a duplicate shared-scratch packet merely because session-local scratch is unreadable. Session-local scratch remains appropriate for intermediate construction and for objects not intended for cross-surface review. Manual operator upload is a last-resort fallback only when the payload is already authorized for this advisor and either the exact mapped path does not resolve, or exact bytes remain unavailable after the bounded retrieval ladder below and ASK explicitly elects manual upload.

The declared review identity. A review object carries one identity block, declared once and referred to afterward by name. Its shape follows the carrier, because a pushed PR and a scratch file are not identified the same way:

PUSHED PR          PR locator + exact base SHA + exact head SHA + exact merge-base SHA
FILE / OBJECT      exact locator + role + lifecycle + full SHA-256
/ BUNDLE

CONDITIONAL        baseline identity — only where the review depends on detecting
                   movement from a prior state
                   byte size — only where truncation or incomplete transport is a
                   named failure mode

Do not require a SHA-256 for a pushed PR whose exact state is already fixed by its locator and its base, head and merge-base. Every later clause in this rule that needs the object's identity refers to the declared review identity; it does not restate the fields. An exact review object concentrates its evidence and does not reproduce it throughout its own narration, and an unchanged-surface inventory names only surfaces whose non-movement is a real scope, collision, authority, or recovery condition. A connector-bounded bundle's per-part manifest fields are not covered by this economy: they independently support reconstruction and are required in full.

Review-window routing — the relay is the request. When an advisor surface is configured, pre-commit and pre-write review default to the advisor, and paired-path Stage-1 readiness includes the minimum exact review object: unless ASK has explicitly elected direct execution, do not report a unit as exact scoped diff ready for approval (or a proposal package as ready) while that minimum advisor-readable exact object remains session-local — publish it, or identify an already advisor-readable exact surface, and report the declared review identity as part of the readiness receipt. Use the smallest exact patch or object that supports the decision; reuse an existing exact advisor-readable object rather than creating a duplicate packet; a bundle exists only where one exact object cannot carry the review. The normal paired path is: minimum exact object available → executor reports Stage 1 ready → ASK relays the readiness receipt or object into the advisor thread → the advisor reviews the exact object and returns a recommendation → ASK adjudicates and relays the decision. ASK's act of relaying executor material into the advisor thread is itself the review request — the mirror of the approval-relay rule; no additional request phrase is required, and an advisor must not return the review to ASK on the ground that no explicit request was uttered. Missing-object recovery: where a prose summary reaches the advisor without the exact object, the review is open — not declined — and Stage-1 readiness is incomplete; the advisor requests the missing minimum object from the executor through the normal relay, and no second ASK review-request phrase exists. Direct execution requires an explicit ASK authorization for the named unit — stated in the executor thread or through a DIRECT EXECUTION envelope; any clear ASK language of equivalent force suffices, and the executor proceeds only within that exact authorization. Other narrowed envelopes — including FYI and HOLD — also suppress an advisor Stage-1 verdict, but they authorize no direct execution and no write. Silence, omission, or failure to relay elects nothing and authorizes no commit or write. Reviewer ≠ authorizer: ASK remains the sole authorization apex at both windows, and speculative packet construction beyond what the review needs remains prohibited.

Pre-PR publication condition. A unit is not reported ready for exact-byte advisor review until the named proposal-only exact patch or bounded review object exists in the index-mapped shared scratch — or an already advisor-readable exact surface is identified by exact locator — and the declared review identity has been reported. A session-local path, a prose summary, or a digest without the object does not satisfy this condition. Publication or identification of the minimum exact object is part of paired-path Stage-1 readiness; it is not gated on any further ASK utterance.

Path authorization is not content authorization. A mapped scratch path authorizes a retrieval route, not every payload that could travel it. Do not copy secrets, wall-bound material, or any payload the advisor is not authorized to read into shared scratch or into a manual upload. If the mapped path or the payload is outside the advisor's authorized read surface, stop and ask ASK to name an authorized review surface; upload does not cure an authorization boundary and never bypasses a wall.

A request to prepare an exact artifact for advisor review authorizes one declared proposal-only review object or bounded review bundle, provided its exact path(s), filename(s), role, and lifecycle (supersession trigger) are stated before creation. It does not authorize the target canonical, a version snapshot, a companion artifact, a repo commit, or a private-memory write — each of those remains a separate approval unit.

The review object carries its proposal status in its scratch path, filename, and handoff, never in wrapper text that would alter bytes intended to match a target. It takes one of three forms:

single-artifact exact-byte review — the -PROPOSED object is byte-identical to the proposed target bytes;
single-file multi-target review — one -PROPOSED packet carries the complete exact patch, the target file set, the baseline refs, the proposed hashes, and the declared role and lifecycle, when the advisor can retrieve it completely;
connector-bounded review bundle — when raw-byte retrieval of a single packet is unavailable under the retrieval ladder below, or a target is not representable as a text patch, publish one declared bundle of ordered exact-object or exact-patch parts in mapped shared scratch. Its manifest records, per part: ordered path, part_type (exact-object | exact-patch), the target path or set, byte size, SHA-256, a baseline ref/hash where applicable, the reconstruction operation, and the proposed target hash — plus the complete target set, the package hash, role, and lifecycle. A text or repo diff is an exact-patch against a declared baseline; a binary or non-patch artifact (a PNG, a diagram export, any exact object) is carried as its exact proposed object bytes; a mixed package may contain both part types. Prefer one bounded part per target over arbitrary prose truncation, but never force binary target bytes into a text-extraction representation. The manifest itself and every part must be individually retrievable through the intended advisor path; every physical path is declared before creation; the bundle is one logical transport operation, not open-ended scratch authority.

Partition every multi-object package by role. Identify the operative review set — the exact current objects whose contents can affect the decision — and the preserve-only set — immutable prior generations, provenance, and historical evidence retained for identity and lineage. Preserve-only objects are verified for the exact property the decision uses, normally existence and identity; they are never regenerated or forced into semantic parity with the current proposal merely because they travel in the same package.

Object reachability is distinct from representation quality. Successful exact-path resolution establishes that the path is reachable. It does not establish that an extracted-text or rendered representation is byte-faithful. Extracted text, OCR, rendered previews, and connector-normalized content are inspection views, not exact-byte evidence. Markup stripping, Unicode transformation, truncation, or partial rendering is a representation failure — never proof that the underlying object is unreachable, and never grounds on its own for reporting a byte defect in the object.

Retrieval order. After resolving the exact mapped path, use the strongest available raw-file or file-byte retrieval route before changing the review representation. Where an extracted view preserves one portion of an object while stripping another — for example plain text surviving while an angle-bracketed markup tag disappears from the same line — the view is demonstrably lossy and must not be used to diagnose the object's bytes.

ASK is the authority relay, not the byte courier. Do not ask ASK to download, attach, re-upload, or otherwise manually shuttle an object while its exact bytes remain retrievable through the authorized mapped route. Metadata-only reachability, or a lossy inspection representation, does not establish exact-byte availability — the prohibition binds on retrievable bytes, not on a resolving path. ASK relays authority and adjudicates; moving bytes that the mapped route already carries is not that role.

Bounded fallback. If raw-byte retrieval is technically unavailable, publish one connector-bounded alternate representation in the same mapped shared scratch. If that representation also cannot be retrieved exactly, stop and report both failures — the exact locator, the retrieval modes attempted, and the failure of each. ASK may then elect manual upload even where the original path still resolves to metadata or a lossy view; a resolving path is not a reason to withhold that election. Manual upload occurs only on that explicit election. Do not create a serial repackaging cascade, and do not treat a lossy view as the trigger for the next package.

Once its path and hash have been reported for review, a review object or bundle is immutable. Never overwrite it in place. A revision receives a new unique dated or _vN -PROPOSED name, identifies its predecessor, and reports new hashes; the superseded object remains scratch provenance unless ASK separately authorizes retirement.

Report the declared review identity in the handoff. A shared-scratch review object is an ordinary named operator-scratch artifact — a visible surface under normal proposal/scratch discipline, not a private persistent surface governed by §Private-Memory Write Gate.

Structured Change Summary

Meaningful changes require a structured change summary covering:

why this change exists
what changed
what did not change
what remains out of scope

If a PR is used, this belongs in the PR description. If no PR is used, the same summary must be produced in the executor handoff or approval record before write actions complete.

When the work surfaces a potentially reusable learning, include a one-line learning disposition: visible owner · nomination/hold · private-memory candidate pending separate authorization · or no retention. "Reusable" is not itself a destination.

Executor preflight — read the finished object before handing it off. Before reporting any meaningful artifact, report, or package ready for cross-surface review or approval — Stage-1-ready in the configured paired path, or ready for the exact-scoped-diff / approval handoff where no advisor surface is configured — reload the final bytes from disk and perform one end-to-end parent cold read of the deliverable and its surrounding frame — never the delta alone. Verify: the summary describes the object actually produced; affected headings, tables, manifests, and neighboring prose remain mutually consistent; every claim-bearing check actually executed against the intended target and its output means what the report says (paths, globs, expansion, counts, and locale-sensitive formatting not silently misread); cross-object identities and predicted relationships agree; lifecycle verbs and authority language conform; and no claim outruns the work performed. A new or materially revised checker must demonstrate one real negative or control case failing for the intended reason before its output gates a claim; an unchanged mature checker is not re-fixtured on every ordinary run.

Triggered internal challenge. Run one read-only, distinct-lens internal adversarial pass before the first cross-surface review or approval handoff (Stage 1 where an advisor surface is configured) when any of these applies: a multi-object package; a ledger, manifest, registry, or generated carrier; cross-object invariants; carry-forward generation; higher-consequence or hard-to-reverse work; a second correction round; or a prior frame/summary inconsistency in the same object family. The reviewer focuses on frame/summary consistency, chronology and authority, collisions and overwrite hazards, cross-object identities, stale carry-forward language, and omitted consequences; it returns findings only and writes nothing. The parent verifies every internal finding against the object and owner before acting on it — internal reviewers fail in both directions, and a false finding closes in-thread, earning no correction artifact unless the failure itself is materially reusable. Internal agreement is not certification, and internal-clean never replaces the external advisor. Where no internal reviewer is available, reload the final object and perform the parent cold read as though receiving it from another executor, report UNAVAILABLE plus the completed fallback, and do not block on the missing capability alone.

Readiness receipt. Every meaningful review or approval handoff — Stage-1 or otherwise — reports: parent semantic self-review: COMPLETE · internal adversarial preflight: PERFORMED | NOT TRIGGERED | UNAVAILABLE · one bounded trigger/lens-or-fallback line. These fields join, not replace, the identity fields §Advisor-Readable Review Objects requires of a paired-path readiness receipt (the declared review identity). A package additionally reports its operative review set and preserve-only set by exact paths and counts. No defect diary — report a pre-handoff catch only where it is materially useful.

Operator-Side Voice Scan

Before presenting an exact scoped diff for approval, scan added prose for voice / surface-boundary risk against the project's named operator-side voice owner(s) and grounding-note voice guidance. Do not assume a private-memory artifact exists or owns those constraints. Any private-memory contribution must already have survived §Learning Disposition and remains subject to §Private-Memory Write Gate.

Flag any matches or concerns honestly in the structured change summary. Do not auto-sanitize: some apparent matches may be legitimate domain vocabulary that the project needs to name directly.

The scan rule may live in AGENTS.md; the token list, translation table, and protected domain-vocabulary list do not. Route those specifics to the narrowest authorized operator-side owner suited to their wall and cadence; do not copy them into repo-local artifacts. Private memory may retain only ASK-authorized machine-local, wall-bound, or deliberately non-operative residue under the two gates.

Default: Hold or Carry Through Per Adversarial-Collaboration Preconditions

When ASK has approved the scoped diff, the workflow continues through commit and push to PR creation.

If the project meets the preconditions for adversarial collaboration (per Adversarial Collaboration) — hardened backbone, active architectural uncertainty, configured advisor surface — hold at PR created until the advisor relay returns approval, then continue to merge. The pushed-not-merged PR is the advisor's structural review window.

ASK forwarding an advisor approval to the executor is the relay. Forwarding may be done by pasting the advisor's approval, summary, or equivalent review result. No additional approval phrase is required after the forwarding act.

Forwarding advisor notes that contain required fixes, blocking concerns, or open questions is not approval relay; it is fix-direction or question-forwarding.

If no advisor surface is configured, carry through to merged + cleanup once diff approval is given. The pattern is proportional to architectural uncertainty live at any moment.

PR Creation

When creating a PR, report:

branch name
commit SHA
PR number
PR URL
actual base branch
actual head branch
validation performed
terminal state: PR created

Post-Merge Cleanup

After merge, verify main, delete merged task branches where safe, verify remote branch state, and report:

current main HEAD
whether merge commit is present
whether expected changes are present
local branch cleanup
remote branch cleanup
final branches
final working tree status
terminal state: merged branches cleaned up

Post-merge cleanup never includes private-memory mutation unless a separately planned and explicitly authorized memory operation remains open.

Direct Push to Main

Branch plus PR is the default for meaningful structure or rule changes. Narrow low-risk edits or explicitly scoped bootstrap tasks may allow direct push to main when scope is made explicit and approved.

Session Topology / Single-Writer Discipline

Multiple writer-capable sessions — for example parallel executor threads, subagents in separate worktrees, a human editor plus an executor, or another runtime occupying the executor role — can mutate the same repo files concurrently. This is a real failure mode, not a hypothetical.

Rules:

One writer at a time per branch. A second operator session on the same branch must verify state freshly, treat the working tree as authoritative over its own memory, and not assume mid-flight context from another session.
Treat repo and remote as the audit trail. When two sessions disagree about state, prefer git status, git log, and remote-branch state over either session's recollection.
Stop on suspected concurrent mutation. If a working tree contains changes the current session did not make, do not overwrite. Re-orient against the repo before continuing.

This rule applies whether the second session is the same agent, a different agent, or a human editor.

Write Guarantee Levels

A write to shared mutable state carries exactly one declared guarantee level. Name it; never imply a stronger one.

LEVEL 0   observed-state checks only — NO exclusion
          reads, hashes, and comparisons at named observation points.
          Movement is detected only when an observation point sees it;
          a write after the final check and before replacement may be
          overwritten without detection.

LEVEL 1   cooperative exclusion — among writers sharing ALL THREE of:
            the same canonical target identity
            the same exclusion primitive
            the same lock plane
          Excludes participants. Excludes nothing else.

LEVEL 2   backend-enforced conditional mutation — the backend itself
          rejects the write if the state moved. IMPLEMENTED and EXERCISED
          per backend; never asserted from the existence of a revision token.

No silent downgrade. Where a caller requires a level the backend cannot provide, the operation fails. It never proceeds at a lower level and reports success — a downgrade that reports success is worse than no protection, because it manufactures confidence.

Level 1 is not compare-and-swap and is never labeled as such. It makes the read-to-write interval irrelevant for participants. A non-participant is outside that exclusion guarantee: movement is detected only at the operation's named observation points, and a write after the final observation and before replacement may be overwritten without detection. Within this model, only an implemented Level 2 conditional write closes that interval against non-participants on the supported backend.

Writers cooperate only where all three Level-1 identities match. Two writers resolving the same file to different canonical identities, or using different exclusion primitives or lock planes, do not exclude each other. The Level-1 primitive itself supplies no evidence that they are coordinating.

Bounded-Region Byte Contract

A write that replaces part of a file, or an identity claim over part of a file, carries an explicit operation-scoped byte contract.

This rule creates no separate review window. The contract travels with the operation and is reviewed at whatever gate the operation already has.

§Scope Discipline scales evidence depth, not whether a boundary category may remain implicit. Every category is declared before the operation; where a category is inapplicable, that is declared explicitly rather than omitted or defaulted:

source mode / encoding             declared and validated, or binary
start + end resolution             the exact start anchor, and EVERY candidate end
occurrence selection               which occurrence, where more than one exists
inclusion                          whether each anchor falls inside the region
separator bytes + ownership        the exact bytes, and which side owns them
trailing bytes                     what else belongs to the region
source + result + untargeted       the region before, the region after, and
  identities                       everything outside it
structure-aware resolution         a typed resolver for the source's structure,
                                   or a fail-closed refusal

A default is a decision made by whoever wrote the tool, applied to a file they never saw.

Anchor resolution fails closed. An anchor that is absent, whose occurrence count does not match the declaration, or whose declared end candidate is not found, is an error — never a scan that runs on to the end of the file.

Cross-field declarations must not contradict one another. Where two fields could claim the same bytes, the contract states which one wins.

The untargeted identity is the operative proof that a bounded edit stayed bounded: everything outside the region is byte-identical before and after. Establish it by comparing those exact bytes — a rendered or line-based view can agree while the bytes differ.

This rule names the required categories. It fixes no implementation schema, API, or field count — those belong to whatever tool performs the write.

Scope Discipline

Match the unit of work to the level of the question.

For implementation and repo hygiene, prefer the smallest honest unit. Small bounded PRs are usually best. Avoid bundling, widening, or design-in-advance.

For conceptual architecture, prefer the largest tractable structural question. The smallest honest unit at the architecture layer is often a structural question or a model attempt against a concrete example, not another local prototype probe.

Do not let "smallest unit" become a rule that prevents zooming out to the right scale. A series of small honest units at the wrong layer can add up to ceremony without architectural progress.

Do not bundle unrelated work. Do not widen scope mid-task unless the widening is explicitly chosen. Do not create artifacts merely because a process pattern exists.

Scale verification to the decision. The evidentiary depth and blocking threshold for an operation scale with reversibility × blast radius × cost of error × decision relevance — a qualitative reasoning frame, not a numerical score. Whenever the frame is applied — in either direction — name the operation class in one sentence ("reversible operator-file maintenance with lineage retained"; "recovery-critical canonical migration"). Every claim then made remains bounded by §Verification Claims and Evidence Boundaries: what scales is how much evidence the operation must gather and what may block it, never how honestly the gathered evidence is stated.

Proportionality never waives a gate. It may reduce evidence depth or classify a discrepancy non-blocking; it never waives an ASK-owned authorization gate, a configured Stage-1 or Stage-2 review window, a wall or write-jurisdiction boundary, a required read, a lifecycle transition, a recovery or rollback requirement, or a safety or secrecy constraint.

Plan-Before-Execute Rule

Before executing a meaningful repo change, state the plan: what files will change, what scope is in vs out, what non-actions apply, what terminal state is expected.

The plan creates an inspectable reasoning object before mutation. It lets ASK, the executor, and any configured advisor challenge scope, assumptions, non-actions, and the intended terminal state before work becomes harder to unwind. This applies whether planning and execution occur in one session or across multiple surfaces. Do not collapse plan and execution into one opaque step.

Any proposed private persistent mutation must be named as a separate planned operation with its exact target, exact proposed mutation, visible-owner or no-retention disposition, and terminal state.

For a creation, include the full proposed payload. For an edit, include the exact diff or replacement payload. For a deletion, include the exact path, deletion warrant, pre-deletion size/hash receipt, and expected absence or restored-byte/hash receipt.

If the operation is absent from the approved plan, the private persistent mutation is out of scope.

Tool-Dependent Workflow Rules

When a project workflow depends on an external tool, vendor, model, rendering surface, extraction surface, diagram-generation surface, or other operator-supplied system whose identity may change, encode the repo-local rule tool-agnostically.

In AGENTS.md, name the structural role the tool plays, when it is invoked, what inputs and outputs it expects, the authority boundary, and any refresh cadence. Carry the current approved tool / vendor / surface identity, the substitution path, and any operational details that depend on the specific tool outside that repo rule.

The repo rule names the structural role. The current occupant, substitution path, and vendor-specific operating details belong in the narrowest visible or operator-side owner suited to their cadence. Private memory may cache only machine-local or deliberately non-operative residue, and only under §Learning Disposition and §Private-Memory Write Gate.

Comments, Docs, and PR Roles

Comments belong in implementation artifacts only when local clarity needs them.
Docs describe architecture, boundaries, operating contracts, and reusable guidance.
Structured change summaries and PR descriptions hold change-specific framing.

Do not push PR-only explanation into permanent repo docs, and do not hide durable operating rules inside a PR or approval record.

Refresh Cadences

Grounding Note

Refresh the grounding note only when external handoff context changes: new strategic direction, philosophical reframing, audience or positioning shift, foundational premises change, operating model changes.

Do not refresh for routine repo chronology. Possible future directions belong in the grounding note only as durable loose threads, not as recommended next paths.

`AGENTS.md`

Refresh this file only when a workflow rule is added, removed, or materially revised.

Do not refresh because project state changed. Do not refresh because a PR landed. Do not refresh because the next direction changed.

If a proposed update says "the project currently should do X," it does not belong in this file.

Defaults

Prefer ASK reuse over world-scale abstraction.
Prefer explicit structure over clever indirection.
Prefer the smallest coherent scaffold that clarifies the workflow boundary.
Use clean technical language. Avoid manifesto phrasing, speculative systems, or generic process bloat. (Voice/register specifics route to the operator voice canonical, not to a second authority here.)

Short Version

Verify repo state before meaningful work.
Read repo-local truth and grounding note before responding.
Stop at exact scoped diff before commit; carry through to merged + cleanup once approved.
State the plan before executing.
Single-writer per branch. Treat repo as audit trail.
Match the unit of work to the level of the question.
Refresh AGENTS.md only for rule changes.
Keep this file workflow-only. Repo holds state. Grounding note holds external context.
Bound every verification claim to the exact evidence gathered; separate checked facts from inferences, and test rules against the live artifacts they govern before applying them.

FilesExpand file tree

AGENTS.shared.md

Latest commit

History