okstra 0.34.1 → 0.36.1

package/runtime/templates/okstra.CLAUDE.md

@@ -0,0 +1,104 @@
+# okstra — agent guidance (managed)
+
+This file is shipped by `okstra install` and surfaced into the active project
+through two channels by `okstra setup`:
+
+- **Claude Code**: `<PROJECT>/CLAUDE.md` gets an `@.project-docs/okstra/CLAUDE.md`
+  import block (per-project symlink to this template). Existing user content
+  in `CLAUDE.md` is preserved — the block lives between
+  `<!-- okstra:claude-md:begin ... -->` markers.
+- **Codex / Aider / other AGENTS.md-aware agents**: `<PROJECT>/AGENTS.md` is
+  created as a direct symlink to this template — but **only if AGENTS.md does
+  not already exist**. okstra never overwrites a hand-written AGENTS.md.
+
+It is **owned by the okstra package**: every `okstra install` overwrites
+`~/.okstra/templates/okstra.CLAUDE.md` from the version currently on disk in
+the npm package. Edits made directly to this file (or to the per-project
+`<PROJECT>/.project-docs/okstra/CLAUDE.md` / `<PROJECT>/AGENTS.md` symlinks)
+will be lost on the next install. Put project-specific overrides outside the
+managed block in `<PROJECT>/CLAUDE.md` instead (or replace `AGENTS.md` with
+your own file — okstra will respect it).
+
+## What okstra is
+
+okstra is a multi-agent cross-verification orchestrator. A Claude lead drives
+the run; codex / gemini / claude workers produce independent analyses; a
+report writer worker synthesises the final report. Day-to-day usage happens
+through slash commands inside a Claude Code session.
+
+## Slash commands
+
+| Command | When to use |
+| --- | --- |
+| `/okstra-setup` | First-time bootstrap in a new project — writes `.project-docs/okstra/project.json`, provisions `.claude/settings.local.json` and `.project-docs/okstra/CLAUDE.md`. |
+| `/okstra-brief` | Turn a requirements doc / ticket / link / conversation into the markdown task brief consumed by `okstra-run`. |
+| `/okstra-run` | Start a cross-verification task in the current session. Drives the interactive wizard. |
+| `/okstra-status` | Inspect overall okstra task status, current phase, blockers, next recommended phase. Also flips a task's workStatus (todo / in-progress / blocked / done). |
+| `/okstra-history` | List past runs, review previous results, queue a re-run. |
+| `/okstra-schedule` | Generate a consolidated work plan across multiple tasks in a task-group. |
+| `/okstra-convergence` | Iterative cross-verification between workers in Phase 5.5; classify findings by consensus level. |
+| `/okstra-report-finder` | Locate the final-report path for a given task key, or read a past report to continue work. |
+| `/okstra-report-writer` | Author / persist the final synthesis report (Phase 6–7). |
+| `/okstra-time-summary` | Per-task / per-worker elapsed time breakdown for a task-id. |
+| `/okstra-logs` | List, size, and clean up `*.log` sidecars from past worker dispatches. |
+
+Type the slash command — do not paraphrase the trigger words into prose.
+
+## Workflow boundaries
+
+- The Claude lead **does not** produce independent worker findings. It
+  dispatches workers, monitors them, and drives convergence. Analysis is the
+  workers' job.
+- Worker wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) run from
+  `~/.okstra/bin/` and are pre-authorised via `<PROJECT>/.claude/settings.local.json`
+  (a symlink to `~/.okstra/templates/settings.local.json`). Do **not**
+  duplicate those permissions in the user's global `~/.claude/settings.json`.
+- Each okstra run provisions a task-scoped git worktree under
+  `~/.okstra/worktrees/`. Files synced from the main checkout are governed by
+  `worktreeSyncDirs` in `.project-docs/okstra/project.json` (default:
+  `.project-docs`, `.scratch`, `graphify-out`, `.claude`).
+- QA gating is configured via `qaCommands` in the same `project.json`.
+  Verifiers reject mutation-style commands (`--fix`, `--write`, `cargo update`,
+  `npm install`, etc.); declare check-only variants only.
+
+## Coding Principles (BLOCKING — agent self-checks before declaring work complete)
+
+These apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
+
+1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
+2. **KISS — simplest sufficient design** — Add abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when an existing concrete call site requires them. *Self-check: name the second caller now; if you cannot, inline.* *Example violation: extracting `formatUserName()` helper used by exactly one call site, "in case we need it elsewhere".*
+3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier has ≥1 current internal caller, or was explicitly user-requested.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
+4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; if a comment would describe WHAT the code does, rename instead. Reserve comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
+5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
+
+## Phase model (high level)
+
+```
+Phase 1  context-loader          → load brief + project context
+Phase 2  team-contract           → confirm lead + worker roster
+Phase 3  worker dispatch         → workers run independently in parallel
+Phase 4  result collection       → gather worker outputs
+Phase 5  cross-review            → workers critique each other's findings
+Phase 5.5 convergence            → classify findings, iterate until stable
+Phase 6  report-writer dispatch  → synthesise final report
+Phase 7  artifact persistence    → manifests, central index update
+```
+
+The lead skill (`okstra-run`) advances phases automatically. Use
+`/okstra-status` to inspect the current phase and `next-recommended-phase`
+hint when resuming.
+
+## Troubleshooting hints
+
+- "okstra runtime missing" / `InstallationError` — run
+  `npx okstra@latest install` (or `okstra ensure-installed`).
+- Worker dispatch refused by Claude Code permissions — verify
+  `<PROJECT>/.claude/settings.local.json` is a symlink to
+  `~/.okstra/templates/settings.local.json`; re-run `/okstra-setup` to
+  re-provision.
+- `qa-command not configured: <category>` warnings — add the missing
+  `lint` / `format` / `typecheck` / `test` entries to `qaCommands` in
+  `project.json`.
+
+For deeper documentation see the package README and `docs/` in the okstra
+source tree.

package/runtime/templates/reports/brief.template.md

@@ -0,0 +1,204 @@
+---
+type: brief
+brief-id: <ticket-id>-<file-title>          # equals the filename stem
+parent-id: self                              # always `self` at root; child briefs use parent's brief-id
+ticket-id: <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12 | "">
+source-type: <file | linear | jira | github | notion | url | user-input>
+task-group: <task-group>
+depth: 0                                     # 0=parent/single, 1=child, 2=grandchild, ...
+created: <YYYY-MM-DD>
+generator: okstra-brief
+reporter-confirmations: <complete | partial | pending | skipped>  # set by Step 6.5
+# codebase-scan variant frontmatter (omit for reporter-input briefs):
+scope: <reporter-input | codebase>              # 'codebase' for codebase-scan variant; omit for reporter-input variant
+priority-lenses: []                              # codebase-scan only: lens enum subset, size 1..4
+scan-scope: []                                   # codebase-scan only: 1+ paths
+out-of-scope: []                                 # codebase-scan only: optional
+candidate-cap: 8                                 # codebase-scan only: 1..12, default 8
+---
+
+# Task Brief: <task_group>/<filename-without-ext>
+
+> Generated: okstra-brief · <YYYY-MM-DD>
+> Source type: <file | linear | jira | github | notion | url | user-input>
+> Tracker key (if any): <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12>
+> Parent brief (child briefs only): <relative path>
+> Recommended next phase: <requirements-discovery | error-analysis>  ← from Step 6
+> Handoff contract: see `prompts/profiles/_common-contract.md` § "Brief handoff contract"
+
+## Source Material
+
+<!-- author guidance — strip out at fill-in time:
+Paste each source separately and as-is. No paraphrasing, summarizing, or
+restructuring. Format conversion (e.g. Jira ADF → Markdown) is allowed and
+must be annotated in the header meta. Heading was originally
+"Source Material (verbatim — do not modify)" — the parenthetical is a
+reviewer note, not body text.
+-->
+
+### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
+
+- ref: <abs file path | LIN-1234 | https://... | "conversation synthesis">
+- fetched-via: <Read | mcp__linear__getIssue | mcp__notion__... | gh issue view | WebFetch | user-paste>
+- fetched-at: <YYYY-MM-DD HH:MM>
+- format: <as-is | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
+
+```
+<Paste the raw source here without changing a single character.>
+```
+
+<!-- Repeat `### Source N — …` blocks as needed. -->
+
+## Context
+
+<Background / scope / why now. If self-evident from Source Material, quote
+it briefly and stop. Use the blockquote below when augmentation is needed.>
+
+> augmented: <label> — <Interpretation added by the skill or user.>
+
+<!-- label MUST be one of: `evidence-link` / `format-conversion` /
+`terminology-mapping` / `intent-inference`. Do NOT add any extra
+interpretation outside the `> augmented:` blockquote. -->
+
+## Problem / Symptom
+
+<Current state. For bugs: repro / observed / expected. For greenfield: gap
+between current and desired.>
+
+<!-- Same source-quote + `> augmented:` rule as the Context section. -->
+
+## Desired Outcome
+
+<Shape of success.>
+
+<!-- Do NOT prescribe a solution — that belongs to implementation-planning. -->
+
+## Constraints
+
+<Deadlines, compatibility, technical/operational limits. Use _(none)_ if
+none.>
+
+## Scan Scope
+
+<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
+<!-- Author guidance: one bullet per `scan-scope` path with a short description of what lives there. -->
+
+- <path>: <one-line description of contents / responsibility>
+
+## Priority Lenses
+
+<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
+<!-- Author guidance: one bullet per priority lens explaining why it is a priority for THIS scope. -->
+
+- <lens>: <short rationale tying this lens to the scope's risk surface>
+
+## Related Artifacts
+
+- <file path / URL / issue / prior task-key>
+
+## Open Questions
+
+<!-- author guidance — strip out at fill-in time:
+Prefix every row with one of these signals so the next phase knows how to
+handle it. Free-form rows are allowed only as `general:`.
+
+Allowed signals:
+- `general: <unresolved question the user flagged>`
+- `terminology: <reporter word> — needs canonical resolution against
+  <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
+- `intent-check: <restated inference> — confirm with reporter`
+  (auto-paired with every `intent-inference` augmentation)
+- `conversion-block: <reporter statement> — could not be mapped to project
+  vocabulary; reporter query required`
+- `adr-candidate: <topic>` — signal only; `implementation-planning`
+  evaluates and, if accepted, drafts a decision file at
+  `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
+
+Use `_(none)_` only if every signal is empty. `intent-check:` and
+`conversion-block:` rows that are answered in Step 6.5 are NOT removed
+from this list — they receive a `[CONFIRMED <YYYY-MM-DD> → RC-N]`
+marker that links to the corresponding entry under
+`## Reporter Confirmations`.
+-->
+
+- <fill in one row per signal, or replace with `_(none)_`>
+
+## Reporter Confirmations
+
+<!-- Populated by Step 6.5. Each subsection records one reporter answer
+verbatim, with a link back to the originating `Open Questions` row. -->
+
+_(none — pending or skipped)_
+
+<!-- when populated, the shape is:
+### RC-1 — <intent-check: or conversion-block: row id / topic>
+- asked: <YYYY-MM-DD HH:MM>
+- linked-row: `<exact Open Questions row text>`
+- answer (verbatim):
+
+  > <reporter's answer, byte-for-byte>
+-->
+
+## Augmentation
+
+<!-- author guidance — strip out at fill-in time:
+Cross-references / interpretation / context added by the user or skill that
+is not in the original source. May be empty. Keep this section visually
+separated from Source Material — never inline it inside Source Material.
+
+Every entry below must start with one of the four labels:
+`evidence-link` / `format-conversion` / `terminology-mapping` /
+`intent-inference`. Unlabelled entries are forbidden.
+-->
+
+### Domain alignment
+
+<!-- author guidance — strip out at fill-in time:
+Observations from Step 3b and the outcome of Step 4.5 (glossary applied
+vs. skipped). The actual glossary edits live in
+`<PROJECT_ROOT>/.project-docs/okstra/glossary.md` when applied; this
+section records what happened. Decision candidates are NOT recorded here —
+they flow through `Open Questions` as `adr-candidate:` rows for
+`implementation-planning` to evaluate (and, if accepted, draft into
+`<PROJECT_ROOT>/.project-docs/okstra/decisions/`).
+
+Allowed entry shapes:
+- `terminology-mapping: <reporter word> → <okstra glossary canonical>` —
+  routine glossary alignment, paired with `terminology:` in Open Questions
+  when unresolved.
+- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
+- `terminology-mapping: skipped glossary: <term> = <definition>` —
+  Step 4.5 outcomes.
+Use `_(none)_` if every alignment entry is empty.
+-->
+
+- <fill in one entry per alignment, or replace with `_(none)_`>
+
+### Evidence links (file / symbol resolution)
+
+<!-- Allowed entry shapes:
+`evidence-link: <reporter phrase> → <relative path>:<line>` or
+`evidence-link: <reporter phrase> → <symbol> in <relative path>`.
+Use `_(none)_` if none. -->
+
+- <fill in one entry per link, or replace with `_(none)_`>
+
+### Intent inferences
+
+<!-- Every entry here is an unverified hypothesis. Each one MUST have a
+paired `intent-check:` row under Open Questions.
+
+Allowed entry shape:
+`intent-inference: <reporter phrase> → <qualitative restatement>`
+(qualitative only — never invent numeric thresholds).
+Use `_(none)_` if none. -->
+
+- <fill in one entry per inference, or replace with `_(none)_`>
+
+### Format conversions
+
+<!-- Allowed entry shape:
+`format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`.
+Use `_(none)_` if none. -->
+
+- <fill in one entry per conversion, or replace with `_(none)_`>