psyclaw 0.27.23 → 0.28.1

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

@@ -0,0 +1,118 @@
+# Protected Hedging Phrases
+
+**Spec:** v3.6.7 §7.1 — pattern protection reference for `report_compiler_agent` (abstract-only mode), Pattern C1.
+
+**Audience:** Upstream calibration agents (academic-paper Stage 4, deep-research Phase 3 abstract handoff). The downstream `report_compiler_agent` reads this reference indirectly through the dispatch context that upstream calibration produces.
+
+**Why this exists:** Live ARS pipeline runs surfaced a recurring failure where the abstract compiler, under hard word-count pressure (i.e., a fixed word budget set by the publisher), dropped epistemic hedges that the body of the paper depended on. The fix routes through a roster of protected hedging phrases that ride in the dispatch context to the compiler. A claim qualified by "may," "tentative," "preliminary," or "in this institutional context" in the body became unconditional in the abstract. The compression-driven drift created compression overclaim — the abstract no longer accurately represented the paper's epistemic stance, which is a publication-integrity failure.
+
+The fix is to make hedging phrases **budget-protected**: upstream calibration marks specific phrases as protected, the protected list rides in the dispatch context to the abstract compiler, and the compiler honours the protection ahead of any other compression target.
+
+---
+
+## What counts as a protected hedging phrase
+
+A phrase qualifies as protected when **dropping it changes the paper's truth-claim**, not merely its rhetorical register. Three categories cover most cases:
+
+### 1. Epistemic hedges that bound the claim
+
+Words and phrases that mark a claim as conditional, tentative, or under-evidenced. Removing them upgrades the claim to assertion.
+
+**Examples:**
+- "may," "might," "could" (modal hedges on causal or predictive claims)
+- "tentative," "preliminary," "exploratory" (status hedges on findings)
+- "suggests," "indicates," "is consistent with" (inferential hedges, distinct from "demonstrates," "proves," "establishes")
+- "in our sample," "for this cohort," "under the conditions tested" (scope hedges)
+
+**Why protected:** A reader who acts on an unconditional version of the claim takes on more risk than the evidence justifies. In academic abstracts this is overclaim; in policy abstracts this is misinformation.
+
+### 2. Reflexivity / positionality markers
+
+Phrases that disclose the author's relationship to the studied phenomenon. Removing them obscures the position from which the work was done.
+
+**Examples:**
+- "from a former evaluator's perspective" (positional)
+- "as participants in the [year-range] reform" (involvement)
+- "the authors served on the [committee] from [year] to [year]" (institutional role)
+- "this analysis draws on the first author's experience as [role]" (experiential)
+
+**Why protected:** Disclosure obligations under most journal policies (BMJ, Nature, social-science conventions) require positionality to ride in the abstract when it materially shapes interpretation. Stripping disclosure for word count violates the policy, not just the rhetorical norm.
+
+### 3. Temporal disambiguation markers
+
+Phrases that pin a claim or a positional statement to a specific time window. Removing them creates temporal ambiguity that downstream readers cannot resolve.
+
+**Examples:**
+- "between 2020 and 2024" (explicit year range)
+- "during their term as [role] in [year]" (role-bounded period)
+- "former [role]" (closed temporal status)
+- "at the time of the [event]" — only protected when the event is named immediately adjacent; otherwise the deictic phrase is itself the failure mode (see `feedback_ars_phase2_phase3_downstream_agent_patterns.md`).
+
+**Why protected:** Deictic temporal phrases ("during this period," "at the time," "currently") read differently when separated from their anchoring context. The abstract has no neighbouring context; an abstract-level deictic is unresolvable.
+
+---
+
+## Upstream calibration: how to mark phrases as protected
+
+Upstream calibration runs at the end of paper drafting, after the body text is stable but before abstract compilation. The calibration agent walks the paper and identifies phrases in the three categories above, then emits a `protected_hedges` block in the dispatch payload to the abstract compiler.
+
+### Dispatch block shape
+
+```yaml
+protected_hedges:
+  epistemic:
+    - phrase: "may"
+      anchored_at: "Section 4, claim about institutional adoption rate"
+      why: "claim is observational, not causal"
+    - phrase: "tentative"
+      anchored_at: "Section 5, conclusion about policy effect"
+      why: "n=12 sites, no comparison group"
+  reflexivity:
+    - phrase: "as a former evaluator on the [committee] between 2020 and 2024"
+      anchored_at: "Author note + Section 1"
+      why: "BMJ-equivalent disclosure obligation; informs how reader weights argument"
+  temporal:
+    - phrase: "between 2020 and 2024"
+      anchored_at: "Section 1, paragraph 2; Section 6, conclusion"
+      why: "abstract-level deictic ('at the time') would be unresolvable"
+```
+
+### Calibration rules
+
+1. **Conservative inclusion.** When in doubt, include the phrase. Calibration cannot recover a hedge it did not list — the compiler treats every entry on the list as non-negotiable, so omitting a phrase removes that protection regardless of intent.
+2. **Anchor every entry.** Each protected phrase must cite where in the paper it operates and one-line why. Without the anchor, the abstract compiler cannot judge replacement-vs-preservation when budget is tight.
+3. **No duplicates.** One entry per phrase. The compiler counts protected phrases against the budget once.
+4. **Calibration is mode-specific.** Deep-research INSIGHT abstracts and academic-paper journal abstracts have different convention (see `word_count_conventions.md`). Calibration runs once per target mode, not once per paper.
+
+---
+
+## Abstract compiler: how protection is honoured
+
+The `report_compiler_agent` abstract-only mode treats protected hedges as **non-negotiable budget**. Concretely:
+
+1. **Budget allocation order.** Protected hedges are reserved before any other content competes for budget, because they are non-negotiable.
+   - Step 1: Compute hard cap (whitespace-split, see `word_count_conventions.md`).
+   - Step 2: Reserve 3–5% buffer.
+   - Step 3: **Reserve words for protected hedges.** Sum the word count of every entry in `protected_hedges` (verbatim). This subtotal is non-negotiable budget.
+   - Step 4: Allocate the remaining words to required structural slots (research question, method, finding, implication).
+   - Step 5: Spend any words still remaining on rhetorical polish, transitions, secondary findings.
+
+2. **Verbatim preservation rule.** A protected phrase rides verbatim into the abstract. The compiler does not paraphrase, compress, or substitute a synonym for a protected phrase. (A future v3.6.7+ extension may add an optional `approved_synonyms` field to the dispatch block; until then, verbatim only.)
+
+3. **Cut order under budget pressure.** When the draft exceeds budget, cuts come from Step 5 first (rhetorical polish), then Step 4 (compress structural slots), **never** from Step 3 (protected hedges).
+
+4. **Failure surface.** If the abstract cannot fit Steps 1–4 within hard cap, the compiler **reports the conflict** rather than dropping a protected hedge. The conflict goes back to upstream calibration to either renegotiate the protected list or the publisher's word cap.
+
+---
+
+## Where this protocol is enforced
+
+The `report_compiler_agent` abstract-only mode prompt enforces the dispatch-context protocol and the budget allocation order. The authoritative protection clause lives in `deep-research/agents/report_compiler_agent.md` under `PATTERN PROTECTION (v3.6.7)`. This file defines what counts as a protected hedge, the upstream calibration shape, and the compiler's budget allocation order; the agent prompt cites this file by path. Cross-model audit covers protected-hedge preservation under the report_compiler bundle's Section 4(f) check in `shared/templates/codex_audit_multifile_template.md`.
+
+---
+
+## Cross-references
+
+- `shared/references/word_count_conventions.md` — whitespace-split standard, 3–5% buffer rule, publisher conventions.
+- `shared/templates/codex_audit_multifile_template.md` — audit dimensions including compression overclaim detection.
+- `docs/design/2026-04-29-ars-v3.6.7-downstream-agent-pattern-protection-spec.md` §3.3 (C1) — pattern definition and provenance.

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

@@ -0,0 +1,109 @@
+# Psychometric Terminology Glossary
+
+**Spec:** v3.6.7 §7.1 — pattern protection reference for `research_architect_agent` (survey designer mode), Pattern B2.
+
+**Audience:** Agents drafting Likert / rating-scale items in survey instruments. Human authors reviewing instrument drafts before pilot testing.
+
+**Why this exists:** Live ARS pipeline runs surfaced two recurring failures in instrument design: (a) items labelled "reverse-coded" that were actually contrast items measuring a different construct, and (b) acquiescence- and recall-bias mitigations that look in place but do not operate. Both failures pass casual peer review and surface only at scale validation, by which point the instrument has already been deployed. This reference defines the operational distinctions the survey designer must respect.
+
+---
+
+## True reverse-coded item vs. contrast item
+
+These are distinct instrument-design tools that look identical to a casual reader. Conflating them invalidates the construct.
+
+### True reverse-coded item
+
+**Operational definition:** A negatively-keyed statement of the **same construct** along the **same Likert dimension**. After numeric reversal of the response value, it contributes to the same scale score as positively-keyed items.
+
+**Necessary conditions:**
+- Same construct: if the positive item probes "perceived institutional support," the reverse item probes the absence of perceived institutional support, not a different construct.
+- Same dimension: agreement-disagreement remains the response axis; frequency or intensity does not get substituted in.
+- Reverse-scoring is mechanically valid: a respondent with high construct standing should give high agreement on positive items and low agreement on the reverse item, such that the reverse item's reversed score aligns with the positive items.
+
+**Correct example pair (construct: perceived institutional support):**
+- Positive: "My institution provides the resources I need to do my work well." (1=strongly disagree → 5=strongly agree)
+- True reverse: "My institution leaves me without the resources I need to do my work." (same scale; respondents high in perceived support disagree with this)
+
+**Why this works:** Both items load on a single latent factor. Confirmatory factor analysis on a piloted dataset will show comparable factor loadings (after sign reversal) and similar item-total correlations.
+
+### Contrast item
+
+**Operational definition:** A statement that probes a **different construct** (or a different dimension of the same construct) and is included to measure something else — discriminant validity, related-but-distinct construct, social-desirability check.
+
+**Why it is not reverse-coding:**
+- A contrast item's score should NOT be combined with the focal scale's score. It belongs on its own scale or its own analysis.
+- Reverse-scoring a contrast item produces a meaningless number.
+- Treating a contrast item as a reverse-coded item dilutes the focal scale's reliability (Cronbach's alpha drops; factor loadings become incoherent).
+
+**Example contrast (NOT a reverse-coded support item):**
+- "I find my work intrinsically meaningful." — This probes intrinsic motivation, not perceived institutional support. It is contrast / divergent-validity, not a reverse item.
+
+### Decision rule for the survey designer
+
+For every item labelled "reverse-coded," the agent must produce a one-line construct-equivalence justification:
+
+> "Item X is true reverse-coded relative to focal items Y because it probes the same construct (perceived institutional support) on the same Likert dimension (agreement). It is not a contrast item probing a related construct."
+
+If that justification cannot be written without slipping into a different construct, the item is **not** reverse-coded — it is a contrast item, and it must either move to its own scale or be removed.
+
+---
+
+## Acquiescence-bias mitigation
+
+**The bias:** Respondents systematically agree with statements regardless of content. Pure-positive scales over-estimate construct standing.
+
+**The standard mitigation:** Mix positive and true-reverse-coded items so that an acquiescing respondent cannot maximise scale score by agreeing throughout.
+
+**The failure mode flagged in v3.6.7 patterns:** "Pseudo-reverse" items that look reverse-coded but are actually contrast items, leaving the scale effectively pure-positive. The pseudo-mitigation is worse than no mitigation because it gives the appearance of having addressed acquiescence while leaving it operative.
+
+**Designer requirement:** Apply the construct-equivalence justification rule (above) to every reverse-coded item. If any "reverse-coded" item fails the justification, that item is mislabelled — it is a contrast item and must either move to its own scale or be removed. A scale that ends up with no surviving reverse-coded item after this filter has not mitigated acquiescence bias and needs redesign before pilot.
+
+---
+
+## Recall-bias mitigation
+
+**The bias:** Respondents misremember the timing or details of past events. Two failure modes are common:
+
+1. **Calendar drift:** Asking "in the last 12 months" without anchoring to a salient event produces noisy recall — respondents reconstruct an approximate window, not a true 12-month boundary.
+2. **Telescoping:** Memorable events get pulled forward in time ("that happened last year" when it happened 18 months ago), inflating recent-period rates.
+
+**The standard mitigation:** Event-anchored phrasing — anchor the recall window to a salient, datable event the respondent's unit shares.
+
+**Correct phrasing (event-anchored, generic):**
+> "Thinking about the period immediately before [the unit-specific event] happened to your unit, how often did X occur?"
+
+**Correct phrasing (event-anchored, project-specific):**
+> "Thinking about the period before your institution announced the merger in [month-year], how often did you experience X?"
+
+**Calendar-anchored phrasing — only acceptable when the entire sample shares a common event date:**
+> "In the 6 months following the [common event] of [specific date], how often did you experience X?"
+
+**Wrong phrasing (calendar-only, no event anchor):**
+> "In the last 12 months, how often did X occur?" — This invites calendar drift and telescoping; the respondent has no shared anchor.
+
+**Designer requirement:** Default retrospective items to event-anchored phrasing. Only use calendar-anchored phrasing when the sample provably shares a common event date and that date is named in the item. When the event-anchor is absent, the item is not recall-bias-mitigated, even if it superficially looks like a retrospective survey item.
+
+---
+
+## Quick decision table
+
+| Designer choice | Operational test | Failure flag |
+|---|---|---|
+| Item is reverse-coded | One-line construct-equivalence justification holds | Pseudo-reverse (contrast item mislabeled) |
+| Acquiescence mitigated | At least one true reverse-coded item per scale AND every item labelled reverse-coded passes the construct-equivalence test | Pure-positive scale or pseudo-reverse mitigation |
+| Recall-bias mitigated | Item anchors recall to a salient event the unit shares | Calendar-anchored without shared event date |
+
+---
+
+## Where this glossary is enforced
+
+The `research_architect_agent` survey designer mode prompt enforces construct-equivalence justification, acquiescence-bias counting, and event-anchored phrasing. The authoritative protection clause lives in `deep-research/agents/research_architect_agent.md` under `PATTERN PROTECTION (v3.6.7)`. This file defines the construct-equivalence test, the acquiescence-mitigation rule, and the event-anchoring decision rule; the agent prompt cites this file by path.
+
+---
+
+## References
+
+- DeVellis, R. F. (2017). *Scale Development: Theory and Applications* (4th ed.). Sage. — reverse-coding and acquiescence bias.
+- Tourangeau, R., Rips, L. J., & Rasinski, K. (2000). *The Psychology of Survey Response*. Cambridge. — recall bias and event anchoring.
+- Loftus, E. F., & Marburger, W. (1983). Since the eruption of Mt. St. Helens, has anyone beaten you up? Improving the accuracy of retrospective reports with landmark events. *Memory & Cognition*, 11(2), 114–120. — primary empirical source for event-anchoring effect.

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

@@ -0,0 +1,238 @@
+# Review criteria consumer protocol (#684)
+
+This protocol binds the #683 `ReviewTargetContext` across formative planning,
+the academic-paper internal evaluator, and the academic-paper-reviewer external
+panel. The binding is workflow conformance only. It never determines severity,
+an editorial verdict, a checkpoint state, or author triage.
+
+Normative design:
+`docs/design/2026-08-11-684-review-criteria-consumer-binding-spec.md`.
+Schemas:
+`shared/contracts/review_target/review_criteria_binding_manifest.schema.json`
+and
+`shared/contracts/review_target/constructive_review_findings.schema.json`.
+Tool: `scripts/review_criteria_binding.py`.
+
+## 1. Inputs and authority
+
+The orchestrating layer receives four explicit inputs:
+
+1. the author-confirmed `ReviewTargetDeclaration` already embedded in the
+   resolved context;
+2. the exact `ReviewTargetContext` JSON;
+3. the exact criteria registry named by that context; and
+4. a caller-supplied `target_review_id`.
+
+Initialize one manifest before any of the three consumers run:
+
+```bash
+python scripts/review_criteria_binding.py init \
+  --context phase0/review_target_context.json \
+  --context-ref phase0/review_target_context.json \
+  --registry shared/review_criteria_registry.json \
+  --registry-ref shared/review_criteria_registry.json \
+  --target-review-id review-001 \
+  --output phase0/review_criteria_binding.json
+```
+
+If an active manifest exists, pass it as `--prior-manifest`. A substantive
+context change under the same `target_review_id` is a conflict. Starting a new
+target review requires a new id and makes the predecessor non-comparable.
+
+The manifest is the exact source of:
+
+- `context_ref` and its raw SHA-256;
+- `resolved_digest`;
+- ordered `selected_criterion_ids`;
+- exact criterion id/version/content-digest pointers;
+- unresolved target dimensions; and
+- parallel interdisciplinary conflict groups.
+
+Consumers never reconstruct these fields from the Markdown brief and never
+copy registry statements into their own instruction files.
+
+## 2. Marker and receipt lifecycle
+
+Before dispatch, render the role-specific marker:
+
+```bash
+python scripts/review_criteria_binding.py marker \
+  --manifest phase0/review_criteria_binding.json \
+  --consumer formative_planning --role FORMATIVE
+```
+
+The marker is appended verbatim to the consumer's output. After a successful
+consumer call, the output also carries exactly one
+`criteria_parallel_conflicts: <canonical compact JSON array>` line rendered
+from the manifest. Record only explicitly named artifacts:
+
+```bash
+python scripts/review_criteria_binding.py record \
+  --manifest phase0/review_criteria_binding.json \
+  --consumer formative_planning \
+  --artifact FORMATIVE=phase2/paper_outline.md
+```
+
+The internal receipt similarly names the paper-blind Phase 6a artifact, not
+the later paper-visible decision:
+
+```bash
+python scripts/review_criteria_binding.py record \
+  --manifest phase0/review_criteria_binding.json \
+  --consumer internal_evaluator \
+  --artifact INTERNAL=phase6/phase6a_precommitment.md
+```
+
+For the external panel, supply all five Phase 1 artifacts in one call:
+
+```bash
+python scripts/review_criteria_binding.py record \
+  --manifest phase0/review_criteria_binding.json \
+  --consumer external_panel \
+  --artifact EIC=phase1/eic.md --artifact R1=phase1/methodology.md \
+  --artifact R2=phase1/domain.md --artifact R3=phase1/perspective.md \
+  --artifact DA=phase1/da.md
+```
+
+The recorder checks the complete marker and exact conflict line inside every
+artifact, computes raw hashes itself, and appends one receipt atomically. Exact
+retry is a no-write. Same-consumer drift is a conflict.
+
+Before a review crosses its handoff boundary, run:
+
+```bash
+python scripts/review_criteria_binding.py validate \
+  --manifest phase0/review_criteria_binding.json \
+  --context phase0/review_target_context.json \
+  --registry shared/review_criteria_registry.json \
+  --require-complete
+```
+
+## 3. Formative planning and writing
+
+Owner: `academic-paper` Phase 2 `structure_architect_agent`.
+
+- Phase 0 resolves the author-confirmed target before Phase 2.
+- The Structure Architect receives the pointer-only context and Target Criteria
+  Brief. Its outline names relevant criterion ids beside planned sections and
+  evidence needs, while keeping scientific validity, venue fit, and submission
+  readiness separate.
+- `argument_builder_agent` and `draft_writer_agent` consume the same context
+  pointer and the Structure Architect's receipt. They do not create a second
+  receipt, re-resolve the target, copy criterion prose into their prompts, or
+  silently change the author's contribution claim.
+- A criterion can motivate a planned check; it never licenses invented evidence,
+  results, methods, or a new research question.
+
+The formative output records `FORMATIVE` with the exact marker.
+
+## 4. Internal evaluator
+
+Owner: `academic-paper` Phase 6 `peer_reviewer_agent`.
+
+- Phase 6a receives the sprint/evaluator contract, paper metadata, the
+  pointer-only context, and Target Criteria Brief. It remains paper-blind.
+- Phase 6a commits the selected criterion ids and keeps each
+  `parallel_conflicts[]` group separate. It does not declare applicability.
+- The Phase 6a artifact records the `INTERNAL` receipt before any draft is
+  visible. Phase 6b receives that unchanged artifact and the draft, assesses
+  applicability, repeats the continuity marker, and emits its Critical/Major
+  constructive sidecar when applicable.
+
+The internal evaluator may identify a scientific-validity problem independent
+of venue fit. It may not turn missing or advisory venue guidance into a blocking
+finding.
+
+## 5. External panel, including DA
+
+Owner: the academic-paper-reviewer orchestrating layer.
+
+- Phase 0 uses author-confirmed target metadata. `field_analyst_agent` may
+  suggest panel expertise but cannot infer or overwrite venue/track/type.
+- Each of `EIC`, `R1`, `R2`, `R3`, and `DA` receives the same context authority
+  and brief during the existing paper-content-blind Phase 1 call.
+- Each Phase 1 output repeats its role-specific marker and commits the selected
+  criterion ids. Conflicting criteria stay parallel.
+- Phase 2 receives the unchanged Phase 1 output plus manuscript data. Findings
+  cite exact criterion pointers and manuscript evidence/absence anchors.
+- `editorial_synthesizer_agent` checks all five marker bindings before
+  synthesis. Missing or mismatched bindings abort the criteria-aware run; the
+  synthesizer never silently falls back to a self-recalled target.
+
+DA adversarial register does not relax the finding contract. Every DA Critical
+or Major item enters the same constructive sidecar and carries the same remedy,
+cost, trade-off, author-intent, and no-honest-remedy fields as another seat.
+
+## 6. Constructive finding sidecar
+
+The sidecar covers Critical/Major weaknesses only. Minor and copyedit channels
+retain their existing formats. Validate it with:
+
+```bash
+python scripts/review_criteria_binding.py validate-findings \
+  --manifest phase0/review_criteria_binding.json \
+  --context phase0/review_target_context.json \
+  --registry shared/review_criteria_registry.json \
+  --findings phase2/constructive_review_findings.json
+```
+
+Every row separates:
+
+- criterion pointers from manuscript evidence;
+- scholarly relevance from confirmed-target relevance;
+- the minimum viable remedy from a stronger costlier option;
+- effort scope from trade-offs; and
+- reviewer advice from author-owned research intent.
+
+If no honest remedy exists, `remedy_status=none`, both option fields are null,
+and `no_honest_remedy_reason` explains why. If a stronger option is not
+meaningful, it is null and `stronger_option_reason` explains why. An available
+option always records `proposed_result_values=false`; new data or intent change
+is an author choice, not an assertion that work or results exist.
+
+A stale/unverified or otherwise non-blocking criterion may appear in ordinary
+advisory prose, but the validator rejects a Critical/Major sidecar row whose
+every criterion pointer has `blocking_eligible=false`.
+
+## 7. Interdisciplinary applicability
+
+Phase 1 commits each selected pointer without manuscript-derived applicability.
+After the paper-visible boundary, a consumer may state:
+
+- `applicable`, with a manuscript evidence/absence anchor;
+- `not_applicable`, with a manuscript-grounded rationale; or
+- `unresolved`, requiring human resolution.
+
+No consumer averages parallel criteria, assigns an adaptive numeric weight, or
+selects the criterion whose outcome is easiest to satisfy. Human resolution
+belongs in a separate author/reviewer record and starts a new target review if
+it changes the selected context.
+
+## 8. Failures and degradation
+
+Binding failures are visible workflow-conformance failures:
+
+- malformed/oversized/symlinked input;
+- context or registry hash drift;
+- context recomputation mismatch;
+- missing/duplicate/wrong-role receipt;
+- missing or altered marker;
+- selected-pointer mismatch;
+- same-id profile change; or
+- invalid constructive sidecar.
+
+They stop only the criteria-aware handoff. They do not create an editorial
+decision. The user may correct the artifacts, explicitly start a new target
+review, or run the pre-#684 field-general workflow with an explicit
+`criteria_binding_unavailable` disclosure. That degraded path makes no venue-
+alignment claim and is non-comparable to a bound treatment run.
+
+## 9. Measurement boundary
+
+`evals/heldout/review_criteria_constructive_value/measurement_plan.md` owns the
+paired behavioral design. CI validates schemas, fixtures, scorer behavior, and
+prompt wiring only. It never dispatches a model, judge, or network request.
+
+Until a valid `heldout-measurement/1.1` report is published, describe the
+mechanism as implemented but its effect on unsupported-finding rate, severity,
+venue alignment, and usefulness as **unmeasured**.

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

@@ -0,0 +1,166 @@
+# Review-pathway rule trace protocol (#669)
+
+This protocol governs the candidate-only, deterministic rule trace built by
+`scripts/build_review_pathway_rule_trace.py`. The trace displays selected-profile
+predicate work. It never selects, predicts, ranks, approves, clears, exempts, or
+authorizes a pathway.
+
+Normative contracts:
+
+- `shared/contracts/human_subjects/review_pathway_trace_request.schema.json`
+- `shared/contracts/human_subjects/review_pathway_rule_trace.schema.json`
+- `shared/contracts/human_subjects/irb_context_record.schema.json`
+- `shared/contracts/human_subjects/authority_profile_registry.schema.json`
+- `shared/contracts/human_subjects/resolved_authority_context.schema.json`
+- `docs/design/2026-08-11-669-review-pathway-rule-trace-spec.md`
+
+## Fixed result and non-authorization boundary
+
+Every completed or halted trace carries exactly:
+
+```text
+Result: institutional determination required
+```
+
+and the exact #665 footer:
+
+```text
+Human-subjects boundary: This output does not authorize recruitment, consent, access to identifiable data, intervention, or data collection.
+```
+
+The trace is advisory navigation only. It cannot change submission readiness,
+authorization status, institutional acceptance, recruitment, consent, data
+access, intervention, collection, delivery, a verdict, a checkpoint, or any
+other workflow state.
+
+## Producer contract
+
+Only a permitted dispatching layer may assemble a
+`review-pathway-trace-request/1.0`. It supplies the exact bound
+`context_pointer`, `registry_pointer`, and `resolved_digest`; it does not infer a
+profile from locale, language, affiliation, topic, or manuscript prose.
+
+Candidate names come only from an explicitly identified institutional material
+or an author-declared question. They are question labels, not authority. A
+request must partition every selected-profile requirement whose exact
+`consumer_scopes` contains `pathway_trace`. Each eligible requirement appears
+under exactly one candidate for its own exact profile. The dispatching layer may
+not omit an awkward predicate, move a data-protection requirement into a
+review-ethics candidate, use an overlay as a selected profile, or invent a local
+pathway rule.
+
+Candidate and requirement arrays use ascending ids. Ordering is
+`display_only_sequence_no_decision_meaning`; it never indicates likelihood, priority, or a
+recommended route. Alternatives are profile-local. A data-protection route
+remains parallel authority work and cannot be described as an IRB route.
+Requests projecting more than 4,096 complete alternative rows fail; trace JSON
+and rendered Markdown are each capped at 8 MiB.
+
+## Builder contract
+
+Before dereferencing any requirement, the builder calls
+`validate_resolved_context(resolved, context, registry)`. It then requires exact
+request pointer/digest equality and exact selected-profile requirement
+coverage. It opens only the explicitly named context, registry, resolved,
+request, and trace files. It uses no model, API, evaluator, network, clock,
+ambient filesystem scan, caller template, or caller prose fragment.
+
+For every emitted predicate, the builder verifies the exact requirement id,
+digest, `requirement_pointer`, and `authority_anchor_pointer` against the bound
+registry. It projects only:
+
+- tri-state applicability and leaf fact occurrences;
+- the exact author-declared fact state and value;
+- missing or unknown fact ids;
+- exact `authoritative_decision_maker.role_id`;
+- exact anchor source id, provision, https link, and effective date.
+
+It does not copy or interpret a requirement title, summary, structured
+expectation, evidence description, legal conclusion, or institutional rule.
+Every fact occurrence is retained; an unresolved fact cannot be converted into
+a matched or unmatched predicate.
+
+All selected profiles on both authority axes must be exact, profile-applicable,
+and bound to current sources. A missing profile emits no candidate trace and
+preserves `JURISDICTION_UNRESOLVED`. Any profile-level applicability/source or
+overlay-base problem emits no candidate trace and uses
+`authority_context_unresolved`.
+
+There is one narrow, trace-only treatment of unknown requirement predicates. If
+both axes have exact selected profiles, every selected profile itself is true
+and current, and all unresolved reasons are selected-profile requirement-level
+`APPLICABILITY_UNRESOLVED`, the builder may display those rows under
+`unresolved_predicates`. This does not open or change #666's
+`profile_dependent_result_allowed` gate; no consumer may turn such a row into an
+action or result.
+
+## Replay and render contract
+
+`request_digest` binds the complete canonical request. `trace_digest` binds the
+complete canonical trace with only that digest field omitted. Neither digest is
+sufficient by itself.
+
+Before accepting or rendering a serialized artifact, call:
+
+```python
+validate_review_pathway_rule_trace(
+    trace,
+    request,
+    context,
+    registry,
+    resolved,
+)
+```
+
+The validator replays #666, rebuilds the request coverage and complete expected
+trace, recomputes digests, and requires exact canonical equality.
+
+The fixed renderer emits only the labelled grammar
+`Candidate pathway examined`, `Matched predicates`, `Unmatched predicates`,
+`Unresolved predicates`, `Alternative pathway triggers`, `Result`, and
+`Authority`, plus the fixed header, state, ordering statement, source label, and
+boundary footer. Empty lists are the literal `- none`. It accepts no template.
+
+## Surface-scoped output lint
+
+After replay, call `scripts/check_review_pathway_output.py` with the one explicit
+trace JSON path and, when present, the one explicit rendered Markdown path. The
+checker scans only every string leaf in that named generated JSON and every line
+in that named rendering. It never scans a directory, repository, source
+document, protocol, fixture corpus, log, or sibling file.
+
+Lint normalization is Unicode NFKC, `casefold()`, Unicode format/surrogate
+removal, control-to-whitespace mapping, Unicode-whitespace collapse, and
+punctuation-spacing normalization. `No IRB needed`, approval/clearance,
+`Low risk`, probability/confidence/likelihood language, percentages, rankings,
+timelines, and comparison to “most studies like yours” fail. A pathway term is
+allowed only in the exact JSON `candidate_pathway_name` field and an exact
+renderer line beginning `Candidate pathway examined: ` whose profile/name pair
+equals the paired JSON. Approval, clearance, low-risk, and probability language
+remain banned even inside a candidate name.
+
+## Consumer contract
+
+An agent may display the trace only after the permitted dispatching layer
+confirms both successful replay and successful surface lint against the exact
+named artifacts. Preserve the candidate labels, buckets, fact states, holders,
+pointers, anchors, ordering statement, result, and footer exactly. Do not
+summarize a candidate as the likely, probable, usual, low-risk, simplest,
+preferred, approved, exempt, cleared, or expected route.
+
+The trace never supplies an action assignment. For action planning, the normal
+#666 gate and exact actor/consumer-scope rules still apply independently. A
+candidate label or matched predicate does not establish applicability of local
+policy, institutional acceptance, submission readiness, authorization, or
+permission to begin any activity.
+
+`deep-research/references/irb_decision_tree.md` is a derived navigation aid. Its
+bounded branches backpoint to registry requirement ids and exact primary-source
+anchors. It is not authority, is not a complete local taxonomy, and cannot
+supply an unanchored predicate to this trace.
+
+## Non-goals
+
+No determination, probability, confidence, likelihood ranking, timeline,
+comparison cohort, simulated committee, legal advice, institutional acceptance,
+submission readiness, authorization, action assignment, or workflow decision.