psyclaw 0.27.22 → 0.28.0

package/vendor/ars/shared/bibliographic_integrity_signals.md

@@ -0,0 +1,142 @@
+# Bibliographic Integrity Signal Contract
+
+`shared/contracts/passport/bibliographic_integrity_signal.schema.json` is the
+single schema authority for bibliographic-integrity observations carried in
+`literature_corpus[].bibliographic_integrity_signals[]`. Version 1.0 is the
+additive migration carrier. Version 1.1 is the #651 retraction-status policy
+cutover. Both preserve the one-advisory-token reference-marker grammar.
+Version 1.2 is the #660 tortured-phrase advisory profile; it is additive and
+does not change the validity of shipped canonical v1.0/v1.1 fixtures or producer
+outputs, nor their policy meaning. Its signal-type invariant intentionally rejects
+noncanonical, previously underconstrained tortured-phrase mutations that claimed
+deterministic or terminal authority.
+
+## Epistemic boundary
+
+The carrier separates three claims that must not be collapsed:
+
+| `epistemic_class` | Required label | What it establishes |
+|---|---|---|
+| `deterministic_fact` | `RESOLVER-OR-LIST-OBSERVATION` | What a named resolver or list returned at a recorded time; not whether the cited work is ultimately genuine, retracted, or sound. |
+| `heuristic_advisory` | `HEURISTIC-INDICATOR` | A rule or model matched; never a factual finding by itself. |
+| `process_attestation` | `CHECK-EXECUTION-ATTESTATION` | A check was reportedly run; it is not the result of that check. |
+
+`check_status` and `finding` are independent. `not_checked`, `unknown`, and
+`degraded` require `finding: unresolved`; none may be rendered or interpreted
+as clean. A legacy `retraction_check: true` therefore migrates only to a
+checked execution attestation with an unresolved finding. It never becomes
+`not_detected`.
+
+## Display and policy ownership
+
+Every v1 signal is rendered as one row in the single
+`Bibliographic Integrity Advisories` section of `provenance_summary.md`.
+Rows compose by `signal_id` in lexical order and show the signal type,
+epistemic label, check status, finding, affected citation/claims, provenance,
+and freshness. The formatter must render `not_checked`, `unknown`, and
+`degraded`, or any signal whose `finding` is `unresolved`, as **NOT CLEAN —
+UNRESOLVED**. The rendered table carries the resolver/list name, version and
+hash, checked/recorded/stale timestamps, freshness, source pointer, and affected
+claims so an advisory never loses its provenance in projection.
+
+`display.marker_token` is always `null`. New retraction and tortured-phrase
+signals do not mint another `<!--ref:...-->` advisory token. During migration,
+the existing finalizer continues to derive its one recognized
+`CONTAMINATED-*` token from the legacy `contamination_signals` fields. Thus
+multiple new signals compose in the provenance summary without changing or
+overflowing the marker grammar.
+
+`terminal_policy` records eligibility and the policy owner; it does not enact
+policy. Only the citation finalizer may evaluate an eligible signal. Version
+1.0 migrations set `eligible: false`, `policy_key: null`, and
+`current_effect: advisory_only`. A v1.1 retraction row is eligible only when
+its effective status is current, undisputed `retracted` and the deterministic
+declared-legitimate exception did not fire. The finalizer then evaluates the
+explicit `terminal_policies.retraction` choice. Adding a signal never silently
+promotes it to `HIGH-BLOCK`.
+
+## Tortured-phrase advisory profile (v1.2 / #660)
+
+Version 1.2 carries one current `tortured_phrase_match` row per
+`(citation_key, cited_title|cited_abstract)` surface. It is always
+`heuristic_advisory` / `HEURISTIC-INDICATOR`; its closed context remains
+`layer: HEURISTIC-ADVISORY` and `evaluation_status: UNMEASURED`. A detected
+row means only **phrase-list match requiring review**. A checked zero-match row
+means only that no phrase-list match was observed on that exact checked
+surface; absence is not a clean certification. It never establishes AI,
+author, paper-mill, misconduct, or other origin, and it carries no precision,
+recall, false-positive, false-negative, coverage, or publisher-acceptance
+claim.
+
+The local producer consumes only an explicitly named canonical snapshot and
+detached manifest. The manifest binds the exact raw UTF-8 snapshot bytes by
+SHA-256 and declares either `user_supplied` or `synthetic_fixture` supply;
+ARS ships no native PPS parser/importer, fetch path, or redistributed PPS list
+content. Matching reads no model, external API, human/model judge, system
+clock, file time, or network time. Required timestamps are explicit inputs.
+
+Each invoked corpus check keeps title and abstract coverage separate. A valid
+title is checked independently. A missing abstract remains an explicit
+`not_checked` / `unresolved` row with reason `ABSTRACT_MISSING`, while a present
+whitespace-only abstract uses `ABSTRACT_EMPTY`; neither state can be
+folded into the title result or omitted. Manual corpus entries have no
+exemption. Every row binds the exact local surface bytes plus snapshot and
+manifest hashes. The producer returns a new passport copy and never rewrites a
+source title, abstract, citation, or input passport in place.
+
+All v1.2 rows compose in the existing single `Bibliographic Integrity
+Advisories` section. `display.marker_token` is `null`,
+`terminal_policy.eligible` is `false`, and neither the finalizer nor formatter
+may mint a marker, gate, terminal promotion, suggested replacement, or
+automatic rewrite from the row. The separate own-draft carrier is
+`tortured-phrase-advisory/1.0`; it has the same
+`HEURISTIC-ADVISORY` / `UNMEASURED` boundary and is not a corpus authority.
+
+## Retraction authority cutover (v1.1 / #651)
+
+The v1.1 `retraction_status` row is authoritative for retraction status. It
+records OpenAlex and Crossref observations separately, including disagreement,
+reinstatement, event dates, source-acquisition timing, load-bearing claim join,
+and a strictly mechanical author-declaration + notice-cited exception. Missing
+dates, reasons, or resolver results stay explicit and are never inferred.
+
+The legacy `retraction_check` boolean remains readable for one compatibility
+window as a process attestation only. New retraction-status producers do not
+write it, and neither the finalizer nor the ethics agent may use it as a status
+or terminality input. The ethics agent points to the canonical row; the
+finalizer owns advisory/strict evaluation.
+
+Retraction status uses the separate `retraction_status_cache_v1` namespace.
+Cached observations retain `checked_at` and typed unknown/degraded states. A
+row older than 30 days is stale and must be revalidated before strict
+promotion; stale never means clean.
+
+## Pinned migration and deprecation path
+
+1. **Read compatibility:** consumers continue to read
+   `contamination_signals`, `contamination_signal_omissions`,
+   `contamination_signals_backfilled_at`, and source-object
+   `retraction_check` exactly as before.
+2. **Dual write:** updated producers append canonical v1 records while still
+   writing the legacy fields required by current marker and terminal-policy
+   behavior. `scripts/bibliographic_integrity_signals.py` defines the
+   deterministic legacy-to-v1 projection.
+3. **Display cutover:** the formatter renders the canonical array into the
+   one provenance-summary section. It does not derive new marker tokens.
+4. **Policy cutover:** #651 cuts over only `retraction_status` through v1.1 and
+   `terminal_policies.retraction`. Other v1.0 signal types remain advisory and
+   keep their existing legacy-policy carriers.
+5. **Removal (future major version):** legacy fields may be removed only after
+   one released compatibility window following policy cutover. Until then
+   they are deprecated write targets, not invalid inputs.
+
+`contamination_signal_omissions.<resolver>: api_degraded` migrates to a
+resolver-specific record with `check_status: degraded` and
+`finding: unresolved`. Absence of both a legacy result and omission remains
+absence/unknown; it is never synthesized as a clean result. Existing
+`provenance_summary.md` text is an output projection and is never parsed back
+as evidence.
+
+The v1.2 profile is not a migration of the older tortured-phrase scaffold.
+Existing v1.0 heuristic rows remain readable with their original meaning, but
+cannot be treated as completed title/abstract checks.

package/vendor/ars/shared/collaboration_depth_rubric.md

@@ -0,0 +1,154 @@
+---
+rubric_version: "1.0"
+paper_citation: "Wang, S., & Zhang, H. (2026). Pedagogical partnerships with generative AI in higher education: how dual cognitive pathways paradoxically enable transformative learning. International Journal of Educational Technology in Higher Education, 23:11. DOI: 10.1186/s41239-026-00585-x"
+license: CC-BY-NC 4.0
+---
+
+# Collaboration Depth Rubric
+
+**Status**: v1.0 (introduced ARS v3.5, 2026-04-21)
+**Source**: Wang, S., & Zhang, H. (2026). *IJETHE* 23:11. DOI [10.1186/s41239-026-00585-x](https://doi.org/10.1186/s41239-026-00585-x). Open Access, CC BY 4.0.
+**Canonical location**: `shared/collaboration_depth_rubric.md` in `Imbad0202/academic-research-skills`. External consumers should reference by stable URL; do not vendor (bump the `rubric_version` field on any modification).
+
+---
+
+## Why this rubric exists
+
+Wang & Zhang (2026) empirically show that student-GenAI collaboration on pedagogical partnership terms simultaneously activates two cognitive pathways — **vigilance** (critical evaluation of AI output) and **offloading** (strategic delegation of cognitive work) — and that **both** independently predict transformative learning. Counterintuitively, cognitive offloading is **positively** associated with deep learning (β = 0.333, p < 0.001), with U-shaped dynamics: shallow scattered use (Zone 2) produces worse outcomes than no AI use (Zone 1); substantial committed delegation (Zone 3) unlocks higher-order reflection (β-quadratic = 0.102, p < 0.001).
+
+This rubric operationalizes their framework as a post-hoc observer signal for Claude Code agents. It is used by `academic-pipeline/agents/collaboration_depth_agent.md` to score dialogue logs and produce **advisory, non-blocking** feedback to the user on how their collaboration pattern is shaping learning depth.
+
+The rubric is **descriptive, not prescriptive**. It does not gate user progression. It does not celebrate high scores. It does not suggest low scores are failures. Its purpose is to make collaboration mode visible, so the user can decide whether to change it.
+
+---
+
+## The four dimensions
+
+### Delegation Intensity
+
+**Paper construct**: Cognitive Offloading (CO). 6-item Likert scale; sample items: *"I delegate complex problem-solving tasks to generative AI"*, *"I transfer cognitive effort to generative AI to reduce mental workload"* (Wang & Zhang 2026, Table 1).
+
+**What to score for**: whole-category handoffs versus scattered micro-asks. Count committed delegation of task *categories* (e.g., "AI, draft the entire literature review" or "AI, do the outline"), not individual prompts. Zone 2's "fixing sentences, checking facts, tidying paragraphs" pattern is **low** intensity even if prompt count is high.
+
+**High-intensity signals**:
+- User assigns a whole subtask to the agent and moves on (e.g., "draft literature review", "build argument skeleton", "generate first outline")
+- User articulates a division-of-labor plan at intake
+- User says "you handle X while I focus on Y"
+
+**Low-intensity signals**:
+- Many small single-prompt interactions, each touching a fragment
+- No task-level commitment language; user holds full cognitive load and just nudges output
+- User edits AI micro-outputs line-by-line rather than regenerating at task level
+
+**Empirical anchor**: U-shape (β-quadratic = 0.102, p < 0.001). Low-to-moderate offloading has minimal learning impact; only above threshold does offloading accelerate transformative learning.
+
+---
+
+### Cognitive Vigilance
+
+**Paper construct**: Cognitive Vigilance (CV). 6-item Likert scale; sample items: *"I critically evaluate the accuracy of AI-generated content"*, *"I verify AI-generated information through independent sources"*, *"I scrutinize AI outputs for potential errors"* (Wang & Zhang 2026, Table 1).
+
+**What to score for**: whether the user actively challenges, verifies, and pushes back on AI output — or accepts it uncritically.
+
+**High-vigilance signals**:
+- User asks AI to justify a claim, cite a source, or defend a framing
+- User catches an AI error and says so explicitly
+- User refuses to accept a draft and asks for a different approach
+- User requests source verification or cross-checks with another tool
+- User counter-argues before accepting
+
+**Low-vigilance signals**:
+- User accepts all drafts without critique
+- User never asks "where does this claim come from?"
+- User forwards AI output unchanged
+- No explicit challenges to AI reasoning in the dialogue
+
+**Empirical anchor**: H2a β = 0.437, p < 0.001, f² = 0.243 — **the single highest-impact path** in Wang & Zhang's model. Also the dimension with highest IPMA importance (0.438) *and* lowest IPMA performance (56.7/100), identifying it as the top priority for pedagogical intervention. If a user scores low here, that is the signal the paper most strongly implicates as correctable.
+
+---
+
+### Cognitive Reallocation
+
+**Paper construct**: Human-GenAI Pedagogical Partnership (HGP) → Transformative Learning Experience (TLE), mediated by cognitive offloading (H3b indirect path β = 0.117, p < 0.001). Paper's characterisation: "strategic offloading liberates mental resources for higher-order reflection"; Risko & Gilbert (2016) cognitive offloading framework extended to show delegation is only learning-productive when freed capacity is *reinvested* in higher-order work.
+
+**What to score for**: when the user hands work to the agent, what does the user do with the freed capacity? Is it invested in reframing research questions, questioning assumptions, constructing original arguments, making judgment calls — or is it idle?
+
+**High-reallocation signals**:
+- After AI completes a subtask, user revisits higher-level framing (e.g., "looking at your draft, I now think the RQ should be X not Y")
+- User produces original synthesis not present in AI output
+- User introduces counter-arguments, frameworks, or perspectives the AI did not raise
+- User makes judgment calls that require context only the human has (stakeholder intent, institutional history, personal aesthetic)
+
+**Low-reallocation signals**:
+- User accepts AI work and moves to next prompt without higher-order engagement
+- No original synthesis; user's contribution is routing and aggregation only
+- Time saved by offloading does not translate to any visible higher-order contribution
+
+**Empirical anchor**: Paper's post-hoc quadratic: the offloading→TLE path only materialises above a threshold (β-quadratic = 0.102, p < 0.001). Delegation without reallocation is Zone 2; delegation *with* reallocation is Zone 3.
+
+---
+
+### Zone Classification
+
+**Paper construct**: three-zone framework (Wang & Zhang 2026's primary conceptual contribution, synthesised from the dual-pathway SEM + fsQCA configurations + post-hoc U-shape analysis). Popularised in Hardman (2026-04-16) and Means (2026-04-20).
+
+**Synthesis rule** (derived from the three dimensions above):
+
+| Zone | Delegation Intensity | Cognitive Vigilance | Cognitive Reallocation | Description |
+|---|---|---|---|---|
+| **Zone 1 — No AI use** | Near 0 | N/A | N/A | User carries full cognitive load manually. Learning occurs but capacity-constrained. |
+| **Zone 2 — Shallow / Scattered** | Low–Mid | Low | Low–Mid | "Half-measures worse than no AI at all." Coordination overhead without meaningful cognitive savings. Empirically the worst outcome zone. |
+| **Zone 3 — Deep Partnership** | High | High | High | Committed strategic delegation **with** critical evaluation **and** reinvested higher-order reflection. The zone in which transformative learning empirically occurs. |
+
+**Scoring rule**: Zone 3 requires **all three** sub-dimensions to be high. Zone 2 is the default when at least one of Delegation Intensity or Cognitive Vigilance is low while AI is being used. Zone 1 is the default when AI is essentially unused in the dialogue window.
+
+**Honest calibration** (anti-sycophancy): Zone 3 is empirically **rare**. Wang & Zhang's IPMA performance scores for CV (56.7) and HGP (54.2) — the two Zone 3 prerequisites — sit in the 55–60 range out of 100. A consumer agent should not default to Zone 3; if an aggregate score trends toward Zone 3, re-audit the dialogue for counter-evidence before finalizing.
+
+---
+
+## Scoring
+
+Each of the first three dimensions is scored **0–10** (integer). Zone Classification is a label derived from the three dimension scores.
+
+**Threshold guidance** (consumer agents may adapt these bands):
+
+| Score band | Label |
+|---|---|
+| 0–3 | Low |
+| 4–6 | Mid |
+| 7–10 | High |
+
+**Zone synthesis**:
+- All three dimension scores ≥ 7 → Zone 3
+- Delegation Intensity or Cognitive Vigilance < 4, AI actively used in dialogue → Zone 2
+- Delegation Intensity < 2 AND Cognitive Reallocation N/A (AI essentially unused) → Zone 1
+- All other combinations → Zone 2 with narrative qualifier
+
+---
+
+## Anti-sycophancy discipline for consumer agents
+
+Any agent consuming this rubric **must** enforce:
+
+1. **Evidence requirement**: no dimension score ≥ 7 ("High") without at least one specific dialogue-turn citation from the scored session.
+2. **Forced counter-enumeration**: before finalizing scores, the agent lists ≥ 2 moments where the user could have gone deeper (even in high-scoring sessions).
+3. **Re-audit trigger**: if the aggregate Zone label comes out Zone 3, re-audit the dialogue for counter-evidence. Zone 3 is empirically rare; a fast Zone 3 call is usually wrong.
+4. **Descriptive language only**: no "great job!", no "needs improvement!". Report observed pattern + specific citable evidence.
+5. **Cross-model divergence flag**: if the consumer agent runs cross-model (e.g., via `ARS_CROSS_MODEL`), any dimension score disagreement > 2 points between models must be flagged in the output.
+
+## Explicitly out of scope
+
+This rubric does **not**:
+
+- Gate user progression. Consumer agents must declare `blocking: false` in their frontmatter.
+- Replace AI self-reflection protocols (e.g., `academic-pipeline` Stage 6's six-dimension Collaboration Quality Evaluation, which is AI-about-itself; this rubric is AI-about-user-collaboration).
+- Detect user "orientation" (efficiency vs depth). Wang & Zhang (2026)'s H4 on efficiency orientation as amplifier is not operationalised here.
+- Prescribe which tasks to delegate. That is a pedagogical decision the user owns; this rubric only describes what delegation pattern occurred.
+
+---
+
+## Versioning
+
+`rubric_version` follows semver. Changes to dimension count, synthesis rule, or operationalisation language require a **minor** bump and a note in `CHANGELOG.md`. Example-refinement or phrasing changes are **patch** bumps.
+
+If a future paper supersedes or materially revises Wang & Zhang (2026)'s constructs, a **major** bump is required and the `paper_citation` field must be updated accordingly.

package/vendor/ars/shared/compliance_checkpoint_protocol.md

@@ -0,0 +1,162 @@
+---
+title: Compliance Checkpoint Protocol (Stage 2.5 / 4.5 dual gate)
+applies_to: "shared/agents/compliance_agent.md"
+---
+
+# Compliance Checkpoint Protocol
+
+Defines how `compliance_agent` participates in Stage 2.5 and Stage 4.5 Integrity Gates, how its decision interacts with the existing FAIL loop, and how user overrides are processed.
+
+**Used by**: `compliance_agent` (Task 8), `academic-pipeline/SKILL.md` Stage 2.5 / 4.5.
+
+## Dual-gate summary
+
+| Aspect | Stage 2.5 | Stage 4.5 |
+|---|---|---|
+| PRISMA-trAIce scope (SR mode only) | M1, M2, M3, M4, M5, M6, M7, M8, M9, M10 | T1, A1, I1, R1, R2, D1, D2 |
+| RAISE principles focus | human_oversight, fit_for_purpose | transparency, reproducibility |
+| RAISE 8-role matrix | not populated | populated (SR mode only) |
+| Block condition | SR mode AND any Mandatory item = FAIL, OR SR mode AND any RAISE principle = fail | Same |
+| Warn condition | Highly Recommended FAIL, OR RAISE principle = warn | Same |
+| Info condition | Recommended / Optional FAIL | Same |
+| Non-SR mode | RAISE principles_only, warn-only (never block) | Same |
+| Checkpoint output | FULL checkpoint + `compliance` section in dashboard | Same |
+
+## Decision precedence
+
+Inside a single checkpoint, decisions aggregate as:
+
+```
+overall_decision = max_severity(
+  prisma_trAIce.block_decision,
+  raise.block_decision,
+  legacy_integrity_verification_decision,  # existing Stage 2.5/4.5 check
+  legacy_failure_mode_checklist_decision   # v3.2 Failure Mode Checklist
+)
+
+severity order: pass < warn < block
+```
+
+Non-SR mode caps the compliance contribution at `warn`.
+
+## User action UX
+
+### On block
+
+Orchestrator presents:
+
+```
+[COMPLIANCE BLOCK] Stage <N>
+
+PRISMA-trAIce Mandatory fails: M4 (Input Data)
+RAISE principles fail: reproducibility
+
+Choose:
+  (a) backfill — return to Stage 2 and add missing material
+  (b) manual handling — edit manuscript directly, rerun compliance
+  (c) acknowledge limitation — invoke user override (see §Override Ladder)
+```
+
+### On warn
+
+Dashboard bullets, FULL checkpoint. User confirms with free text or `continue`.
+
+### On info (Recommended / Optional fail)
+
+Bullet in dashboard, no flow interruption.
+
+## Canonical gap-tag vocabulary
+
+Compliance reports and fixture templates use these canonical tags in `gaps[].reason`, `principle_evidence[]`, and narrative fields. They are lexical signals — `compliance_agent` (Task 8) and downstream readers pattern-match on them.
+
+| Tag | Where it appears | Meaning |
+|---|---|---|
+| `[MATERIAL GAP]` | `gaps[].reason`, `principle_evidence[]`, `evidence[]` | The item cannot be verified because the underlying material (passport field, manuscript section, supplementary file) is missing. Apply [Anti-Leakage Protocol](../academic-paper/references/anti_leakage_protocol.md) — do not hallucinate. |
+| `[WEAK EVIDENCE]` | `principle_evidence[]` | The item is nominally reported but the description is too vague for auditor use. Triggers CA-4 downgrade: a RAISE principle marked `pass` with `[WEAK EVIDENCE]` in its evidence should be downgraded to `warn`. |
+| `[GAP]` | `roles[].evidence_synthesists` narrative and similar role-level fields | Short form for a role-level gap carried forward from item-level fails. Permitted only in the 8-role matrix narrative; item-level reasons MUST use the long `[MATERIAL GAP]` form. |
+
+Casing is significant — uppercase square-bracketed. Lowercase or missing brackets are treated as plain prose and will not be recognised as gap signals.
+
+<!-- harness-retirement 2026-06-10 (F-008): the "do not hallucinate" tail on the [MATERIAL GAP] row is kept as known debt — high-stakes academic compliance surface with a silent failure mode; delete only with calibration evidence that the tail is inert. -->
+
+## Override Ladder (3-round friction)
+
+Triggered when user picks "acknowledge limitation" on a block.
+
+| Round | Behaviour |
+|---|---|
+| 1st block override | Warn user. Rationale optional. Allowed. |
+| 2nd (if user re-enters block state) | Require rationale string (any length). |
+| 3rd | Require rationale ≥ 100 chars. Only released on rationale confirmation. |
+
+Round count is per-stage-per-pipeline-run, stored in `compliance_history[].user_override` entries.
+
+> **Enforcement boundary.** This ladder is enforced at **runtime by `compliance_agent`** using the `compliance_history[]` round counter, NOT by Schema 12. Schema 12 intentionally permits `user_override.rationale.minLength: 1` so that legacy passports and cross-session resume do not fail validation on historical entries. The round-counter increment and ≥100-char rationale check live in the agent's write-path, not in the JSON Schema. If you bypass the agent and hand-write a `user_override` entry into the passport, Schema 12 will accept any rationale length — but that entry will not have gone through the friction ladder and must be treated as unaudited.
+
+On any successful override, the agent generates `disclosure_addendum` text and the orchestrator **auto-injects** it into the manuscript's AI disclosure section. The addendum is non-removable — this is the concrete form of the `no detection evasion` iron rule in CONTRIBUTING.md.
+
+### Advisory adjudication-activity receipt (#673)
+
+The compliance decision, friction-ladder enforcement, manuscript disclosure,
+and ordinary routing/state effect are completed and made durable first. Only
+afterward may the action-time producer best-effort append a closed activity
+binding through the state tracker's sole-writer path; receipt failure cannot
+change the override or checkpoint outcome.
+
+Every executed compliance report is eligible to be bound as the
+`compliance_report` role. A plain PASS or WARN report with no `user_override`
+is a valid report-only **captured-zero** group. The paired
+`compliance_override_action_receipt` is required only when the report satisfies
+the complete qualifying-override predicate in the frozen #673 spec: a
+systematic-review compliance contribution actually blocks, user action is
+required, the user override is true, and the recomputed blocker scope, stage,
+run, report hash, actor/source/action, ordinal/friction, occurrence id, and
+interaction digest all match. The action receipt contains no rationale. It is
+forbidden for a plain report and may not turn a legacy-only block, PASS/WARN,
+`user_action_required=false`, or malformed/non-qualifying override claim into
+activity.
+
+These receipt bindings remain internal activity metadata under
+`state_tracker_agent.md` § "Adjudication-activity metadata". They never enter
+`compliance_history`, the Material Passport, manuscript disclosure, checkpoint
+decision, gate/verdict input, Process Record, handoff, or model prompt, and are
+never reconstructed from prose. No model/judge/eval, network/API, clock, or
+ambient scan participates in their production.
+
+### `disclosure_addendum` template
+
+```
+The authors acknowledge the following compliance limitations for this <evidence synthesis|manuscript>:
+- PRISMA-trAIce <item_id> (<item_title>) not fully reported. Rationale: <user text>.
+- RAISE principle <principle_name>: <partial|not met>. Rationale: <user text>.
+```
+
+**Template fill rules** (compliance_agent uses these deterministically):
+
+- `<evidence synthesis|manuscript>`: pick `evidence synthesis` when `mode in {systematic_review, other_evidence_synthesis}`; pick `manuscript` when `mode == primary_research`.
+- `<partial|not met>`: pick `partial` when the principle's original status was `warn`; pick `not met` when it was `fail`.
+- `<item_id>`: the PRISMA-trAIce item ID as listed in `user_override.scope[]`.
+- `<item_title>`: look up the short title from `shared/prisma_trAIce_protocol.md` (e.g. `M4` → "Input data").
+- `<principle_name>`: one of `human_oversight`, `transparency`, `reproducibility`, `fit_for_purpose`.
+- `<user text>`: verbatim copy of `user_override.rationale`, truncated to first 500 chars if longer (the addendum keeps prose; the full rationale lives in the compliance_history).
+
+## Fail loop integration
+
+After 3 unresolved rounds of retry at the same stage, orchestrator invokes the existing `pipeline_state_machine.md §Integrity Check FAIL Loop` procedure:
+
+1. List all unresolvable items.
+2. User picks [manual handling / remove AI usage from this stage / continue with "partially non-compliant" warning].
+3. Chosen path is recorded as `compliance_history[].resolution_path`.
+
+## Append-only history
+
+`material_passport.compliance_history[]` never overwrites. On retry-pass, the previous fail entry is preserved with its own timestamp. The AI Self-Reflection Report at Stage 6 cites the full history to demonstrate how the correction was made — this is RAISE transparency applied to ARS itself.
+
+## Boundary: non-pipeline invocation
+
+When invoked from `academic-paper full` (primary research standalone), no pipeline state machine is available. Compliance_agent:
+
+- Writes report to `./compliance_reports/<ISO-timestamp>.yaml` (local file)
+- Does not trigger pipeline checkpoint dashboard
+- If skill has a `disclosure` mode, hooks compliance output there
+- `block_decision` capped at `warn`

package/vendor/ars/shared/compliance_report.schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Imbad0202/academic-research-skills/shared/compliance_report.schema.json",
+  "title": "ARS Compliance Report (Schema 12)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "mode",
+    "stage",
+    "generated_at",
+    "raise",
+    "overall_decision",
+    "user_action_required"
+  ],
+  "properties": {
+    "mode": {
+      "enum": ["systematic_review", "primary_research", "other_evidence_synthesis"]
+    },
+    "stage": { "enum": ["2.5", "4.5"] },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "prisma_trAIce": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["items_total", "by_tier", "block_decision"],
+          "properties": {
+            "items_total": { "const": 17 },
+            "by_tier": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["mandatory", "highly_recommended", "recommended", "optional"],
+              "properties": {
+                "mandatory": { "$ref": "#/$defs/tier_bucket" },
+                "highly_recommended": { "$ref": "#/$defs/tier_bucket" },
+                "recommended": { "$ref": "#/$defs/tier_bucket" },
+                "optional": { "$ref": "#/$defs/tier_bucket" }
+              }
+            },
+            "block_decision": { "$ref": "#/$defs/decision" },
+            "protocol_maturity": { "$ref": "#/$defs/protocol_maturity" }
+          }
+        }
+      ]
+    },
+    "raise": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "principles", "principle_evidence", "block_decision"],
+      "properties": {
+        "mode": { "enum": ["full", "principles_only"] },
+        "principles": {
+          "type": "object",
+          "required": ["human_oversight", "transparency", "reproducibility", "fit_for_purpose"],
+          "additionalProperties": false,
+          "properties": {
+            "human_oversight": { "$ref": "#/$defs/principle_status" },
+            "transparency": { "$ref": "#/$defs/principle_status" },
+            "reproducibility": { "$ref": "#/$defs/principle_status" },
+            "fit_for_purpose": { "$ref": "#/$defs/principle_status" }
+          }
+        },
+        "principle_evidence": {
+          "type": "object",
+          "required": ["human_oversight", "transparency", "reproducibility", "fit_for_purpose"],
+          "additionalProperties": false,
+          "properties": {
+            "human_oversight": { "type": "array", "items": { "type": "string" } },
+            "transparency": { "type": "array", "items": { "type": "string" } },
+            "reproducibility": { "type": "array", "items": { "type": "string" } },
+            "fit_for_purpose": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "roles": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Present only when raise.mode == 'full'; see top-level allOf constraint.",
+          "properties": {
+            "evidence_synthesists": { "type": "array", "items": { "type": "string" } },
+            "ai_development_teams": { "type": "array", "items": { "type": "string" } },
+            "methodologists": { "type": "array", "items": { "type": "string" } },
+            "publishers": { "type": "array", "items": { "type": "string" } },
+            "users": { "type": "array", "items": { "type": "string" } },
+            "trainers": { "type": "array", "items": { "type": "string" } },
+            "organisations": { "type": "array", "items": { "type": "string" } },
+            "funders": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "block_decision": { "$ref": "#/$defs/decision" }
+      }
+    },
+    "overall_decision": { "$ref": "#/$defs/decision" },
+    "user_action_required": { "type": "boolean" },
+    "evidence": { "type": "array", "items": { "type": "string" } },
+    "user_override": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["decision", "timestamp", "rationale", "scope"],
+      "properties": {
+        "decision": { "const": true },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "rationale": { "type": "string", "minLength": 1 },
+        "scope": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^(T1|A1|I1|M([1-9]|10)|R[12]|D[12]|human_oversight|transparency|reproducibility|fit_for_purpose)$"
+          }
+        }
+      }
+    },
+    "upstream_sync_status": { "enum": ["current", "stale"] }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "mode": { "const": "systematic_review" } }, "required": ["mode"] },
+      "then": { "properties": { "prisma_trAIce": { "type": "object" } } }
+    },
+    {
+      "if": { "properties": { "mode": { "const": "primary_research" } }, "required": ["mode"] },
+      "then": { "properties": { "prisma_trAIce": { "type": "null" } } }
+    },
+    {
+      "if": {
+        "properties": { "raise": { "properties": { "mode": { "const": "full" } }, "required": ["mode"] } },
+        "required": ["raise"]
+      },
+      "then": { "properties": { "raise": { "required": ["roles"] } } }
+    }
+  ],
+  "$defs": {
+    "decision": { "enum": ["block", "warn", "pass"] },
+    "principle_status": { "enum": ["pass", "warn", "fail"] },
+    "protocol_maturity": {
+      "description": "Optional maturity-disclosure context for the PRISMA-trAIce protocol authority backing this report. Populated by compliance_agent from shared/prisma_trAIce_protocol.md: frontmatter `citation` and `snapshot_date` are the deterministic source for upstream_citation and snapshot_date; `status` is derived from the protocol authors' self-description (currently foundational_proposal per Holst et al. 2025); `caveat_summary` is composed from the protocol's framing (issue #93 / PR #94 add a `§ Status disclaimer` section as the canonical prose source — until that PR lands, agents derive the summary from the Holst 2025 framing). See handoff_schemas.md § Schema 12 and issue #95 for the contract narrative.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "upstream_citation", "snapshot_date", "caveat_summary"],
+      "properties": {
+        "status": {
+          "description": "Authors' self-described maturity stage. 'foundational_proposal' = pre-Delphi, immediately-adoptable-but-unvalidated (current Holst et al. 2025 status). 'delphi_consensus' = post-formal-consensus. 'empirically_validated' = items validated across diverse research contexts.",
+          "enum": ["foundational_proposal", "delphi_consensus", "empirically_validated"]
+        },
+        "upstream_citation": {
+          "description": "Citation string matching shared/prisma_trAIce_protocol.md frontmatter `citation` field.",
+          "type": "string",
+          "minLength": 1
+        },
+        "snapshot_date": {
+          "description": "ISO 8601 date of the protocol snapshot consulted; matches shared/prisma_trAIce_protocol.md frontmatter `snapshot_date`.",
+          "type": "string",
+          "format": "date"
+        },
+        "caveat_summary": {
+          "description": "One-paragraph summary of the maturity caveat, suitable for inclusion in the block message and the AI Self-Reflection Report compliance summary.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "tier_bucket": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "pass", "fail"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "pass": { "type": "integer", "minimum": 0 },
+        "fail": { "type": "array", "items": { "type": "string" } },
+        "gaps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["item_id", "reason"],
+            "properties": {
+              "item_id": { "type": "string" },
+              "reason": { "type": "string" },
+              "evidence_path": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}