psyclaw 0.27.22 → 0.28.0

package/vendor/ars/shared/references/cross_document_consistency_advisory_protocol.md

@@ -0,0 +1,263 @@
+# Cross-document Consistency Advisory Protocol (`#672`)
+
+This protocol defines the consumer and handoff boundary for the closed
+`cross-document-consistency-advisory/1.0` family. The frozen design is
+`docs/design/2026-08-10-672-cross-document-consistency-advisory-spec.md`.
+The deterministic implementation is
+`scripts/build_cross_document_consistency_advisory.py`.
+
+The family consists of:
+
+- `preregistration-artifact/1.0`, the persistent deep-research handoff sidecar;
+- `cross-document-source-manifest/1.0`, the exact two-artifact source authority;
+- `cross-document-consistency-advisory-draft/1.0`, untrusted semantic input;
+- `cross-document-consistency-advisory/1.0`, the replay-finalized carrier; and
+- `evidence-row/1.2`, whose only surface is
+  `cross_document_consistency`.
+
+## Advisory-only meaning
+
+Every final carrier fixes `layer=LLM-ADVISORY` and
+`evaluation_status=UNMEASURED`. The runtime does not call a model: it validates
+caller-supplied semantic observations and exact evidence. Repository fixtures
+measure contract behavior only. They do not measure semantic accuracy,
+coverage, false-positive rate, or false-negative rate.
+
+The only performed outcomes are
+`POTENTIAL_INCONSISTENCY_LOCATED` and
+`NO_LISTED_INCONSISTENCY_LOCATED`. The latter always means **not proof of
+agreement, completeness, or a clean document**. An unperformed observation is
+`check_state=not_checked` with a null outcome.
+
+This carrier has no score, confidence, severity, PASS/FAIL, gate, readiness,
+acceptance, authorization, terminal-policy effect, rewrite instruction, or
+replacement text. It never creates or changes ClaimIntent, a revision roadmap,
+author adjudication, patch authority, Integrity Report counts/verdicts, Phase E
+claim rows, or Material Passport state. Consent/protocol review remains owned by
+#667/#681; this family adds no consent/protocol role, enum, observation, or
+consumer.
+
+## Preregistration sidecar ownership
+
+The research architect is a non-shell declarer. It records only the explicit
+caller status and, for a completed supplied artifact, the explicitly named
+companion handle. It must not hash the file, guess a digest, copy the repository
+template into the handoff, or construct/update the sidecar itself.
+
+Before the deep-research handoff, a shell-capable orchestrator invokes:
+
+```bash
+python scripts/build_cross_document_consistency_advisory.py \
+  build-preregistration-artifact \
+  --status <provided|not_provided|access_failed|retrieval_failed> \
+  --declared-at <explicit-rfc3339> \
+  ...
+```
+
+The named deterministic builder is the only owner allowed to create or update
+`preregistration-artifact/1.0`. It emits exactly one record, including an
+explicit unavailable receipt. It never reads an ambient clock. A `provided`
+record binds the strict-UTF-8 companion's exact artifact/content SHA-256 and
+byte sizes and uses `author_provided_completed_preregistration` provenance
+(`synthetic_fixture` is reserved for repository tests). The unavailable states
+have null paths and byte bindings, `not_provided` provenance, and the caller's
+explicit RFC3339 declaration time.
+
+The companion is explicitly named by the caller. The sidecar never embeds,
+locates, fetches, or follows it. The repository file
+`deep-research/templates/preregistration_template.md` is guidance only and can
+never be evidence or a replacement companion.
+
+Academic-paper intake and every pipeline handoff strict-parse and replay the
+same sidecar and, when provided, the same companion bytes. They then carry both
+byte-for-byte without reinterpretation. Omission, silent substitution, digest
+repair, or rebuilding from prose is invalid. A later explicit user supply must
+produce a new fully bound sidecar through the same builder; it cannot be spliced
+into the old receipt.
+
+## Stage 4.5 source authority and replay
+
+The source manifest contains exactly two artifacts:
+
+1. the designated, present accepted manuscript draft; and
+2. the exact projection of the current preregistration sidecar.
+
+All manuscript and disclosure evidence roles bind the designated accepted-draft
+artifact. Only the `preregistration` role binds the preregistration artifact.
+Extra, unused, or prior manuscript artifacts are invalid.
+
+Sidecar projection is exact:
+
+| sidecar status | manifest state | binding rule |
+|---|---|---|
+| `provided` | `present` | same ID/path/provenance and four byte bindings |
+| `not_provided` | `source_missing` | same ID; null path/bindings; `not_provided` provenance |
+| `access_failed` | `access_failed` | same ID; null path/bindings; `not_provided` provenance |
+| `retrieval_failed` | `retrieval_failed` | same ID; null path/bindings; `not_provided` provenance |
+
+If a previously provided companion is unreadable or no longer replays, the
+result is `SOURCE_BINDING_INVALID`. It is not downgraded to `not_checked` and no
+carrier is written.
+
+Finalization takes only explicitly named local inputs: draft, source manifest,
+sidecar, accepted draft, and the preregistration companion when provided. It
+strict-parses and replay-validates the complete sidecar and source bundle before
+reading any observation outcome. Its `input_binding` fixes the raw draft and
+manifest SHA-256, sidecar raw SHA-256 and `record_digest`, accepted-draft artifact
+ID/SHA-256, and source-bundle SHA-256. Validation and rendering require those
+same inputs and rebuild the carrier byte-for-byte; a self-consistent digest alone
+is insufficient.
+
+The exact `input_binding` roster is:
+
+```text
+draft_schema_version
+draft_sha256
+source_manifest_schema_version
+source_manifest_sha256
+preregistration_record_schema_version
+preregistration_record_sha256
+preregistration_record_digest
+accepted_draft_artifact_id
+accepted_draft_sha256
+source_bundle_sha256
+```
+
+`source_bundle_sha256` is canonical-JSON framing over the exact manifest SHA,
+sidecar raw SHA/record digest, designated accepted-draft ID/SHA, and every
+manifest artifact's ID, kind, state, provenance, artifact/content hashes, and
+sizes in bytewise ASCII artifact-ID order. It is never raw-byte concatenation.
+`report_id` is `XDOC-` plus the first 24 lowercase hex digits of SHA-256 over
+canonical compact JSON containing exactly the draft SHA, manifest SHA, sidecar
+raw SHA/record digest, accepted-draft ID/SHA, and source-bundle SHA. Display
+`ADV-XDOC-*` and `EVR-XDOC-*` IDs derive from canonical pair/observation-key
+order; callers cannot select them.
+
+The accepted draft limit is 8 MiB, the preregistration artifact limit is 64 MiB,
+and their aggregate UTF-8 limit is 72 MiB. Files are strict UTF-8, are not
+normalized, and are admitted before semantic consumption.
+
+## Pair roster and evidence
+
+Each carrier has exactly four pair results, in this order:
+
+1. `abstract_results` (`abstract`, `results`);
+2. `discussion_results` (`discussion`, `results`);
+3. `methods_reported_analyses` (`methods`, `reported_analyses`); and
+4. `manuscript_preregistration` (`manuscript_report`, `preregistration`,
+   `disclosure_scope`).
+
+The performed finding vocabulary is closed:
+
+| pair | allowed finding types |
+|---|---|
+| `abstract_results` | `numeric_mismatch`, `direction_mismatch`, `significance_mismatch`, `claim_strength_rung_mismatch` |
+| `discussion_results` | `direction_mismatch`, `claim_strength_rung_mismatch`, `scope_or_population_overreach` |
+| `methods_reported_analyses` | `declared_analysis_no_reported_counterpart`, `reported_analysis_no_declared_counterpart`, `analysis_specification_conflict` |
+| `manuscript_preregistration` | `undisclosed_preregistration_deviation` |
+
+The first three use exactly two evidence slots. The preregistration pair uses
+exactly three; its manuscript disclosure witness is never optional for a
+performed observation. Logical roles remain distinct even when several roles
+bind the same accepted manuscript bytes.
+
+Methods absence requires one quote and one `checked_no_match` over an exact,
+non-empty, explicitly named counterpart scope. A generic, incomplete, blank, or
+unprovided scope is `not_checked`, never evidence of absence. An undisclosed
+preregistration-deviation observation requires manuscript and preregistration
+quotes plus `checked_no_match` over the exact named manuscript disclosure scope.
+An exact disclosure quote for the same `deviation_id` produces a no-listed
+observation; absent or unreplayed disclosure scope makes the whole observation
+not checked.
+
+Performed no-listed observations use only `legitimate_compression`,
+`same_rung_rewording`, `disclosed_deviation`, or
+`other_no_listed_observation`, under their pair-specific schema branches. A
+checked scope carries
+`caller_declared_complete_named_scope_not_independently_authenticated`; this is
+replay provenance, not independent proof of completeness. Not-checked reasons
+are closed to `PAIR_CHECK_NOT_PERFORMED`, `COUNTERPART_DOCUMENT_MISSING`,
+`COUNTERPART_SCOPE_NOT_PROVIDED`, `SOURCE_ACCESS_FAILED`, and
+`SOURCE_RETRIEVAL_FAILED`. Missing source takes precedence, then access failure,
+then retrieval failure. Invalid schema, role, digest, or replay is a contract
+error and cannot be laundered into one of those receipts.
+
+`evidence-row/1.2` is separate from 1.0 and 1.1. It carries the complete ordered
+bilateral or trilateral evidence unit under
+`surface=cross_document_consistency`. The legacy 1.0 Phase E shape and 1.1
+authority-profile content-coverage shape, their schemas, runtime behavior, and
+serialized identities remain unchanged. Versions/surfaces cannot be mixed.
+
+Every positive quote or checked scope is exact-source bound. External text is
+strictly percent-decoded once (`+` stays literal), capped at 25 Python
+whitespace-split words and 1,000 Unicode code points, hashed, and replayed by a
+half-open UTF-8 byte span. Overflow is rejected rather than truncated. All text
+is rendered inert and defaults to `session_only/not_assessed`; shareable rows
+require the paired user-declared rights value. No cache, network, retrieval,
+normalization, or ambient clock participates.
+
+The field-relative ladder in
+`shared/references/claim_strength_ladder.md` is semantic caller guidance only.
+There is no deterministic keyword matcher or numeric ranker, and no ladder
+observation grants revision authority.
+
+## Legacy multi-file audit non-migration
+
+The existing Codex multi-file audit runner, its rounds/convergence state, and
+its `audit_artifact_entry` gate remain separate legacy consumers. An old
+multi-file audit `PASS` cannot be mapped, projected, or translated into
+`NO_LISTED_INCONSISTENCY_LOCATED`. Conversely, a #672
+`POTENTIAL_INCONSISTENCY_LOCATED` observation cannot be mapped, projected, or
+translated into an old-audit P1/P2/P3 finding, `PASS` / `MINOR` / `MATERIAL`
+verdict, gate result, convergence decision, or `audit_artifact_entry`.
+
+#672 never invokes the legacy runner, consumes an old audit output, or writes
+into its carrier. Existing audit behavior and bytes remain unchanged; the two
+surfaces may be shown independently but cannot satisfy, suppress, aggregate, or
+change one another.
+
+## Pipeline coexistence with #660
+
+#660 tortured-phrase screening and #672 run inside the **single existing**
+mandatory Stage-5 entry checkpoint after the same exact Stage 4.5 PASS. The
+orchestrator runs #660 first and #672 second and surfaces two independent
+carriers. The exact machine join is:
+
+```text
+#660 input_binding.artifact.artifact_id
+  == #672 input_binding.accepted_draft_artifact_id
+#660 input_binding.artifact.artifact_sha256
+  == #672 input_binding.accepted_draft_sha256
+```
+
+Neither carrier consumes, suppresses, aggregates, or changes the other. A #660
+loaded-snapshot failure may still write its schema-valid degraded artifact and
+exit 1; the checkpoint preserves and validates it. A #672 contract/runtime
+failure writes no output and records only a bounded, redacted
+`ADVISORY_UNAVAILABLE:<CODE>` diagnostic. Neither behavior changes Stage 4.5,
+blocks or delays the mandatory checkpoint, requires remediation, or alters
+Stage-5 dispatch after user confirmation.
+
+Any manuscript revision makes both carriers stale. The manuscript must re-enter
+integrity review, obtain a new exact Stage 4.5 PASS, and rerun #660 then #672
+against the same new accepted bytes. Reusing either carrier or rerunning only one
+is invalid cargo.
+
+This advisory is not a formatter input, Phase E row, Material Passport terminal
+state, or additional checkpoint. It is displayed as a separate `ADV-XDOC-*`
+table at the existing checkpoint.
+
+## Rendering, failure, and measurement limits
+
+`render` performs the same full replay before display. One explicit page contains
+at most 25 observations; `--all` does not exist. Navigation names the preceding
+or next explicit page, while the complete canonical JSON remains authoritative.
+
+On #672 failure, no schema-valid output is created or replaced. Only a closed
+`ADVISORY_UNAVAILABLE:<CODE>` diagnostic of at most 80 ASCII characters is
+retained; it cannot contain source/quote text, local paths, or raw exceptions.
+The diagnostic is informational and nonblocking.
+
+Held-out documentation remains `UNMEASURED`. No measurement JSON, model output,
+judge record, live model/API call, expensive evaluation, semantic efficacy claim,
+or clean-document claim is authorized by this protocol.

package/vendor/ars/shared/references/evidence_row_protocol.md

@@ -0,0 +1,260 @@
+# Shared Evidence-row Protocol (`evidence-row/1.0`, `1.1`, and `1.2`)
+
+This protocol is the runtime-facing authority for evidence rows. The canonical
+field shape is `shared/contracts/evidence/evidence_row.schema.json`; cross-field
+semantics are implemented by `scripts/evidence_rows.py`; the frozen decision is
+`docs/design/2026-08-09-656-shared-evidence-row-contract-spec.md`.
+
+## V1 surface and persistence
+
+V1 has one live surface:
+
+```text
+surface = phase_e_claim_verification
+Integrity Report.phases.E_claims.evidence_rows[]
+```
+
+The Integrity Verification Agent emits one row per selected
+`(claim_id, ref_slug, anchor)` tuple. The full ordered array travels inside the
+existing Schema 5 Integrity Report. It is not a new passport aggregate. A
+multi-citation claim keeps one row per citation; `E_claims.checked` and verdict
+summaries continue to count distinct claims.
+
+The Stage 4 -> 5 opt-in `claim_audit_results[]` contract is a different lifecycle
+and is not a V1 producer or consumer.
+
+## Producer sequence
+
+For each selected tuple:
+
+1. Pass the candidate row and, when available, its exact session-held source text
+   directly to `build`. Never pass a URL for the builder to fetch.
+2. Preserve the v3.7.3 anchor's encoded value. The builder validates and decodes
+   it exactly once with strict UTF-8.
+3. For a `page` or `section` anchor, pass only the bounded passage the agent
+   actually relied on. The builder requires that passage to be an exact substring
+   of the held source text. It does not authenticate the locator.
+4. Pass an explicit failure state when an upstream access or extraction attempt
+   failed. Never copy the claim, writer anchor, error message, or placeholder into
+   `excerpt.text`.
+5. Persist the returned row unchanged. Render only the persisted row array.
+
+The builder, not producer prose, decides the evidence state:
+
+| Anchor / input | State | Excerpt |
+|---|---|---|
+| `quote`, exact once-decoded source match | `verified_exact_match` | exact matched text |
+| `quote`, held source mismatch | `unconfirmed_anchor` | null |
+| `page` / `section`, supplied passage exactly in held source | `agent_extracted` | exact passage |
+| `paragraph` | `not_checked` | null |
+| any non-`none` anchor, no held source | `source_missing` | null |
+| explicit stable permission/paywall failure | `access_failed` | null |
+| explicit upstream retrieval/extraction failure | `retrieval_failed` | null |
+| explicit unperformed check | `not_checked` | null |
+| `none` / absent marker normalized to `none` | `anchorless` | null |
+
+The canonical display labels come only from `scripts/evidence_rows.py`. “Verified”
+in `VERIFIED EXACT MATCH` applies to excerpt provenance, not the Phase E claim
+verdict.
+
+## Exactness and budgets
+
+- Source-content SHA-256 covers the exact held source string encoded as UTF-8.
+  Artifact/PDF hashes are separate nullable provenance and cannot substitute.
+- No Unicode, case, whitespace, newline, or punctuation normalization occurs.
+- Percent decoding runs once. `%HH` must be well formed and yield strict UTF-8;
+  `+` remains a plus sign.
+- Quote anchors and excerpts are at most 25 whitespace-split words and 1,000
+  Unicode code points. Over-budget rows fail; they are not truncated.
+- Positive excerpts carry a SHA-256 plus a half-open UTF-8 byte span. Replaying
+  that span against the exact source content must yield the excerpt bytes.
+- `row_sha256` binds the canonical complete row except for the digest field itself.
+
+## Cache replay
+
+Only `verified_exact_match`, `agent_extracted`, and `unconfirmed_anchor` are
+cacheable. A candidate hit is revalidated against the current explicit source,
+anchor, schema, hashes, budgets, and state transition. Source or anchor drift is a
+miss. A corrupt cache candidate fails closed as a cache input: the builder
+discards it and rebuilds from the current explicit source/anchor inputs, and
+corrupt content is never returned or displayed as a hit.
+
+A hit preserves the evidence state, excerpt bytes, byte span, and capture time.
+It changes the cache status to `hit` and recomputes the row digest. Empty/failure
+states use `not_used`. Renderers never read or write cache entries.
+
+## Checkpoint rendering
+
+`render_markdown` and `render_html` require an explicit in-memory
+`ref_slug -> exact session-held source text` map for every source-bound row.
+Before display they replay `verified_exact_match`, `agent_extracted`, and
+`unconfirmed_anchor` against that text. Missing replay text is a render failure:
+a self-consistent row plus unkeyed digests cannot prove where writer-controlled
+text came from.
+
+The renderers do not retrieve or open a source, corpus item, sibling path, URL,
+DOI, cache, environment variable, or model tool. Replay validation recomputes
+the strict once-decode and source-bound hashes, but never decodes the stored
+display value again, extracts new text, derives a new state, or mutates the row.
+
+Markdown and HTML surfaces use the same fixed evidence labels and treat every
+claim, locator, source label, detail, decoded anchor, and excerpt as untrusted
+data. A payload cannot create a tag, comment, link, image, heading, fence, extra
+table cell/row, or prompt instruction. Only bounded stored evidence appears;
+surrounding source context never does.
+
+The default and maximum page size are 25 rows; a caller may request a smaller
+positive page. Each page reports its one-based page, total pages, row interval,
+and total rows. There is no render-all mode and no total-row cap. Walking the
+pages preserves every row exactly once in document order.
+
+## Rights and privacy
+
+Rows default to:
+
+```json
+{
+  "sharing_scope": "session_only",
+  "rights_basis": "not_assessed"
+}
+```
+
+A user-confirmed shareable row must pair with
+`rights_basis=user_declared_authorized`. The contract never infers permission from
+source location or availability. A 25-word excerpt is an adjudication aid, not a
+license finding. Exporters that cannot preserve the caveat remove the excerpt.
+
+No full text, abstract, private notes, surrounding context, API credential, or
+rendered markup belongs in an evidence row.
+
+## Legacy and degradation
+
+A positively identified pre-#656 Schema 5 report may omit `evidence_rows`; use
+the explicit `--allow-legacy-absence` compatibility flag to render it as
+`LEGACY — EVIDENCE ROWS UNAVAILABLE`. Missing shape alone is not legacy proof,
+and render fails without the flag. Do not interpret absence as an empty
+successful check and do not synthesize historical excerpts. A current producer
+with selected tuples must emit corresponding rows, including explicit empty
+states, and may never use the compatibility flag.
+
+For a current report, distinct row `claim_id` count must equal
+`E_claims.checked`, distinct claims with Phase E verdict `VERIFIED` must equal
+`E_claims.verified`, and rows sharing one `claim_id` must repeat the same claim
+object and verdict. These checks reject an empty-success carrier and
+contradictory multi-source rows. Exact tuple coverage is still audited against
+the E1 Claim Registry, which remains the selection authority and is not copied
+into a second V1 machine manifest.
+
+Failure states do not alter Phase E verdict taxonomy or gate logic. The evidence
+row is an adjudication view, not a new closure condition.
+
+## Human-read boundary
+
+Seeing an excerpt at a checkpoint is not reading the source. Evidence-row build,
+validation, cache replay, and rendering never call `/ars-mark-read`, never write a
+human-read log, and never change `human_read_source`, `read_scope`, latest-event
+resolution, or LOW-WARN promotion.
+
+## Consumer rule
+
+Consumers reference this protocol and the schema by pointer. They consume the
+machine row, not a copied enum or a parsed rendered table. They may not upgrade
+`unconfirmed_anchor`, `not_checked`, `source_missing`, `access_failed`,
+`retrieval_failed`, or `anchorless` into evidence-bearing states.
+
+## Version 1.1 (`evidence-row/1.1`) authority-profile advisory extension (#681)
+
+`shared/contracts/evidence/evidence_row_v1_1.schema.json` is a separate closed
+version for `surface=authority_profile_content_coverage`. It does not extend the
+Phase E row in place: `claim`, `verdict`, and `detail` are absent, and exact
+`requirement_pointer`, `authority_anchor_pointer`,
+`structured_expectations[]` pointer/digest, packet artifact, and advisory
+document-locator bindings replace them. Version 1.0 producer behavior, cache
+semantics, persisted bytes, and Phase E rendering remain unchanged. A page may
+contain only one evidence-row version/surface.
+
+The 1.1 builder is `build_advisory(...)`. It records only passage provenance;
+it never chooses an `advisory_coverage_status`, interprets a structured
+expectation, opens a packet path, retrieves content, or calls a model/API. The
+closed states are:
+
+- `agent_extracted`: a once-decoded, bounded quote is an exact substring of the
+  explicitly supplied artifact string;
+- `checked_no_match`: the explicit artifact string was checked, with no quote
+  or excerpt persisted; and
+- `not_checked`, `source_missing`, `access_failed`, and `retrieval_failed`:
+  explicit unperformed/empty states with null content binding and excerpt.
+
+Both source-bound states require replay from an explicit
+`artifact_id -> exact session-held content` map before rendering. V1.1 retains
+the same strict once-decode, 25-word/1,000-code-point bounds, exact UTF-8 content
+hash and byte-span rules, inert Markdown/HTML treatment, rights pairing, and
+human-read-ledger noninterference. It deliberately fixes `cache.status` to
+`not_used` and `cache.key_sha256` to null.
+For a positive row, `captured_at` is the explicit RFC 3339 timestamp carried by
+the closed advisory draft; it is not invented from the authority-context
+confirmation time or the runtime clock.
+
+V1.1 rows are nested only in the replay-bound
+`content-coverage-advisory/1.0` carrier defined by
+`shared/contracts/human_subjects/content_coverage_advisory.schema.json` and
+`shared/references/authority_content_coverage_advisory_protocol.md`. Their
+labels remain `LLM-ADVISORY`; neither an exact passage nor a checked-no-match
+state changes #667 deterministic status, readiness, authorization, or
+institutional acceptance, and neither is an adequacy or efficacy finding.
+
+## Version 1.2 cross-document consistency extension (#672)
+
+`shared/contracts/evidence/evidence_row_v1_2.schema.json` is a separate closed
+version whose only surface is `cross_document_consistency`. It is nested only in
+`cross-document-consistency-advisory/1.0` and is finalized and replayed by
+`scripts/build_cross_document_consistency_advisory.py`. It does not widen either
+earlier schema or enter the Phase E Integrity Report. The 1.0 and 1.1 schemas,
+`scripts/evidence_rows.py` behavior, cache semantics, rendering, and serialized
+identities remain unchanged; versions and surfaces cannot be mixed.
+
+One 1.2 row is the complete ordered evidence unit for one observation. The first
+three pair kinds have two logical-role slots. Manuscript/preregistration has
+exactly three: `manuscript_report`, `preregistration`, then the manuscript-bound
+`disclosure_scope`. Logical roles remain distinct even when several bind the
+same accepted manuscript bytes.
+
+Its states are `agent_extracted`, `checked_no_match`, `not_checked`,
+`source_missing`, `access_failed`, and `retrieval_failed`. A quote is exact-span
+replayed. `checked_no_match` binds an exact, non-empty, named source scope and
+only records the caller's semantic assertion that no counterpart was located;
+it does not prove semantic absence or scope completeness. Methods absence
+requires one quote plus a checked counterpart scope. An undisclosed
+preregistration deviation requires two quotes plus its third checked disclosure
+scope. Consumers cannot promote an unavailable or unperformed slot.
+
+V1.2 retains strict single percent decode with literal `+`, the 25-word and
+1,000-code-point ceilings, exact strict-UTF-8 hash/span replay, inert rendering,
+and paired sharing/rights values. It performs no cache lookup, model/API call,
+retrieval, normalization, or ambient-clock read. One canonical `row_sha256`
+binds the complete bilateral or trilateral row.
+
+The row supports only a caller-supplied `LLM-ADVISORY` / `UNMEASURED`
+observation. It creates no PASS/FAIL, score, gate, clean/agreement certificate,
+ClaimIntent, revision authority, or consent/protocol finding. See
+`shared/references/cross_document_consistency_advisory_protocol.md`.
+
+## Version 1.3 claim-standing advisory surface (#655)
+
+`shared/contracts/evidence/evidence_row_v1_3.schema.json` defines
+`evidence-row/1.3`, surface `claim_standing_advisory`: one provenance-only row
+per (probe claim, selected work-family candidate) in the #655 claim-standing
+probe. The row binds a bounded inspected-evidence excerpt to the exact source
+content hash and UTF-8 span, reuses the family's cache, content-handling, and
+row-hash blocks verbatim, and carries a `coverage` declaration
+(`abstract` / `session_held_full_text` / `metadata_only`) in place of 1.0's
+anchor: the two anchor-derived excerpt states do not exist on this surface.
+Cross-field conditionals bind retrieved states to a full payload and a bound
+source, non-retrieved states to null payloads and `contains_external_text:
+false`, the rights coupling in both directions, and metadata-only coverage to
+failure states with a null source hash. The row never carries a stance or
+verdict; an exact excerpt match never determines stance; abstract-level
+coverage is never rendered as verified full text. The consuming stance record
+(`claim-standing-stance-record/1.0`) references rows by id AND row hash. No
+runtime validator for this surface exists yet — the future stance runner owns
+replay verification before rendering.

package/vendor/ars/shared/references/firm_rules.md

@@ -0,0 +1,90 @@
+# Firm Rules — Canonical Source
+
+This file is the **single source of truth** for firm-rule wording that is otherwise duplicated verbatim across agent prompts. Each block below is the canonical text; the agent prompts listed under "Mirrored in" carry a byte-identical copy (modulo the agent's self-reference noun, where noted). `scripts/check_firm_rules_sync.py` fails CI if any mirror drifts from the canonical block here.
+
+**Why this file exists:** the contamination `R-L3-2-*` wording provably drifted between v3.9.0 (contamination-only) and v3.9.4 (contamination-AND-temporal) drafts before being single-sourced here. Manual 5×-duplication is not enough; the sync lint pins it.
+
+**Related mechanisms:** the Phase Boundary enforcement-status sentence (factual status prose, not a behavioral firm rule) is single-sourced as `CANONICAL_ENFORCEMENT` inside `scripts/check_v3_9_2_phase_boundary.py` (#491) rather than here — same defrift goal, separate mechanism co-located with its only consumer.
+
+**ID namespaces (do NOT confuse — they were overloaded until v3.10 PR-A):**
+
+- `R-L3-2-*` = **contamination advisory** rules (origin: v3.7.3 spec §3.2 L3-2; extended v3.9.0 §3.3). Original holder of the `R-L3-2` ID.
+- `R-CIM-*` = **Claim Intent Manifest emission** rules (origin: #103 claim-alignment spec; the agent prompts borrowed `R-L3-2-A/B/C` until v3.10 PR-A renamed them to remove the collision).
+- `R-L3-1-*` = per-citation locator gate (v3.7.3 §3.1). Not mirrored here.
+
+---
+
+## Contamination advisory firm rules (R-L3-2-*)
+
+> **Canonical wording note:** R-L3-2-A carries the **v3.10 PR-B broad form** (default-advisory + opt-in strict extension across contamination AND temporal namespaces; temporal strict not yet wired). This block is the single source of truth for the wording; the contamination mirrors below are intentionally *by-ID references*, not full-block copies (see the "Mirrored in (contamination rules)" note).
+
+<!-- canonical:R-L3-2-A -->
+- **R-L3-2-A (default-advisory + opt-in strict extension):** By default, contamination and temporal-integrity signals never block emission on their own; in a namespace that accepts a `strict` value, a user-enabled strict terminal policy may promote that namespace's specified signals to non-acknowledgeable terminal blockers. v3.10 accepts a strict value for `contamination_triangulation` only; `temporal_integrity` accepts `advisory` only (no temporal strict path exists yet). This follows the v3.5 Collaboration Depth Observer + v3.6.8 LOW-WARN precedent: hard-gating contamination by default would amount to refusing to cite mid-2024+ preprints en masse, which is too coarse — so the terminal promotion is opt-in (off by default), scoped to the namespace's accepted-strict signals, and surfaced via the §formatter terminal gate, never silently.
+<!-- /canonical:R-L3-2-A -->
+
+<!-- canonical:R-L3-2-B -->
+- **R-L3-2-B (no retroactive computation):** bibliography_agent computes contamination_signals at ingest time, not at audit time. Re-running the check post-hoc on existing entries is a separate batch operation (deferred to user invocation; not part of the cite-time finalizer).
+<!-- /canonical:R-L3-2-B -->
+
+<!-- canonical:R-L3-2-C -->
+- **R-L3-2-C (triangulation count over present fields):** k is computed over `*_unmatched` fields that are present. Absent fields are excluded from the count and do not default to either `true` or `false`. k_max reflects how many lookups were successfully run; the (k, k_max) pair together determines the annotation tier.
+<!-- /canonical:R-L3-2-C -->
+
+<!-- canonical:R-L3-2-D -->
+- **R-L3-2-D (no API-inferred classification):** OpenAlex's `primary_location.source.type` and Crossref's `type` fields, even when returned by the APIs for matched entries, MUST NOT be used to derive any classification (venue_type, scope category, hard-block eligibility). The k=3 case makes those classifications structurally unavailable; including them in any classification logic creates fake precision.
+<!-- /canonical:R-L3-2-D -->
+
+<!-- canonical:R-L3-2-E -->
+- **R-L3-2-E (gate refusal list unchanged by advisory tiers; terminal blocks ride a separate generic rule):** All triangulation *annotations* are advisory. The terminal gate **refusal list** is NOT extended by any advisory marker shape. The gate's **advisory pass-through allowlist** MUST be extended in lockstep with any new advisory suffix so that new advisory suffixes are not accidentally routed through a refusal rule. The fix for a new advisory suffix is pass-through-list expansion, not refusal-list change. v3.10 adds a *generic* terminal-refusal rule (formatter rule 11) that fires on any unresolved `severity=HIGH-BLOCK` token inside a `<!--ref:...-->` marker — it is NOT a per-suffix refusal entry, so the advisory suffix table and pass-through allowlist stay unchanged when a strict policy promotes a signal. The formatter is STAMP-CHECK ONLY: it compares each marker's `policy_hash` against the passport's current `terminal_policies` (freshness guard) and never re-runs policy logic; the finalizer is the sole policy evaluator.
+<!-- /canonical:R-L3-2-E -->
+
+<!-- canonical:R-L3-2-F -->
+- **R-L3-2-F (retraction authority is canonical and advisory-first):** A v1.1 `bibliographic_integrity_signals[].retraction_status` row is the only retraction-status authority. Legacy `retraction_check` is a process attestation only. Detection is unconditional; absent `terminal_policies.retraction` is advisory. Only the citation finalizer may promote an eligible current, undisputed retracted row under explicit `strict`; reinstated, stale, unknown/degraded, resolver-disagreement, and deterministic declared-legitimate-use rows never promote. The ethics agent points to this result and the formatter remains stamp-only. No retraction advisory marker token is minted.
+<!-- /canonical:R-L3-2-F -->
+
+**Mirrored in (contamination rules):**
+
+- `academic-paper/agents/formatter_agent.md` — R-L3-2-A + R-L3-2-E (in the contamination pass-through paragraph).
+- `deep-research/references/crossref_api_protocol.md` — R-L3-2-A (user-discretion reference).
+- `deep-research/references/openalex_api_protocol.md` — R-L3-2-A reference.
+- `academic-pipeline/agents/pipeline_orchestrator_agent.md` — R-L3-2-C / R-L3-2-D / R-L3-2-E (finalizer logic).
+- `deep-research/agents/bibliography_agent.md` — R-L3-2-B (ingest-time computation).
+- `shared/bibliographic_integrity_signals.md`, `deep-research/agents/ethics_review_agent.md`, and `docs/design/2026-08-08-651-retraction-status-spec.md` — R-L3-2-F.
+
+> These mirrors are **intentionally by-ID prose references**, not full-block copies (e.g. crossref's "the user retains discretion per R-L3-2-A", the formatter's "advisory per ... R-L3-2-A + R-L3-2-E"). The wording lives in exactly one place — the canonical block above — so the single-source goal (D3) is met without duplicating the full rule text into five files. The v3.10 PR-B reword therefore changes ONLY the canonical block, not the mirrors. Because the mirrors are by-ID references, the sync lint does NOT wording-check them; it (1) ID-guards the contamination side (no contamination context reuses an `R-CIM-*` ID, no claim-manifest surface reuses an `R-L3-2-*` ID), and (2) **contradiction-guards** the contamination mirrors against phrasing that would contradict the broad reword — a by-ID reference's surrounding prose MUST NOT assert an unqualified "advisory only" / "never block" / "cannot block" / "must not block" / "non-blocking" claim, since a strict terminal policy can now block (see `check_firm_rules_sync.py` contradiction guard). (Wording-sync IS enforced for the `R-CIM-*` blocks below, whose mirrors ARE full-block copies.)
+
+---
+
+## Claim Intent Manifest emission firm rules (R-CIM-*)
+
+> Renamed from `R-L3-2-A/B/C` in v3.10 PR-A to remove the ID collision with the contamination rules above. The three writing-stage agents emit a claim intent manifest; the only difference between mirrors is the agent's self-reference noun ("synthesis agent" / "compiler" / "writer"), which the sync lint normalizes before comparison.
+
+<!-- canonical:R-CIM-A -->
+- **R-CIM-A (one-shot pre-commitment):** Emit exactly ONE manifest entry per <AGENT> invocation, BEFORE the first prose block. No later mutation, no append, no re-emission within the same invocation. Drafting that introduces a claim not in the manifest produces a `claim_drifts[]` entry with `drift_kind=EMITTED_NOT_INTENDED` downstream — that detection is the design intent (drift is surfaced, not silenced). The manifest is the pre-commitment artifact the audit diffs against; rewriting it mid-draft would hide the signal.
+<!-- /canonical:R-CIM-A -->
+
+<!-- canonical:R-CIM-B -->
+- **R-CIM-B (no audit responsibility):** The <AGENT> emits manifests; it does NOT detect drift, re-judge supported / unsupported, or read other manifests. The §"Manifest cross-reference (D6)" set-diff lives in `claim_ref_alignment_audit_agent.md`. Mirrors the v3.6.7 partial-inversion discipline: narrative-side emits, audit-side reads.
+<!-- /canonical:R-CIM-B -->
+
+<!-- canonical:R-CIM-C -->
+- **R-CIM-C (no frontmatter reading):** Generate `claim_text`, `intended_evidence_kind`, `planned_refs`, and any `negative_constraints[].rule` values from the corpus + prompt context already provided. You MUST NOT read entry frontmatter to discover candidate claims — the same partial-inversion rule that gates anchor selection in v3.7.3 R-L3-1-C. The orchestrator allocates a fresh `manifest_id` per invocation (M-INV-4); never copy a `manifest_id` from a sibling manifest.
+<!-- /canonical:R-CIM-C -->
+
+**Mirrored in (claim-manifest rules):**
+
+- `deep-research/agents/synthesis_agent.md` (`<AGENT>` = "synthesis agent")
+- `deep-research/agents/report_compiler_agent.md` (`<AGENT>` = "compiler"; R-CIM-B carries an extra standalone-mode sentence — see prompt)
+- `academic-paper/agents/draft_writer_agent.md` (`<AGENT>` = "writer")
+- `shared/contracts/passport/claim_intent_manifest.schema.json` — references `R-CIM-A` by ID in the `claims` field description.
+
+---
+
+## Collision guard
+
+`scripts/check_firm_rules_sync.py` additionally asserts:
+
+1. No `R-L3-2-A/B/C` token appears inside any `## Claim Intent Manifest Emission` prompt section or inside `claim_intent_manifest.schema.json`.
+2. No `R-CIM-A/B/C` token appears inside any contamination context (formatter pass-through paragraph, crossref/openalex protocol, finalizer logic, contamination specs).
+
+This pins the v3.10 PR-A disambiguation against regression.