@litfamily/litopencode 1.0.0

package/skills/autoconference/references/conference-protocol.md

@@ -0,0 +1,102 @@
+# OpenCode Conference Protocol
+
+## OpenCode authority envelope
+
+This reference is inert protocol guidance. `lit-plan` must approve the finite root-owned objective,
+budget, roots, task packets, and review contract before any mutation or delegation, including
+interactive runs. Only explicit `/start-work` may consume that approval. Children remain depth-one
+and packet-only; children must not write or mutate root-owned state, select models, or invoke routes.
+The OpenCode bounded-authority lifecycle owns every action. Conflicts use read-only comparison before
+any proposal. The root must not create, reset, delete, merge, or commit version-control state. Any
+approved local cleanup ends with a cleanup receipt.
+
+## Preconditions
+
+The root requires a complete proposal containing objective, success criterion, fixed evaluator or
+rubric, baseline provenance, disjoint search partitions, exact regular-file roots, packet schemas,
+researcher count, round and iteration ceilings, per-call timeout, wall-clock budget, cancellation,
+resume, stale-state, review, and cleanup policy. Missing or vague values return a planning blocker.
+
+The root verifies live OpenCode `task` capability immediately before delegation. A configured role,
+previous success, prompt claim, or child request is not proof. If capability is absent, denied,
+unknown, or called from a child context, return `BLOCKED_MULTI_AGENT_UNAVAILABLE`.
+
+## Round state machine
+
+Each round has four ordered phases. Parallelism exists only among approved researcher task calls in
+Phase 1. Later phases consume accepted packets and remain sequential root decisions.
+
+### Phase 1 — independent research packets
+
+The root issues one depth-one task packet per approved partition. Each packet fixes objective, roots,
+evaluator, timeout, iteration ceiling, output schema, and baseline digest. Children cannot delegate,
+coordinate peers, alter shared state, or consume another grant. They return evidence, claims,
+uncertainties, failures, and exact proposals.
+
+The root waits only to the approved deadline. It preserves valid partial packets, rejects malformed or
+late packets, and never fabricates output for a missing lane.
+
+### Phase 2 — poster comparison packet
+
+One depth-one packet compares accepted researcher packets. Its output names approaches, measurements,
+failures, contradictions, evidence gaps, and candidate transfer claims. It cannot validate claims or
+change root state.
+
+### Phase 3 — independent review packet
+
+One independent depth-one packet challenges every material claim against the evaluator or rubric and
+source receipts. Verdicts are `validated`, `challenged`, `overturned`, or `needs_review`. Missing
+reviewer provenance, timeout, stale inputs, or unavailable evidence blocks transfer.
+
+### Phase 4 — root acceptance and transfer
+
+The root accepts only validated findings. Every accepted finding links researcher packet, poster
+packet, review receipt, evaluator evidence, and round identity. The root proposes exact result rows,
+accepted-finding references, and one round event under the current lifecycle revision. Only explicit
+`/start-work` applies those bounded root writes.
+
+## Convergence
+
+Conditions are evaluated in this order:
+
+1. cancellation or stale-state blocker;
+2. target reached by accepted evaluator evidence;
+3. total iteration, round, task-call, wall-clock, or resource budget exhausted;
+4. all lanes stalled or failed;
+5. two complete reviewed rounds with no material improvement under the approved noise rule;
+6. otherwise continue with the next approved round.
+
+Budget exhaustion and all-lane stall are terminal but not success. Qualitative convergence requires
+the approved rubric and two complete independently reviewed rounds. Self-assessment is evidence, not
+the authoritative acceptance criterion.
+
+## Knowledge transfer
+
+Transfer is a root-owned reference update, not a shared child document. The next round receives a
+bounded list of accepted finding identifiers and summaries. Rejected, challenged, and unresolved
+claims stay outside that list. Children may cite accepted identifiers but cannot edit or replace them.
+
+## Conflict handling
+
+Conflicting proposals are compared read-only against the same baseline digest and evaluator. The root
+records incompatible paths, receipts, and uncertainty, then requests a user decision or an additional
+approved experiment. Metric rank alone never grants write authority or decides which bytes to apply.
+
+## Resume and interruption
+
+Resume follows `references/crash-recovery.md`. The root parses bounded events, verifies packet hashes,
+recomputes remaining budget, checks live capability, and identifies the first incomplete phase.
+Completed phase receipts are not repeated. Unreceipted artifacts are preserved and reported. Any
+continuation requires an approved recovery packet and explicit `/start-work resume` with current CAS.
+
+## Cancellation and completion
+
+Cancellation stops new task calls and preserves accepted receipts. After a terminal condition, a
+packet-only synthesis lane may propose report bytes if capability remains available. `/review-work`
+then checks scope, tests and evidence, package or artifact integrity, security and provenance, and the
+real user surface.
+
+Completion reports terminal reason, accepted and rejected packets, evidence gaps, changed paths,
+remaining risks, and cleanup observations. Temporary paths are preserved by default. Any local
+cleanup is a separate approved action with a receipt. Publication, release, deployment, external
+upload, source-control mutation, and live OpenCode configuration are outside this protocol.

package/skills/autoconference/references/convergence-guide.md

@@ -0,0 +1,167 @@
+# Convergence Guide
+
+## OpenCode authority envelope
+
+This reference is inert decision guidance. `lit-plan` must approve the finite root-owned target,
+budget, roots, evaluator, and review contract before any mutation or delegation, including
+interactive runs. Only explicit `/start-work` may consume that approval. Children remain depth-one
+and packet-only; children must not write or mutate root-owned state, select models, or invoke routes.
+
+Focused reference for convergence detection, tuning, and termination tradeoffs in autoconference.
+
+---
+
+## Convergence Conditions
+
+### Metric Mode
+
+| Condition | Trigger | Code |
+|-----------|---------|------|
+| Target Reached | Any researcher's `metric_value` hits the target defined in `Success Metric` | `CONVERGED` |
+| Metric Plateau | Best metric across ALL researchers unchanged for 2 consecutive complete rounds | `CONVERGED` |
+| Budget Exhaustion | `max_total_iterations`, `max_rounds`, or `time_budget` hit | `BUDGET_STOP` |
+| All Stalled | Every researcher at stuck Level 2+ simultaneously in the same round | `STALLED` |
+
+**Evaluation order matters.** The Conference Chair checks in this sequence — first match wins:
+
+```
+1. Any TARGET_REACHED?                              → CONVERGED → synthesis
+2. Budget hit (iterations / rounds / time)?          → BUDGET_STOP → synthesis
+3. All researchers stalled?                          → STALLED → synthesis
+4. Metric plateau (2 consecutive no-improve rounds)? → CONVERGED → synthesis
+5. None of the above?                                → continue → round N+1
+```
+
+**Noise threshold:** Default is 0.1% of the baseline metric value. For integer-valued metrics (e.g., test cases passed), the threshold is 0. A round's best metric must exceed the previous round's best by more than this threshold to count as an improvement.
+
+### Qualitative Mode
+
+| Condition | Trigger | Code |
+|-----------|---------|------|
+| Quality Plateau | Reviewer assigns scores >= 8/10 to ALL researcher outputs for 2 consecutive rounds | `CONVERGED` |
+| Early Quality | All researchers score 9-10 in a single round (Conference Chair discretion) | `CONVERGED` |
+| Budget Exhaustion | Same as metric mode | `BUDGET_STOP` |
+| All Stalled | Same as metric mode | `STALLED` |
+| Sub-threshold Plateau | Reviewer scores plateau below 8 for 2+ rounds with no improvement | `STALLED` |
+
+**Score source:** The Reviewer's authoritative scores in `peer_review_round_{N}.md` under "Qualitative Scores" — NOT the researchers' self-assessment scores.
+
+---
+
+## Tuning Convergence Sensitivity
+
+### Plateau Window
+
+The default plateau window is **2 consecutive rounds**. This balances:
+- **Too short (1 round):** Premature convergence. A single unlucky round triggers early stop, missing potential breakthroughs in the next round.
+- **Too long (3+ rounds):** Wasted budget. Continuing after genuine convergence burns iterations that could be saved.
+
+To adjust: Currently hardcoded at 2. To customize, the Conference Chair can be instructed in the conference.md `Goal` section (e.g., "Use a 3-round convergence window for this exploratory conference").
+
+### Noise Threshold
+
+| Metric Type | Default Threshold | Rationale |
+|-------------|-------------------|-----------|
+| Continuous (float) | 0.1% of baseline | Filters measurement noise |
+| Integer | 0 | Any improvement counts |
+| Percentage (0-100) | 0.1 absolute | Small enough to detect real gains |
+
+**When to increase:** High-variance metrics where measurement noise exceeds 0.1% (e.g., benchmark latency on shared hardware). Set to 1-2% to avoid false convergence signals from noisy runs.
+
+**When to decrease:** Precision-sensitive tasks where 0.01% matters (e.g., model accuracy on large test sets). Set to 0.01% or use exact comparison.
+
+### Qualitative Score Threshold
+
+The default convergence threshold is **8/10** from the Reviewer. Interpretation:
+
+| Score | Meaning | Converge? |
+|-------|---------|-----------|
+| 9-10 | Exceeds criteria | Yes (even after 1 round at Chair's discretion) |
+| 8 | Meets criteria, minor gaps | Yes (after 2 consecutive rounds) |
+| 7 | Solid but with clear gaps | No — keep iterating |
+| <= 6 | Below criteria | No — significant work remains |
+
+---
+
+## Early Termination vs Budget Exhaustion
+
+### When Early Termination Is Good
+
+- **Genuine convergence:** The metric has truly plateaued and more iterations will not help. Saving budget is the right call.
+- **Target reached:** A researcher hit the success metric. No reason to continue (unless the user wants to find an even better solution — rare).
+- **All stalled:** Every researcher has exhausted their search space. Continuing wastes resources.
+
+### When Early Termination Is Bad
+
+- **False plateau:** The metric appeared stuck but a breakthrough was imminent. This happens when:
+  - Researchers are in the middle of a strategy shift (Level 1 stuck → pivot → improvement coming)
+  - The search space has "plateaus before cliffs" — long flat regions followed by sudden drops
+  - One researcher is close to a breakthrough but hasn't reported it yet (it's mid-iteration)
+
+**Mitigation:** The 2-round window helps — a single bad round doesn't trigger convergence. Additionally, the ENDGAME signal on the final round gives researchers one last chance to EXPLOIT.
+
+### When Budget Exhaustion Is Good
+
+- **Exploratory conferences:** The user set a generous budget intentionally. Running all rounds maximizes coverage of the search space.
+- **Noisy metrics:** When individual measurements are unreliable, more data points improve the synthesis.
+- **Qualitative mode:** Self-assessment is unreliable, so running more rounds gives the Reviewer more chances to correct course.
+
+### When Budget Exhaustion Is Bad
+
+- **Clear convergence ignored:** The metric stopped improving 3 rounds ago but `max_rounds` hasn't been reached. This wastes the user's time and compute.
+
+**Mitigation:** The convergence check runs every round and will trigger `CONVERGED` before budget is exhausted if a true plateau is detected.
+
+---
+
+## Convergence Patterns
+
+### Pattern 1: Quick Convergence (2-3 rounds)
+
+```
+Round 1: Researchers explore diverse strategies, one finds a strong approach
+Round 2: Knowledge transfer spreads the winning strategy; all researchers refine it
+Round 3: Minimal improvement → CONVERGED
+```
+
+**Characteristics:** Small search space, clear optimal direction, researchers rapidly align. Common in well-understood optimization problems.
+
+### Pattern 2: Gradual Convergence (5+ rounds)
+
+```
+Round 1-2: Initial exploration, moderate improvements
+Round 3-4: Cross-pollination produces novel combinations
+Round 5-6: Diminishing returns, metric plateaus → CONVERGED
+```
+
+**Characteristics:** Large search space, complementary strategies that benefit from synthesis. The most valuable pattern — the conference format adds the most value here.
+
+### Pattern 3: Breakthrough After Plateau
+
+```
+Round 1-3: Steady improvement, then plateau
+Round 4: One researcher makes a breakthrough via radical pivot
+Round 5: Knowledge transfer spreads breakthrough → rapid improvement
+Round 6: New plateau → CONVERGED
+```
+
+**Characteristics:** Search space has local optima. The Devil's Advocate researcher or a Level 2 DEEP PIVOT often triggers the breakthrough. This is why the 2-round convergence window exists — it prevents premature termination during the plateau at round 3.
+
+### Pattern 4: Stalled Conference
+
+```
+Round 1-2: Moderate improvement
+Round 3: All researchers hit Level 2 stuck
+Round 3: → STALLED → early synthesis
+```
+
+**Characteristics:** Search space is too constrained, or the problem is harder than expected. The synthesis still produces value — negative results and failed strategies inform future work.
+
+### Pattern 5: Budget Exhaustion (No Convergence)
+
+```
+Round 1-N: Continuous improvement, never plateaus
+Round N: max_rounds hit → BUDGET_STOP → synthesis
+```
+
+**Characteristics:** Rich search space with many viable strategies. The conference could have benefited from more rounds. Consider re-running with a larger budget or narrower search space partitions.

package/skills/autoconference/references/core-principles.md

@@ -0,0 +1,83 @@
+# Core Principles
+
+## OpenCode authority envelope
+
+This reference is inert design guidance. `lit-plan` must approve the finite root-owned objective,
+budget, roots, packet contract, and review policy before any mutation or delegation, including
+interactive runs. Only explicit `/start-work` may consume that approval. Children remain depth-one
+and packet-only; children must not write or mutate root-owned state, select models, or invoke routes.
+
+Eleven principles behind the autoconference orchestration system. Principles 1–7 are inherited from autoresearch-skill and apply to each Researcher agent's inner loop. Principles 8–11 are conference-specific and govern the multi-agent coordination layer.
+
+---
+
+## Section 1 — Inherited Principles (from autoresearch-skill)
+
+These apply to each Researcher agent's inner loop. See [autoresearch-skill core-principles](https://github.com/wjgoarxiv/autoresearch-skill/blob/main/references/core-principles.md) for full explanations.
+
+| # | Principle | Definition | conference.md Field |
+|---|-----------|-----------|---------------------|
+| 1 | **Single Metric** | Optimize exactly one measurable quantity. Multiple objectives cause the agent to game tradeoffs instead of improving. | `Success Metric` |
+| 2 | **Mechanical Verification** | The metric must be computable without human judgment. *(Relaxed in qualitative mode — see Principle 9)* | `Success Metric → Target` |
+| 3 | **Atomic Changes** | One change per iteration. Compound changes make it impossible to attribute improvement or regression. | Enforced by the loop protocol |
+| 4 | **Keep or Revert** | If the metric improves, keep the change. Otherwise, revert immediately. No "maybe." | `researcher_{ID}_results.tsv → status` |
+| 5 | **Full History** | Record every attempt — successes AND failures. Failed approaches constrain the search space for future rounds. | Per-researcher logs + TSV |
+| 6 | **Constrained Search** | Explicitly define what can change and what cannot. Without boundaries, agents may "cheat." | `Search Space → Allowed / Forbidden` |
+| 7 | **Autonomous Loop** | The loop runs without human intervention within its constraints. | `Constraints → pause_every: never` |
+
+---
+
+## Section 2 — Conference Principles (new)
+
+| # | Principle | Definition | conference.md Field |
+|---|-----------|-----------|---------------------|
+| 8 | **Knowledge Transfer** | Validated findings must propagate to all researchers between rounds. Without sharing, parallel research degenerates into N independent runs with no synergy. | `Shared Knowledge` section |
+| 9 | **Adversarial Review** | Claims must survive challenge before propagating. Self-evaluation has blind spots (Goodhart's Law). An external reviewer with deep reasoning catches overfitting, noise, and invalid comparisons. | `peer_review_round_N.md` |
+| 10 | **Synthesis Over Selection** | The final output combines complementary insights from multiple researchers, not just picks the winner. The conference's value is in cross-pollination — insights no single researcher would produce alone. | `synthesis.md` |
+| 11 | **Relentless Persistence** | The conference runs until the budget is spent or convergence is reached. Stopping early leaves the most valuable cross-pollination unrun. | Conference Persistence Directive |
+
+---
+
+## Why Each Conference Principle Matters
+
+### 8. Knowledge Transfer
+
+- **Why:** Parallel researchers exploring independent search partitions will rediscover each other's dead ends if findings are never shared. Knowledge transfer converts N parallel experiments into a compound learning process where each researcher's next round is informed by all others' prior rounds.
+- **Violation consequence:** The conference degenerates into N independent autoresearch runs. There is zero synergy. The conference overhead (poster session, peer review) is incurred with no benefit over running autoresearch N times separately.
+- **Example:** Researcher A discovers in Round 1 that batch normalization causes instability with this dataset. If this is not shared, Researcher B wastes Round 2 trying the same approach. With knowledge transfer, Researcher B reads "BN unstable — avoid" and explores a different direction instead.
+
+### 9. Adversarial Review
+
+- **Why:** Self-evaluation is systematically optimistic. Researchers measure their own work against their own understanding of the metric. A reviewer with no stake in the result and explicit instructions to challenge claims catches what self-evaluation misses: overfitting to the test set, measurement noise mistaken for improvement, valid-looking but flawed comparisons.
+- **Violation consequence:** Goodhart's Law activates. Researchers optimize for the appearance of progress. Noise is reported as signal. Overfit improvements propagate to Shared Knowledge and corrupt subsequent rounds.
+- **Example:** Researcher A reports a 3% accuracy improvement. Without review, this propagates to all researchers. With review, the Reviewer checks: "Was the test set fixed? Was the same random seed used? Is 3% within measurement noise?" — and may overturn the claim, preventing a false positive from contaminating the shared state.
+- **Note on qualitative mode:** Self-assessment makes Principle 9 more critical, not less. An independent reviewer packet provides the authoritative quality verdict each round, compensating for unreliable self-assessed proxies.
+
+### 10. Synthesis Over Selection
+
+- **Why:** Picking the "winning" researcher discards 2/3 of the work done. Different researchers explore different search space partitions and develop complementary insights. The synthesizer's job is to identify which insights are orthogonal (can be combined) vs. redundant (can be deduplicated), producing a unified result that no single researcher could have reached alone.
+- **Violation consequence:** The conference produces a result equivalent to running one autoresearch with extra steps. The cross-pollination value — the primary reason to run a conference — is lost.
+- **Example:** Researcher A finds the best architectural change. Researcher B finds the best hyperparameter configuration. Neither tested their improvement in combination. The Synthesizer identifies these as orthogonal improvements and combines them, producing a result better than either individual finding.
+
+### 11. Relentless Persistence
+- **Why:** Conference value compounds across rounds. Round 1 finds local optima. Round 3+ enables cross-pollination breakthroughs where Researcher A's validated insight transforms Researcher B's approach.
+- **Violation consequence:** Conference stops after round 1 with isolated results. The synthesis that would have emerged from cross-pollination never happens.
+- **Example:** A 3-round conference with 3 researchers: Round 1 finds 3 local optima. Round 2 cross-pollinates, producing 2 hybrid approaches. Round 3 synthesizes. Stopping at round 1 misses the synthesis entirely.
+
+---
+
+## Mapping to conference.md
+
+| Principle | conference.md Section | Enforcement |
+|-----------|----------------------|-------------|
+| Single Metric | `## Success Metric` | Template requires exactly one metric + direction |
+| Mechanical Verification | `## Success Metric → Target` | Target must be a computable expression |
+| Atomic Changes | (Loop protocol) | Researcher agent instructed per-prompt |
+| Keep or Revert | Per-researcher TSV | Each row records `kept` or `reverted` |
+| Full History | Researcher logs + TSV | Append-only; never delete rows |
+| Constrained Search | `## Search Space` | Allowed and Forbidden explicitly listed |
+| Autonomous Loop | `## Constraints` | Default: no pause |
+| Knowledge Transfer | `## Shared Knowledge` | Conference Chair populates after each round |
+| Adversarial Review | `peer_review_round_N.md` | Independent reviewer packet runs after every poster packet |
+| Synthesis Over Selection | `synthesis.md` | Packet-only synthesis runs once at the end |
+| Relentless Persistence | Conference Persistence Directive | Conference Chair advances rounds automatically until budget or convergence |

package/skills/autoconference/references/crash-recovery.md

@@ -0,0 +1,104 @@
+# Root-Owned Crash Recovery Matrix
+
+## OpenCode authority envelope
+
+This reference is inert recovery guidance. `lit-plan` must approve the finite root-owned recovery
+point, remaining budget, roots, packet schema, and stale-state response before any mutation or
+delegation, including interactive runs. Only explicit `/start-work` may consume that approval.
+Children remain depth-one and packet-only; children must not write or mutate root-owned state,
+select models, or invoke routes.
+
+Recovery is read-first and fail-closed. The root reconciles regular files, bounded event lines, packet
+identities, hashes, lifecycle revision, and remaining budget. It never assumes that an absent event
+means an action failed, and it never treats an unreceipted artifact as accepted state.
+
+## Common diagnosis
+
+Before proposing recovery, the root performs only approved reads:
+
+1. parse `conference_events.jsonl` in order and reject malformed or non-monotonic records;
+2. locate the last complete phase receipt for the current work and round;
+3. compare packet identities and hashes with root result rows;
+4. classify extra or partial artifacts as unreceipted rather than deleting them;
+5. compare goal, evaluator, roots, baseline digest, dependency inputs, and lifecycle revision;
+6. verify real OpenCode task capability again before proposing another child call;
+7. calculate the exact remaining round, iteration, wall-clock, and task-call budget.
+
+Any mismatch that changes meaning returns `BLOCKED_STALE_CONFERENCE_STATE`. Missing task capability
+returns `BLOCKED_MULTI_AGENT_UNAVAILABLE`. Diagnosis itself writes nothing.
+
+## Recovery type 1 — interrupted researcher packet
+
+**Signal:** a round-start receipt exists, but one or more approved researcher packet identities have no
+terminal receipt.
+
+**Proposal:** preserve accepted packets, mark unresolved identities as incomplete in the recovery
+packet, and offer either redispatch of only those identities or continuation with explicitly partial
+evidence. The user approves one option through `lit-plan`; explicit `/start-work resume` consumes it.
+
+The replacement call receives a new packet identity and the same approved partition, evaluator,
+baseline digest, and remaining budget. Partial child output remains evidence but cannot be merged with
+the replacement packet without reviewer reconciliation.
+
+## Recovery type 2 — interrupted poster packet
+
+**Signal:** all intended researcher packets are terminal, but there is no accepted poster receipt.
+
+**Proposal:** leave any unreceipted poster artifact untouched, identify it in the recovery report, and
+issue a fresh poster packet using the accepted researcher packets only. The root accepts the new packet
+only after schema, identity, and hash checks.
+
+## Recovery type 3 — interrupted reviewer packet
+
+**Signal:** an accepted poster receipt exists, but material claims lack an accepted review receipt.
+
+**Proposal:** preserve the poster packet, classify any partial review artifact as unreceipted, and issue
+a fresh independent reviewer packet with the same rubric and evidence map. Knowledge transfer remains
+blocked until the root accepts the review packet.
+
+## Recovery type 4 — interrupted root transfer
+
+**Signal:** an accepted review receipt exists, but root result rows, accepted-finding references, and
+the round-complete event do not agree.
+
+**Proposal:** derive an idempotent transfer set from accepted packet and review identities. For each
+candidate root write, record expected prior digest, proposed resulting bytes, and the event identity to
+append. Do not apply any part during diagnosis. Explicit `/start-work resume` applies the exact approved
+set with current CAS revision or stops stale.
+
+If a proposed prior digest no longer matches, preserve current bytes and return a conflict packet. Do
+not guess which version is newer or more valuable.
+
+## Recovery type 5 — interrupted synthesis
+
+**Signal:** a terminal conference reason is accepted, but no accepted synthesis packet and completion
+receipt agree.
+
+**Proposal:** preserve all round receipts and any unreceipted report artifact. Issue a fresh synthesis
+packet containing only accepted findings, review verdicts, terminal reason, and report schema. The root
+may finalize proposed report bytes only through the active approved lifecycle.
+
+## Idempotency and replay
+
+- Completed phase receipts are immutable inputs and are not repeated.
+- A request identity replay with identical payload is idempotent; reuse with different payload fails.
+- A stale lifecycle revision cannot apply a recovery packet.
+- A late child packet cannot satisfy a newer identity.
+- Missing evidence remains missing; recovery does not reconstruct it from prose.
+- Cancellation is terminal for the current work and stops new dispatch.
+
+## Recovery output
+
+The read-only recovery report names:
+
+- work identity, round, last accepted phase, and current lifecycle revision;
+- accepted, partial, missing, malformed, late, and stale packets;
+- remaining finite budget and capability verdict;
+- exact proposed root actions and their expected prior digests;
+- paths preserved without change;
+- the explicit `/start-work resume` command boundary or a blocker.
+
+Temporary and user-owned paths are not removed automatically. Cleanup is a separately approved local
+proposal after recovery or cancellation, followed by a receipt listing removed, preserved, absent, and
+blocked paths. No recovery path grants publication, release, source-control mutation, or live-profile
+authority.

package/skills/autoconference/references/results-logging.md

@@ -0,0 +1,198 @@
+# Results Logging Protocol
+
+## OpenCode authority envelope
+
+This reference is inert schema guidance. `lit-plan` must approve the finite root-owned result paths,
+budget, roots, packet schema, and review contract before any mutation or delegation, including
+interactive runs. Only explicit `/start-work` may consume that approval. Children remain depth-one
+and packet-only; children must not write or mutate root-owned state, select models, or invoke routes.
+
+Structured logging for machine-readable experiment tracking at two levels: per-researcher (matching autoresearch format) and conference-level (adding researcher identity, round context, and peer review verdicts).
+
+---
+
+## Section 1 — Per-Researcher TSV (`researcher_{ID}_results.tsv`)
+
+One file per researcher (e.g., `researcher_A_results.tsv`, `researcher_B_results.tsv`). Same schema as autoresearch's `autoresearch-results.tsv` for compatibility.
+
+### Schema
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `iteration` | int | 0-indexed iteration number within the current round |
+| `metric_value` | float | Measured metric value (or self-assessment score 1-10 in qualitative mode) |
+| `delta` | float or `-` | Change from baseline (iteration 0 of this researcher) |
+| `delta_pct` | string | Percentage change from baseline |
+| `status` | enum | `baseline`, `kept`, `reverted` |
+| `description` | string | One-line description of the change |
+| `evaluator_source` | string | Source of the evaluation — e.g., `script:evaluate.py`, `review-packet:independent`, `self-assessment` |
+| `timestamp` | ISO 8601 UTC | Real UTC instant in `YYYY-MM-DDTHH:MM:SS[.sss]Z` form |
+
+### Example
+
+```tsv
+iteration	metric_value	delta	delta_pct	status	description	evaluator_source	timestamp
+0	2.3991	-	-	baseline	Recursive quicksort with list comprehensions	script:benchmark.py	2026-03-18T10:00:00Z
+1	1.8845	-0.5146	-21.4%	kept	Bottom-up iterative merge sort	script:benchmark.py	2026-03-18T10:05:00Z
+2	1.7265	-0.6726	-28.0%	kept	Merge sort + insertion sort for subarrays < 32	script:benchmark.py	2026-03-18T10:10:00Z
+3	1.9504	-0.4487	-18.7%	reverted	Natural merge sort with run detection	script:benchmark.py	2026-03-18T10:15:00Z
+4	0.9817	-1.4174	-59.1%	kept	LSD radix sort base 256	script:benchmark.py	2026-03-18T10:20:00Z
+```
+
+### Notes
+
+- **Qualitative mode:** `metric_value` holds the researcher's self-assessed quality score (1-10). The Reviewer's authoritative scores appear in the conference-level TSV.
+- **Iteration numbering:** Resets to 0 at the start of each round for simplicity. The round context is captured in the conference-level TSV.
+- **Baseline row:** The first row of each round uses `status: baseline` and `delta: -`.
+
+---
+
+## Section 2 — Conference-Level TSV (`conference_results.tsv`)
+
+One file for the entire conference. Adds researcher identity, round context, and peer review verdicts on top of the per-researcher schema.
+
+### Schema
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `round` | int | Conference round number (1-indexed) |
+| `researcher` | string | Researcher identifier (`A`, `B`, `C`, ...) |
+| `iteration` | int | Iteration within the round (0-indexed) |
+| `metric_value` | float | Measured metric value |
+| `delta` | float or `-` | Change from round baseline |
+| `delta_pct` | string | Percentage change from round baseline |
+| `status` | enum | `baseline`, `kept`, `reverted`, `failed` |
+| `description` | string | One-line description of the change |
+| `evaluator_source` | string | Source of the evaluation — e.g., `script:evaluate.py`, `review-packet:independent`, `self-assessment` |
+| `peer_review_verdict` | enum | `validated`, `challenged`, `overturned`, `-` |
+| `timestamp` | ISO 8601 | When the experiment completed |
+
+### Example
+
+```tsv
+round	researcher	iteration	metric_value	delta	delta_pct	status	description	evaluator_source	peer_review_verdict	timestamp
+1	A	0	2.3991	-	-	baseline	Recursive quicksort baseline	script:benchmark.py	-	2026-03-18T10:00:00Z
+1	A	1	1.8845	-0.5146	-21.4%	kept	Bottom-up iterative merge sort	script:benchmark.py	validated	2026-03-18T10:05:00Z
+1	A	2	1.7265	-0.6726	-28.0%	kept	Merge sort + insertion sort < 32	script:benchmark.py	validated	2026-03-18T10:10:00Z
+1	B	0	2.4012	-	-	baseline	Recursive quicksort baseline	script:benchmark.py	-	2026-03-18T10:00:00Z
+1	B	1	2.1500	-0.2512	-10.5%	kept	Heap sort implementation	script:benchmark.py	challenged	2026-03-18T10:07:00Z
+1	B	2	1.9800	-0.4212	-17.5%	kept	Heap sort with Floyd's algorithm	script:benchmark.py	validated	2026-03-18T10:12:00Z
+1	C	0	2.3950	-	-	baseline	Recursive quicksort baseline	script:benchmark.py	-	2026-03-18T10:00:00Z
+1	C	1	0.9817	-1.4133	-59.1%	kept	LSD radix sort base 256	script:benchmark.py	validated	2026-03-18T10:08:00Z
+2	A	0	1.7265	-	-	baseline	Round 2 start from best known	script:benchmark.py	-	2026-03-18T10:30:00Z
+2	A	1	1.5100	-0.2165	-12.5%	kept	Merge sort + radix hybrid	script:benchmark.py	validated	2026-03-18T10:35:00Z
+```
+
+### Status Values
+
+| Value | Meaning |
+|-------|---------|
+| `baseline` | Starting point for this researcher in this round |
+| `kept` | Change improved the metric and was kept |
+| `reverted` | Change did not improve metric; reverted to previous best |
+| `failed` | Researcher crashed, timed out, or self-terminated before completing the iteration |
+
+### Peer Review Verdict Values
+
+| Value | Meaning |
+|-------|---------|
+| `validated` | Reviewer confirmed the claim holds |
+| `challenged` | Reviewer flagged the claim as questionable; needs more evidence |
+| `overturned` | Reviewer determined the claim is invalid |
+| `-` | Not yet reviewed (e.g., baseline row, or round not yet complete) |
+
+Every conference-level row must have exactly the eleven documented fields. For every completed round,
+each configured researcher must have exactly one genuine iteration-0 `baseline` row with finite metric,
+`-` delta/percentage, and `-` peer verdict; later rows are non-baseline experiments. `round` is an integer
+from 1 through configured max rounds; `researcher` is one of the configured `A` through `Z` identifiers;
+`iteration` is unique within that round/researcher tuple. Percentage, status, peer verdict, non-empty
+description/source, and real UTC timestamp must match this schema. Missing or placeholder baselines,
+extra/missing fields, unknown researchers, out-of-range rounds, duplicate evidence identities, invalid
+enums, or non-finite metrics invalidate completion evidence.
+
+---
+
+## Section 3 — Event Log (`conference_events.jsonl`)
+
+An append-only JSONL file recording all significant conference events. Each line is a JSON object. External tools can tail this file for real-time monitoring.
+
+### Schema
+
+```json
+{
+  "event": "<event_type>",
+  "timestamp": "<ISO 8601>",
+  "payload": { ... }
+}
+```
+
+### Event Types
+
+| Event | When | Payload Fields |
+|-------|------|----------------|
+| `conference.started` | Conference Chair initializes | `researchers`, `mode`, `goal`, `config_summary` |
+| `round.started` | Each round begins | `round`, `researcher_states` |
+| `researcher.iteration` | Researcher completes an iteration | `researcher`, `round`, `iteration`, `metric_value`, `delta`, `status` |
+| `round.poster_session` | Poster session complete | `round`, `summary` |
+| `round.peer_review` | Peer review complete | `round`, `validated_count`, `challenged_count`, `overturned_count` |
+| `round.completed` | Round finishes | `round`, `best_metric`, `best_researcher`, `converged` |
+| `researcher.stuck` | Researcher hits stuck Level 2+ | `researcher`, `round`, `stuck_level` |
+| `conference.converged` | Convergence detected | `final_best_metric`, `round_count`, `reason` |
+| `conference.completed` | Synthesis done | top-level `terminal_verdict`; payload `synthesis_path`, `final_report_path`, `total_iterations`, `total_rounds`, `researcher_count` |
+
+### Example
+
+```jsonl
+{"event":"conference.started","timestamp":"2026-03-18T10:00:00Z","payload":{"researchers":3,"mode":"metric","goal":"Optimize inference latency","config_summary":"metric=p95_latency_ms, direction=minimize, target=<50ms"}}
+{"event":"round.started","timestamp":"2026-03-18T10:00:05Z","payload":{"round":1,"researcher_states":["A:ready","B:ready","C:ready"]}}
+{"event":"researcher.iteration","timestamp":"2026-03-18T10:05:00Z","payload":{"researcher":"A","round":1,"iteration":1,"metric_value":1.8845,"delta":-0.5146,"status":"kept"}}
+{"event":"round.poster_session","timestamp":"2026-03-18T10:20:00Z","payload":{"round":1,"summary":"A: merge sort -28%, B: heap sort -17.5%, C: radix sort -59.1%"}}
+{"event":"round.peer_review","timestamp":"2026-03-18T10:25:00Z","payload":{"round":1,"validated_count":5,"challenged_count":1,"overturned_count":0}}
+{"event":"round.completed","timestamp":"2026-03-18T10:26:00Z","payload":{"round":1,"best_metric":0.9817,"best_researcher":"C","converged":false}}
+{"event":"conference.completed","timestamp":"2026-03-18T11:45:00Z","terminal_verdict":"TARGET_MET","payload":{"synthesis_path":"synthesis.md","final_report_path":"final_report.md","total_iterations":45,"total_rounds":3,"researcher_count":3}}
+```
+
+Every valid `round.completed` payload contains an in-range integer `round`, finite numeric `best_metric`,
+a configured `best_researcher`, and boolean `converged`. Its best researcher and metric must match the
+direction-aware best non-failed conference TSV row for that round. Duplicate, incomplete, invalid, or
+unreconciled round receipts invalidate completion even if a later receipt is valid. At terminal state,
+TSV rounds and sequential completed-round receipts must name the same round set.
+
+The terminal verdict is one of `TARGET_MET`, `CONVERGED`, `BUDGET_EXHAUSTED`, `STALLED`, `CANCELLED`,
+or `BLOCKED`. The packaged status helper parses JSONL with the guaranteed Node runtime and validates
+the latest valid-JSON `conference.completed` object. Its UTC timestamp must be real; artifact paths
+must be exactly `synthesis.md` and `final_report.md`; and all three non-negative integer counts must
+reconcile with fully schema-valid results TSV rows, reconciled `round.completed` events, configured max
+rounds, and configured researcher count. `payload.total_iterations` counts only non-baseline experiment
+rows across all researchers and rounds; required iteration-0 baseline rows are excluded.
+Malformed JSON is ignored as an incomplete append. Valid JSON that names the terminal event but has a
+missing or invalid verdict, payload, path, timestamp, or count is `terminal invalid` with exit code 4.
+An unavailable Node command yields `BLOCKED_NODE_UNAVAILABLE` with exit code 3; a parser invocation
+failure yields `BLOCKED_NODE_RUNTIME_ERROR` with the same exit code. Neither condition silently falls
+back to another runtime.
+
+---
+
+## Usage
+
+The TSV files and event log enable:
+
+- **Programmatic analysis:** Load `conference_results.tsv` into pandas; plot per-researcher convergence curves; compute cross-researcher strategy comparison.
+- **CI integration:** Parse the last row of `conference_results.tsv` to check if the target was met. Same pattern as autoresearch-skill.
+- **Cross-project comparison:** Standardized format across all autoconference runs.
+- **Bounded monitoring:** After an approved finite conference step, read at most the last 200 records from `conference_events.jsonl`, capture the snapshot, and stop.
+- **Peer review accuracy analysis:** Compare `peer_review_verdict` against final synthesis outcomes to measure reviewer quality over time.
+
+## Relationship to Other Output Files
+
+| File | Purpose | Format | Audience |
+|------|---------|--------|----------|
+| `conference.md` | User configuration + Conference Log | Markdown | Humans |
+| `researcher_{ID}_log.md` | Detailed per-iteration reasoning | Markdown | Humans |
+| `researcher_{ID}_results.tsv` | Per-researcher machine-readable results | TSV | Scripts/CI |
+| `conference_results.tsv` | Conference-level results with verdicts | TSV | Scripts/CI |
+| `conference_events.jsonl` | Event stream for real-time monitoring | JSONL | Scripts/monitoring |
+| `poster_session_round_N.md` | Session Chair's round summary | Markdown | Humans |
+| `peer_review_round_N.md` | Reviewer's verdicts per round | Markdown | Humans |
+| `synthesis.md` | Synthesizer's unified result | Markdown | Humans |
+| `final_report.md` | Executive summary | Markdown | Humans |