@litfamily/litopencode 1.0.0

package/skills/autoresearch/references/persona-templates.md

@@ -0,0 +1,232 @@
+# Persona Templates
+
+## OpenCode authority envelope
+
+This reference is inert guidance. `lit-plan` must approve the question, persona packet schema, finite
+budget, canonical roots, output write set, rollback policy, and review gate before any mutation,
+including an interactive run. Only explicit `/start-work` may perform bounded writes, commands,
+evaluation, or reversion within that packet; personas never grant authority.
+
+Reference library for `autoresearch:predict`. Select 4–6 personas per deliberation based on the question domain. Each persona has a fixed reasoning style and known biases — these biases are features, not bugs. Diversity of bias produces better deliberation.
+
+---
+
+## Default Personas (General-Purpose)
+
+### 1. Optimist
+
+**Reasoning style:** Focuses on best-case trajectories. Weighs upside evidence heavily. Assumes execution problems are solvable given motivation.
+
+**Characteristic moves:**
+- Cites historical examples of things that worked despite skepticism
+- Discounts transition costs as temporary
+- Assumes rational actors will adapt and improve
+- Finds signal in early positive indicators others dismiss as noise
+
+**Known biases:**
+- Overweights recent positive signals
+- Underweights structural constraints and systemic inertia
+- Assumes willingness implies capability
+
+**Typical confidence range:** 70–90% on favorable outcomes
+
+---
+
+### 2. Pessimist
+
+**Reasoning style:** Focuses on failure modes. Weighs downside evidence heavily. Assumes execution problems compound rather than resolve.
+
+**Characteristic moves:**
+- Cites base rates for similar initiatives that failed
+- Emphasizes second-order effects and unintended consequences
+- Highlights incentive misalignments that sabotage stated goals
+- Assumes good intentions don't translate to good outcomes
+
+**Known biases:**
+- Overweights historical failures without accounting for changed context
+- Underweights human adaptability and creative problem-solving
+- May confuse "hard" with "impossible"
+
+**Typical confidence range:** 60–80% on unfavorable outcomes
+
+---
+
+### 3. Realist
+
+**Reasoning style:** Anchors to base rates, empirical data, and existing evidence. Resists both optimistic and pessimistic pulls. Explicitly models uncertainty.
+
+**Characteristic moves:**
+- Asks "what is the reference class for this?"
+- Separates what is known from what is assumed
+- Assigns explicit probability ranges rather than directional claims
+- Points out where evidence is thin and confidence should be low
+
+**Known biases:**
+- May be excessively conservative — anchors too heavily on past, underweights genuine novelty
+- Can frustrate deliberations by refusing to commit when commitment is needed
+
+**Typical confidence range:** 40–65% (deliberately calibrated uncertainty)
+
+---
+
+### 4. Contrarian
+
+**Reasoning style:** Takes the opposing view of whatever the group appears to favor. Not a pessimist — will argue against pessimism just as readily if pessimism is the consensus.
+
+**Characteristic moves:**
+- Identifies the dominant narrative and immediately looks for its weakest points
+- Asks "what would have to be true for the opposite to be correct?"
+- Finds cases where the conventional wisdom was confidently wrong
+- Stress-tests assumptions that others treat as settled
+
+**Known biases:**
+- Contrarianism for its own sake — may defend weak positions past the point of usefulness
+- Can produce noise when consensus is actually correct
+
+**Typical confidence range:** Varies — always opposite of group mean
+
+---
+
+### 5. Expert
+
+**Reasoning style:** Domain-grounded reasoning. Draws on technical knowledge, field-specific patterns, and insider understanding of how the relevant system actually works.
+
+**Characteristic moves:**
+- Corrects misunderstandings about technical feasibility or domain mechanics
+- Cites specific mechanisms rather than analogies
+- Distinguishes between "possible in theory" and "achievable in practice given constraints"
+- Flags when a question rests on a false technical premise
+
+**Known biases:**
+- May overweight domain-specific knowledge and underweight cross-domain patterns
+- Expert blind spots: assumes domain rules are stable when disruption is possible
+- Can be dismissive of non-expert insights that happen to be correct
+
+**Typical confidence range:** 60–85% within domain, explicitly lower outside it
+
+---
+
+### 6. Newcomer
+
+**Reasoning style:** Reasons from first principles without domain baggage. Asks "obvious" questions that experts have stopped asking. Notices what seems strange from the outside.
+
+**Characteristic moves:**
+- Questions assumptions that experts treat as axioms
+- Applies analogies from unrelated fields
+- Asks "why does it have to work this way?"
+- Often identifies the simplest possible interpretation that experts overcomplicate
+
+**Known biases:**
+- Lacks knowledge of why the "obvious" solution was already tried and failed
+- May reinvent known failure modes
+- Confidence can be miscalibrated due to unknown unknowns
+
+**Typical confidence range:** 50–75% (wide uncertainty bands)
+
+---
+
+## Adversarial Personas
+
+### 7. Devil's Advocate
+
+**Purpose:** Steelmans the least popular position in the room. Not the same as Contrarian — the Devil's Advocate takes the weakest argument and makes it as strong as possible.
+
+**Activation rule:** Add this persona when Phase 4 shows one position is held by only 1 persona, or when consensus is forming early. The Devil's Advocate defends the minority.
+
+**Reasoning style:**
+- Reads the minority position charitably — assumes the best version of the argument
+- Constructs the strongest possible case for it using the opposition's own evidence
+- Identifies what the majority is missing or discounting unfairly
+- Does NOT personally believe the position — role is advocacy, not conviction
+
+**Key question asked:** "What would the best proponent of this view say that hasn't been said yet?"
+
+**Known biases:**
+- May argue positions past the point of intellectual honesty
+- Can derail deliberations if activated when genuine consensus is warranted
+
+---
+
+### 8. Black Swan Hunter
+
+**Purpose:** Identifies catastrophic low-probability scenarios that the other personas are ignoring because they seem unlikely.
+
+**Activation rule:** Add for decisions with irreversible consequences, long time horizons (5+ years), or when the downside of being wrong is existential/catastrophic.
+
+**Reasoning style:**
+- Ignores base rates deliberately — focuses on tail risk
+- Asks "what is the worst plausible outcome, and how would we know it was coming?"
+- Looks for hidden dependencies, single points of failure, and correlated risks
+- Identifies scenarios where multiple unlikely events compound
+
+**Key question asked:** "What is the catastrophic scenario that everyone is implicitly assuming won't happen?"
+
+**Known biases:**
+- Can make deliberations feel paralyzed by improbable scenarios
+- May conflate "catastrophic if true" with "likely enough to act on"
+
+**Confidence range:** Not applicable — Black Swan Hunter does not give confidence estimates. Gives probability floor estimates ("this has at least a 3% chance") and impact estimates instead.
+
+---
+
+## Domain-Specific Persona Sets
+
+For specialized decisions, replace 2–3 default personas with these domain alternatives.
+
+### Technical Architecture Decisions
+
+| Persona | Replace | Focus |
+|---------|---------|-------|
+| Architect | Expert | System design, scalability, long-term maintainability |
+| Security Engineer | Contrarian | Attack surfaces, trust boundaries, failure modes |
+| Product Manager | Optimist | User value, market fit, delivery speed |
+| Operations | Pessimist | Operational burden, incident response, deployment risk |
+
+**Recommended set:** Architect + Security Engineer + Product Manager + Operations + Black Swan Hunter (for irreversible architecture choices)
+
+### Investment / Business Decisions
+
+| Persona | Replace | Focus |
+|---------|---------|-------|
+| Bull | Optimist | Growth thesis, market opportunity |
+| Bear | Pessimist | Competitive threats, execution risk |
+| Analyst | Realist | Comparable companies, financial modeling |
+| Operator | Expert | Unit economics, operational leverage |
+
+### Policy / Social Impact Decisions
+
+| Persona | Replace | Focus |
+|---------|---------|-------|
+| Advocate | Optimist | Best-case impact, intended effects |
+| Critic | Pessimist | Unintended consequences, distributional effects |
+| Economist | Expert | Incentive structures, second-order effects |
+| Affected Party | Newcomer | Ground-level reality, implementation friction |
+
+---
+
+## Customization Guide
+
+To define a new persona for a specific domain:
+
+```
+### [Persona Name]
+
+**Reasoning style:** [1-2 sentences on how they approach problems]
+
+**Characteristic moves:**
+- [Specific argumentative pattern 1]
+- [Specific argumentative pattern 2]
+- [Specific argumentative pattern 3]
+
+**Known biases:**
+- [Systematic blind spot 1]
+- [Systematic blind spot 2]
+
+**Typical confidence range:** [X–Y%]
+```
+
+**Rules for custom personas:**
+1. Each persona must have a distinct reasoning style — not just a different opinion.
+2. Biases must be realistic and predictable — the deliberation engine exploits known biases for diversity.
+3. Avoid personas that are strictly superior (no biases) — they collapse diversity.
+4. Maximum 8 personas per deliberation — diminishing returns beyond that.

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

@@ -0,0 +1,96 @@
+# Results Logging Protocol
+
+## OpenCode authority envelope
+
+This reference is inert guidance. `lit-plan` must approve the result schema, finite budget, canonical
+roots, output write set, rollback policy, and review gate before any mutation, including an
+interactive run. Only explicit `/start-work` may perform bounded log writes, evaluation, or reversion
+within that packet; without it this protocol grants no write authority.
+
+Structured TSV logging for machine-readable experiment tracking.
+
+## File: `autoresearch-results.tsv`
+
+Every research project produces an `autoresearch-results.tsv` file alongside `research.md` and `research_log.md`. This file is append-only and machine-parseable.
+
+## Format
+
+Tab-separated values with these columns:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `iteration` | int | 0-indexed iteration number |
+| `metric_value` | float | Measured metric value |
+| `delta` | float or `-` | Change from baseline (iteration 0) |
+| `delta_pct` | string | Percentage change from baseline |
+| `status` | enum | `baseline`, `kept`, `reverted`, `guard_violation`, `reference` |
+| `description` | string | One-line description of the change |
+| `evaluator_source` | string | `mechanical`, `agent`, or `manual` |
+| `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	agent	2026-03-15T10:00:00Z
+1	1.8845	-0.5146	-21.4%	kept	Bottom-up iterative merge sort	agent	2026-03-15T10:05:00Z
+2	1.7265	-0.6726	-28.0%	kept	Merge sort + insertion sort for subarrays < 32	agent	2026-03-15T10:10:00Z
+3	1.6939	-0.7052	-29.4%	kept	Merge sort + binary insertion sort chunk size 64	agent	2026-03-15T10:15:00Z
+4	1.9504	-0.4487	-18.7%	reverted	Natural merge sort with run detection	agent	2026-03-15T10:20:00Z
+5	0.9817	-1.4174	-59.1%	kept	LSD radix sort base 256	agent	2026-03-15T10:25:00Z
+6	0.7513	-1.6478	-68.7%	kept	LSD radix sort base 65536	agent	2026-03-15T10:30:00Z
+7	0.1780	-2.2211	-92.6%	reference	Python built-in sorted()	agent	2026-03-15T10:35:00Z
+```
+
+Every row must have exactly eight tab-separated fields. Terminal completion requires exactly one genuine
+iteration-0 `baseline` row with a finite `metric_value`, `-` delta, and `-` percentage. Every later
+iteration is a non-baseline experiment. `iteration` is a unique non-negative integer within the
+configured maximum; `metric_value` and any non-`-` `delta` are finite numbers;
+`delta_pct` is `-` or a numeric percentage; status and evaluator source use only the enums above;
+description is non-empty; and timestamp is a real UTC instant. The initializer's row-0 `TBD` baseline is
+only a scaffold placeholder: replace it with measured finite evidence before terminal completion. A
+missing or placeholder baseline, baseline status after iteration 0, duplicate iteration, extra/missing
+column, invalid enum, non-finite metric, or invalid timestamp makes completion evidence `terminal
+invalid` rather than `COMPLETE`.
+
+## Usage
+
+The TSV file enables:
+- **Programmatic analysis:** Load into pandas, plot convergence curves, compute statistics
+- **CI integration:** Parse the last row to check if the target was met
+- **Cross-project comparison:** Standardized format across all autoresearch-skill runs
+- **Git-friendly:** TSV diffs clearly show which iterations were added
+
+## Terminal Event
+
+`autoresearch_events.jsonl` is the append-only lifecycle event stream. Initialization creates it
+empty. The root `/start-work` loop appends `autoresearch.completed` only after it has accepted a
+genuine terminal reason, a finite iteration-0 baseline, and a non-empty final report. The receipt
+names the report rather than relying on file presence alone:
+
+```json
+{"event":"autoresearch.completed","timestamp":"2026-03-15T10:40:00Z","terminal_reason":"TARGET_MET","final_report_path":"final_report.md","results_path":"autoresearch-results.tsv","total_iterations":7}
+```
+
+Allowed terminal reasons are `TARGET_MET`, `BUDGET_EXHAUSTED`, `CANCELLED`, and `BLOCKED`. A terminal
+event with a missing or empty `final_report.md`, or without a genuine finite baseline replacing the
+scaffold's `TBD` row, is never `COMPLETE`. The packaged status helper uses the
+guaranteed Node runtime to parse JSONL. The latest valid-JSON `autoresearch.completed` object must have
+a real UTC timestamp, one allowed `terminal_reason`, the two exact relative artifact paths shown above,
+and a non-negative integer `total_iterations` equal to the number of fully schema-valid non-baseline
+experiment rows. The required iteration-0 baseline is evidence but is not included in that count.
+Malformed JSON is
+ignored as an incomplete write; valid JSON that names the terminal event but misses or violates any
+field is `terminal invalid` with exit code 4. If Node cannot be resolved, status returns
+`BLOCKED_NODE_UNAVAILABLE` with exit code 3 rather than silently changing parsers. A resolved Node
+command that cannot execute the parser returns `BLOCKED_NODE_RUNTIME_ERROR`, also with exit code 3.
+
+## Relationship to Other Output Files
+
+| File | Purpose | Format | Audience |
+|------|---------|--------|----------|
+| `research.md` | Living research document with History table | Markdown | Humans |
+| `research_log.md` | Detailed per-iteration analysis | Markdown | Humans |
+| `autoresearch-results.tsv` | Machine-readable results | TSV | Scripts/CI |
+| `autoresearch_events.jsonl` | Append-only lifecycle and terminal receipts | JSONL | Scripts/CI |
+| `final_report.md` | Executive summary | Markdown | Humans |

package/skills/autoresearch/references/scenario-dimensions.md

@@ -0,0 +1,178 @@
+# Scenario Dimensions
+
+## OpenCode authority envelope
+
+This reference is inert guidance. `lit-plan` must approve the subject, selected dimensions, finite
+budget, canonical roots, output write set, rollback policy, and review gate before any mutation,
+including an interactive run. Only explicit `/start-work` may perform bounded writes, commands,
+evaluation, or reversion within that packet; without it use these prompts read-only.
+
+Reference for `autoresearch:scenario`. Each dimension defines the questions to ask and an example applied to a software system.
+
+---
+
+## Dimension 1: Best Case
+
+**Description:** All assumptions hold, all collaborators perform optimally, and every external condition is favorable. The ceiling of what success looks like.
+
+**Questions to ask:**
+- What does complete success look like in concrete terms?
+- Which conditions, if all true simultaneously, would produce the best outcome?
+- What capabilities or value would be unlocked that currently seem out of reach?
+- How quickly could the ideal state be achieved?
+
+**Example (software system):** All services scale elastically with zero downtime, the team ships on the roadmap schedule, adoption exceeds projections by 2×, and no security incidents occur in year one.
+
+---
+
+## Dimension 2: Worst Case
+
+**Description:** Every assumption fails, every risk materializes, and every external factor is adversarial. The floor — not likely, but possible.
+
+**Questions to ask:**
+- What is the single most catastrophic outcome?
+- Which combination of failures would be unrecoverable?
+- What would force a full shutdown or pivot?
+- Which dependencies, if lost, would collapse the entire system?
+
+**Example (software system):** A zero-day exploit exposes all user data, the primary cloud provider suffers a week-long outage, and the lead engineer leaves mid-sprint — simultaneously. The product is taken offline for 14 days.
+
+---
+
+## Dimension 3: Most Likely
+
+**Description:** The realistic base case given current knowledge, trends, and historical analogues. Not optimistic, not pessimistic.
+
+**Questions to ask:**
+- What does "normal" execution actually look like?
+- Which risks are almost certain to materialize in some form?
+- Where do timelines typically slip in comparable projects?
+- What does the median outcome look like at the 6-month and 1-year mark?
+
+**Example (software system):** Launch is 3 weeks late, one major feature is deferred to v1.1, initial adoption is 60% of projections, and one P1 bug requires a hotfix within the first two weeks.
+
+---
+
+## Dimension 4: Edge Case
+
+**Description:** Boundary conditions and rare-but-valid inputs that reveal hidden assumptions in the design. Not failure — just behavior at the limits.
+
+**Questions to ask:**
+- What happens at the extreme ends of the input range (0, max, negative, empty)?
+- Which user behaviors violate implicit assumptions in the design?
+- What race conditions or concurrency issues emerge under boundary conditions?
+- What breaks when two normally-separate components interact at the same moment?
+
+**Example (software system):** A user submits a form with a 10,000-character name. An API is called with an empty array. Two users edit the same record within the same millisecond. The system receives requests at exactly midnight UTC during a time-zone rollover.
+
+---
+
+## Dimension 5: Cascade Failure
+
+**Description:** A single failure triggers a chain of dependent failures, producing an outage larger than any individual component could cause alone.
+
+**Questions to ask:**
+- Which single component failure would propagate furthest?
+- Where are the shared dependencies that multiple systems rely on?
+- Which retry/backoff configurations could amplify load under failure?
+- What is the critical path through the system, and what happens if it breaks?
+
+**Example (software system):** The authentication service becomes slow (not down). Every other service starts waiting for auth tokens. Queues fill. CPU spikes. The database connection pool exhausts. The entire system becomes unavailable even though auth itself never fully died.
+
+---
+
+## Dimension 6: Adversarial
+
+**Description:** A motivated, intelligent actor actively tries to break, exploit, manipulate, or abuse the system. Not random failure — intentional attack.
+
+**Questions to ask:**
+- What is the highest-value target in this system for an attacker?
+- Which trust boundaries can be violated with the least effort?
+- What social engineering vectors exist against users or operators?
+- If you were the attacker, where would you start?
+
+**Example (software system):** An attacker crafts a request that bypasses input validation, injects SQL into a log aggregation pipeline, and uses the resulting data access to exfiltrate user PII — exploiting a component that was never considered part of the attack surface.
+
+---
+
+## Dimension 7: Time-Compressed
+
+**Description:** Normal timelines are radically shortened by external pressure (regulatory deadline, competitor launch, incident response). Quality-vs-speed tradeoffs become acute.
+
+**Questions to ask:**
+- If the timeline were cut in half, what would be cut and what are the consequences?
+- Which shortcuts taken under time pressure create long-term technical debt?
+- What safety checks would be bypassed under extreme deadline pressure?
+- How does team performance degrade under sustained crunch?
+
+**Example (software system):** The product must ship in 2 weeks instead of 8. Code review is eliminated, automated tests are skipped for "non-critical" paths, and the security audit is deferred. Six months later, three of those "non-critical" paths have production bugs.
+
+---
+
+## Dimension 8: Resource-Constrained
+
+**Description:** Key resources — budget, compute, people, time, bandwidth — are cut by 50–90%. What survives? What breaks? What gets creative?
+
+**Questions to ask:**
+- Which features require full resources vs. working with minimal resources?
+- What degrades gracefully and what collapses under resource reduction?
+- Which resource is the true bottleneck, and what happens if it disappears entirely?
+- How does the system behave when operating at 10% of expected capacity?
+
+**Example (software system):** Cloud budget is cut 70% mid-quarter. The team must reduce compute by shutting down staging environments, consolidating microservices, and disabling background jobs — discovering that two "separate" services are actually tightly coupled and cannot be co-located.
+
+---
+
+## Dimension 9: Stakeholder Conflict
+
+**Description:** Different stakeholders (users, operators, management, regulators, investors) have mutually incompatible goals, and the system or project must navigate the conflict.
+
+**Questions to ask:**
+- Which stakeholders have opposing success criteria?
+- Where does optimizing for one group actively harm another?
+- What happens when two stakeholders escalate their conflict to a decision-maker?
+- Which unspoken political dynamics could derail the project?
+
+**Example (software system):** The security team requires all data to be encrypted at rest, which adds 40ms latency. The product team's SLA requires <100ms response time. Engineering is caught between two mandates with no budget to resolve both. The conflict stalls the roadmap for 6 weeks.
+
+---
+
+## Dimension 10: Regulatory/Compliance
+
+**Description:** Existing or new rules, standards, or enforcement actions constrain what the system can do, how data must be handled, or where it can operate.
+
+**Questions to ask:**
+- Which regulations currently apply, and how strictly are they enforced?
+- What new regulations are likely in the next 1–3 years in this domain?
+- What would a compliance audit find if conducted today?
+- Which features would need to be removed or redesigned for a different jurisdiction?
+
+**Example (software system):** GDPR enforcement ramps up. The system's logging infrastructure has been retaining full request bodies (including PII) for 90 days. The team must implement retroactive data minimization and a right-to-deletion pipeline under a 30-day regulatory deadline.
+
+---
+
+## Dimension 11: Long-Term Drift
+
+**Description:** Gradual degradation over 1–5 years as the system ages, the team turns over, dependencies decay, and the original design assumptions become obsolete.
+
+**Questions to ask:**
+- What will be unmaintainable 2 years from now if no action is taken?
+- Which tribal knowledge, if lost with team turnover, would create critical gaps?
+- Which external dependencies are likely to be deprecated or abandoned?
+- How does accumulated technical debt compound, and what triggers a reckoning?
+
+**Example (software system):** Three years after launch, the original architect has left. Two key libraries are unmaintained. The test suite is 60% flaky so most developers skip it. A major Node.js version upgrade is required, but no one fully understands the build pipeline. Routine changes take 3× longer than in year one.
+
+---
+
+## Dimension 12: Recovery/Resilience
+
+**Description:** After a failure (any kind), how does the system return to normal? How fast, how completely, and with what residual damage?
+
+**Questions to ask:**
+- What is the recovery time objective (RTO) and is the system actually designed to meet it?
+- Which failure modes have no documented recovery procedure?
+- How is data integrity verified after recovery?
+- What lessons from a recovery event are actually captured and acted on?
+
+**Example (software system):** After a database corruption event, the team discovers that the most recent valid backup is 18 hours old (backups were silently failing for a week). Recovery takes 14 hours, and 12 hours of user data is permanently lost. The incident reveals no runbook existed for this failure mode.