@azure-id/orc 0.55.0

package/templates/skills/context-combiner/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: context-combiner
+description: >
+  Combines 2+ RELATED, already-confirmed ORC analyses (from orc-analyze) into
+  ONE merged, deduped, conflict-resolved requirement context before build. Use
+  when the user analyzed multiple related documents within the same scope and
+  chose "pass to context-combiner" at orc-analyze's Phase F. Verifies the source
+  analyses actually overlap (shared files/requirements/scope) and challenges the
+  user if they look unrelated; pools ALL source requirements into one table and
+  reconciles them (exact/semantic duplicates, partial overlaps split — never
+  collapsed, conflicts, ordering) one issue at a time; proves NOTHING WAS LOST
+  via a source coverage matrix and a 100% coverage gate before handoff;
+  spot-checks inherited evidence and marks stale anchors; writes
+  combined-report.md + combined-requirement-spec.md (the merged spec reuses the
+  requirement-spec schema, so the planner/build pipeline is unchanged). Full
+  lane only (Opus 5 high). The orchestrator DISPATCHES this to a subagent —
+  it never combines itself, and the combiner never builds or spawns subagents.
+---
+
+# CONTEXT-COMBINER
+
+The orchestrator stays on top and **dispatches a Context Combiner subagent
+(orc-context-combiner-opus-5-high)** with a list of 2+ confirmed analysis
+spec paths. It never combines itself. The combiner merges related, ALREADY
+code-grounded analyses — it does not re-analyze the repo from scratch.
+
+Purpose: turn 2+ related, confirmed requirement-specs (same user scope) into ONE
+merged, deduped, conflict-resolved requirement set a planner can build from as if
+it were a single analysis — with PROOF that no source requirement was lost.
+
+## Hard rules
+
+1. **Dispatched, not self-run.** The orchestrator coordinates; the Combiner
+   subagent (Opus 5 high) reads the specs and reconciles them against each
+   other. The combiner NEVER builds and NEVER spawns subagents.
+2. **Related only — verify + challenge.** The user asserted relatedness at the
+   Phase F gate, but the combiner MUST verify real overlap (shared files,
+   overlapping requirements, shared scope). If overlap is weak/empty, it
+   challenges: "combine anyway / keep separate" — and records the decision.
+3. **Trust confirmed sources — but spot-check freshness.** Source specs are
+   already code-grounded with evidence. The combiner INHERITS their `file:line`
+   evidence — it does not re-derive the code. It only reconciles the specs
+   against EACH OTHER, plus ONE bounded freshness pass: for each inherited
+   anchor, confirm the file still exists and the line still plausibly matches
+   (Read just that region — never a re-analysis). A failed check marks the row's
+   evidence `STALE` — never silently carried. STALE evidence on a buildable
+   requirement becomes a Phase D challenge (re-anchor / proceed anyway / drop).
+   Record the repo state checked against as `combined_against` (git HEAD short
+   sha) in both artifacts.
+4. **Resolve conflicts one at a time.** Every cross-source conflict, duplicate,
+   and ordering dependency is raised as a 2–3 option challenge with ONE
+   **recommended** option + a one-line reason. Wait, record, continue. Never
+   batch. Keep asking until the combined context is clear (no open conflict).
+5. **Conservation — nothing is lost, and you must prove it.** Every source
+   requirement ID gets EXACTLY ONE outcome in the Source coverage matrix
+   (merged / deduped-into / split-across / conflict-resolved / dropped).
+   `dropped` is legal ONLY with a recorded user decision from a Phase D
+   challenge. **When in doubt, keep both rows** — a redundant requirement costs
+   the planner a dedupe; a lost one costs the build a feature. The conservation
+   gate (Phase E) blocks artifact handoff until `coverage_pct` is 100.
+6. **Two artifacts, spec derived from report.** `combined-report.md` (human,
+   source of truth) and `combined-requirement-spec.md` DERIVED from it (schemas/).
+7. **Never build on unresolved.** If a conflict is left unresolved, record it as
+   an open question and refuse handoff to build until it is resolved.
+8. **Checkpoint decisions eagerly.** Every challenge verdict is appended to
+   `combine-decisions.md` in the internal folder THE MOMENT it is given
+   (question, options, choice, timestamp). On resume/compaction, replay that
+   file and continue from the first unanswered item — never re-ask a recorded
+   decision, never lose one.
+9. Usage: report handoff + remind the user to run `/usage`. Never invoke it.
+10. **Never open a run of your own.** The combiner has no slash command; it is
+    always dispatched from `orc-analyze` Phase F while that run's trace is still
+    open. So: do NOT write `log_dir/.current`, do NOT create a trace file, do
+    NOT emit `FINISH`. Your `DISPATCH`/`RETURN`, every Phase D verdict and the
+    Phase E conservation result belong to the **dispatching lane's** end-of-run
+    packet — the hook segments your work as its own `PHASE-EDGE` family
+    (`combine`) inside that same file. Bootstrapping here would split the
+    analyze run across two files and invent a lane nothing can open. See
+    `../orc/references/trace-protocol.md`.
+
+## Phase A — Load sources
+Read every source `requirement-spec.md` (2+) the orchestrator hands you, plus
+their reports. Confirm you have ≥2. Note each source's scope, mode, depth.
+Record `combined_against` = current git HEAD short sha.
+**Scale guard:** if sources > 4, warn that merge quality and token cost degrade
+and offer staged combining (combine the two most related first, then fold in
+the next against the combined result). Record the choice in
+`combine-decisions.md`.
+
+## Phase B — Verify relatedness
+Compute overlap across sources:
+- shared `files[]` between specs,
+- overlapping/duplicate requirement statements,
+- shared scope string.
+If overlap is strong → proceed. If weak/empty → CHALLENGE (recommended-option):
+"These share {N} files / no overlapping requirements — combine anyway
+(recommended only if you're sure) or keep separate?" Record the verdict in the
+report's Relatedness check. If the user chooses **keep separate**, STOP the run:
+do NOT proceed to Phase C or write any `combined-*` artifact — return to the
+orchestrator with `combined: false` (the analyses stay separate; the orchestrator
+falls back to per-analysis stop/build).
+
+## Phase C — Pool, then reconcile
+
+**C.0 — Pool first, never pairwise.** Normalize ALL source requirements into ONE
+pooled table (`source_id` e.g. A.R1, statement, files, evidence, depth of its
+source). Then cluster pooled rows by shared files/behavior and detect issues
+WITHIN clusters. This scales to N sources — pairwise comparison misses
+three-way interactions and is forbidden.
+
+**C.1 — Classify every cluster:**
+- **EXACT-DUPLICATE** — same requirement, same wording → merge into one row,
+  tracking `from: [A.Rx, B.Ry]`.
+- **SEMANTIC-DUPLICATE** — same effect, different wording → merge, but QUOTE
+  both original statements in the report so intent nuance isn't erased. If the
+  equivalence is not obvious, it's a Phase D challenge, not a silent merge.
+- **PARTIAL-OVERLAP** — one requirement subsumes or intersects another →
+  **SPLIT into a shared row + residue row(s)**; never collapse. Residue rows
+  keep their own `from[]` and evidence. Ambiguous splits are Phase D challenges.
+- **CONFLICT** — source A and source B require contradictory things on the same
+  file/behavior.
+- **ORDERING** — one source depends on another's change existing first. Record
+  as structured pairs (`before` / `after` merged IDs), not free text.
+
+**C.2 — Reconcile beyond requirements.** Cross-check `assumptions_resolved` and
+`alternatives` across sources too: contradictory resolved assumptions are a
+CONFLICT (Phase D); alternatives anchored to a merged/split requirement are
+re-pointed at the merged ID.
+
+**C.3 — Evidence freshness spot-check** (per Hard rule 3): verify each inherited
+anchor still exists; mark failures `STALE`.
+
+Anything ambiguous becomes a Phase D challenge.
+
+## Phase D — Challenge (interactive, recommended options, one at a time)
+For every CONFLICT / ambiguous DUPLICATE or PARTIAL-OVERLAP split / ORDERING
+decision / STALE-evidence-on-buildable / proposed drop, ask a single focused
+2–3 option question with ONE **recommended** option + a one-line reason. Wait,
+record, continue. Never batch. Append every verdict to `combine-decisions.md`
+immediately (Hard rule 8). Keep going until nothing is unresolved.
+
+## Phase E — Conservation gate (before any artifact is written)
+Build the **Source coverage matrix**: one row per source requirement ID with
+exactly one Outcome — `merged → #N` / `deduped-into → #N` / `split-across →
+#N,#M` / `conflict-resolved → #N` / `dropped (user decision ref)`. Then check:
+- every source ID appears exactly once (no unaccounted IDs, no double-counting),
+- the union of `from[]` across merged rows equals the non-dropped source set,
+- every `dropped` row cites a recorded decision in `combine-decisions.md`.
+`coverage_pct` = accounted source IDs / total source IDs × 100. If it is not
+100 → fix the merge (or raise the missing challenge), do NOT proceed.
+`handoff_ready` = (`coverage_pct` == 100) AND (no open conflict).
+
+## Phase F — Write combined artifacts
+1. Write `combined-report.md` (schemas/combined-report.md) into
+   `.claude/skills/orc/analyzer/combined-{name}/` (internal): Relatedness check,
+   Merged requirements (deduped, ordered, evidence inherited, STALE flagged,
+   `depth_from` when sources differ in depth), **Source coverage matrix**
+   (Phase E), **Additional context (do not build)** merged from the sources
+   (anchors re-pointed at the merged requirement; dedupe ONLY when the evidence
+   anchor is the same `file:line` AND the notes convey the same constraint —
+   otherwise keep both; non-actionable, omit if none), Cross-scope conflicts &
+   decisions, Open questions, Handoff readiness.
+2. Derive `combined-requirement-spec.md` (schemas/combined-requirement-spec.md)
+   FROM the confirmed combined report, in the same internal folder. Reuse the
+   base requirement-spec shape + `combined_from`, `cross_scope`, and the
+   `coverage` block.
+
+## Phase G — Return & branch
+Return to the orchestrator: `combined_report_path`, `combined_spec_path`,
+`combined_from[]`, `conflicts_resolved[]`, `coverage_pct`, `dropped[]`
+(source IDs dropped by user decision), `stale_evidence[]` (rows flagged STALE),
+`handoff_ready: bool` (open/unresolved items are NOT a return field — they live
+in the report's Open questions section, reachable via `combined_report_path`).
+The orchestrator then offers the user (plain language):
+- **Stop here** → COPY `combined-report.md` OUT to `{report_out_dir}/combined-{name}/`
+  and stop.
+- **Pass to orc build** → hand `combined-requirement-spec.md` back to the
+  orchestrator, which continues at Phase 1 (Requirement Planner) and runs the
+  full pipeline. The combiner NEVER builds directly.
+
+**Gate the build option on `handoff_ready`:** if `handoff_ready` is false (an
+unresolved conflict remains per Hard rule 7, or `coverage_pct` < 100 per Hard
+rule 5), the orchestrator offers ONLY **Stop here** — the build option is
+withheld until the open conflict is resolved and coverage is complete.
+
+## No mini variant
+Full lane only. `orc-analyze-mini` / `orc-mini` do not use the combiner.

package/templates/skills/context-combiner/schemas/combined-report.md

@@ -0,0 +1,78 @@
+# Template — Combined Analysis Report
+
+Human-readable source of truth for a MERGE of 2+ related analyses. Written to
+orc/analyzer/combined-{name}/combined-report.md. Copied OUT to
+{report_out_dir}/combined-{name}/ on "stop here".
+
+```markdown
+# Combined Analysis Report — {combined-name}
+kind: combined
+combined_from: [analysis-A, analysis-B, ...]   # source analysis names
+scope: <the shared scope X these analyses live in>
+combined_at: DDMMYY HH:MM:SS
+combined_against: <git HEAD short sha the evidence spot-check ran against>
+model: opus-5-high        # the RESOLVED model of the combiner that produced
+                          #   this — never copied from here
+
+## Relatedness check
+How the source analyses overlap — shared files, overlapping requirements,
+shared scope. If overlap was weak, the user was challenged and their decision
+is recorded here.
+- Shared files: web/reports/x (analysis-A R1, analysis-B R2)
+- Overlapping requirement: both add export to the reports module
+- Verdict: related (confirmed) | combined-anyway (user override) | ...
+
+## Merged requirements (deduped, ordered)
+Every row carries file:line evidence inherited from the source spec (the
+combiner trusts confirmed specs; it does not re-derive the code) — spot-checked
+against `combined_against`; anchors that no longer match are marked STALE and
+were challenged, never silently carried. SEMANTIC-DUPLICATE merges quote both
+original statements. PARTIAL-OVERLAP rows are split (shared + residue), never
+collapsed. `Depth` is shown when sources differ in depth.
+
+| # | Requirement (merged) | From | Depth | Code reality | Evidence (file:line) | Files/modules | Status |
+|---|----------------------|------|-------|--------------|----------------------|---------------|--------|
+| 1 | "add CSV export"     | A.R1 | deep | HTML only    | web/reports/view.x:30 | web/reports/x | buildable |
+| 2 | "reuse report auth"  | A.R2, B.R3 (dedup) | standard | guard present | web/reports/routes.x:12 (STALE — user chose proceed) | web/reports/x | exists |
+
+## Source coverage matrix (conservation proof)
+EVERY source requirement ID appears exactly once with exactly one Outcome.
+`dropped` requires a recorded user decision in combine-decisions.md. The gate
+below must show coverage_pct: 100 before this report can hand off to build.
+
+| Source ID | Outcome | Merged as | Decision ref |
+|-----------|---------|-----------|--------------|
+| A.R1 | merged | #1 | — |
+| A.R2 | deduped-into | #2 | — |
+| B.R2 | conflict-resolved | #3 | combine-decisions.md #2 |
+| B.R3 | deduped-into | #2 | — |
+| B.R4 | dropped | — | combine-decisions.md #4 (user: superseded by A.R1) |
+
+- source requirements total: {N} · accounted: {N} · coverage_pct: 100
+
+## Additional context (do not build)
+Anchored, non-actionable context merged from the sources — each item re-pointed at
+the merged requirement it serves. Dedupe ONLY when the evidence anchor is the same
+file:line AND the notes convey the same constraint — near-identical notes are kept,
+both, with their own From tags. Read for understanding; never a task. Omit this
+whole section if no source carried context.
+| Anchor (merged #) | From | From scope | Dependency | Touchpoint to respect | Evidence (file:line) |
+|-------------------|------|-----------|------------|-----------------------|----------------------|
+| 1 (CSV export) | A.ctx | reporting (Y) | consumes-output | report query already paginates; export must page too | web/reports/query.x:44 |
+
+## Cross-scope conflicts & decisions
+Every conflict/duplicate/partial-overlap/ordering issue found across sources
+(including contradictory resolved assumptions), each raised as a
+recommended-option challenge and resolved. Decisions are also checkpointed
+eagerly in combine-decisions.md.
+- CONFLICT (resolved): A.R4 wants offset paging, B.R2 wants cursor — user chose cursor.
+- DUPLICATE (merged): A.R2 and B.R3 both reuse auth — merged into #2.
+- PARTIAL-OVERLAP (split): A.R5 subsumes B.R1 — shared row #4, A-only residue row #5.
+- ORDERING (structured): before: #1 (A export) → after: #6 (B schedule).
+
+## Open questions (block handoff until resolved)
+- (none) | UNRESOLVED: ... — combiner refuses build handoff while any remain.
+
+## Handoff readiness
+- complete: yes/no   (coverage_pct == 100, all conflicts resolved, no open UNRESOLVED)
+```

package/templates/skills/context-combiner/schemas/combined-requirement-spec.md

@@ -0,0 +1,87 @@
+# Schema — Combined Requirement Spec (DERIVED from combined-report.md)
+
+Machine projection of combined-report.md. A STRICT SUPERSET of the base
+requirement-spec schema — every base field is present (so the planner consumes it
+UNCHANGED, exactly like a single requirement-spec.md) — plus combine-only
+additions: `combined_from`, `combined_against`, `cross_scope`, `coverage`,
+`kind`, and `requirements[].from` / `requirements[].depth_from`.
+Written to orc/analyzer/combined-{name}/combined-requirement-spec.md.
+
+```yaml
+analysis_name: string           # combined-{name}
+kind: combined                  # ADDED: marks this as a merge (vs a single analysis)
+combined_from: [string]         # ADDED: source analysis names, e.g. [analysis-A, analysis-B]
+combined_against: string        # ADDED: git HEAD short sha the evidence spot-check ran against
+mode: audit | prose | requirement | mixed   # base enum + 'mixed' when sources differ
+depth: standard | deep | mixed              # base enum + 'mixed' when sources differ
+source_doc: string | null       # base field: null for combined (sources are in combined_from)
+scope: string                   # base field: the shared scope X
+grounding: repo-read | repo-read+scouts | from-system-analyst | from-source-specs
+                                # base enum + 'from-source-specs'; combined always uses the latter
+derived_from: combined-report.md
+created_at: timestamp
+
+requirements:                   # base field, merged/deduped/ordered — base item shape + 'from'
+  - id: R1
+    statement: string
+    from: [string]              # ADDED: which source req(s) this came from, e.g. [A.R1]
+    depth_from: standard | deep # ADDED: depth of the dominant source (only when depth: mixed)
+    code_reality: string
+    evidence: [string]          # file:line inherited from source spec; STALE anchors are
+                                # suffixed " (STALE)" and carry a recorded user decision
+    files: [string]
+    status: exists | missing | conflict | verified | buildable | resolved
+    resolution: string|null
+
+assumptions_resolved:           # base field: merged from all sources (may be []).
+  - item: string                # Contradictory resolutions across sources were raised as
+    decision: string            # CONFLICT challenges and carry the reconciled decision.
+
+alternatives:                   # base field: merged from deep-mode sources ([] if none),
+  - for: R#                     # re-pointed at MERGED requirement ids
+    recommended: string
+    options: [string]
+    risk: string
+
+context:                        # base field: merged anchored, NON-ACTIONABLE context ([] if none)
+  - anchor: R#                  # remapped to the MERGED requirement id (still REQUIRED — no anchor, no entry)
+    from_scope: string
+    dependency: string          # consumes-output | guards-invariant | shares-file | doc-references
+    note: string
+    evidence: [string]
+# Same rule as the base spec: read-for-understanding, never a task. On merge,
+# dedupe ONLY same-file:line anchors carrying the same constraint; otherwise keep both.
+
+coverage:                       # ADDED: conservation proof (mirrors the report's coverage matrix)
+  source_requirements_total: int
+  merged_total: int
+  coverage_pct: 100             # MUST be 100 — the combiner refuses handoff below that
+  dropped:                      # source IDs excluded ONLY by recorded user decision
+    - id: string                # e.g. B.R4
+      decision: string
+  stale_evidence: [string]      # merged R ids whose inherited anchors failed the spot-check
+
+cross_scope:                    # ADDED: combine-only audit block
+  conflicts_resolved:
+    - between: [A.R4, B.R2]
+      decision: string
+  overlaps_merged:
+    - merged: [A.R2, B.R3]
+      into: R2
+      kind: exact | semantic    # semantic merges quote both statements in the report
+  overlaps_split:               # PARTIAL overlaps are split, never collapsed
+    - between: [A.R5, B.R1]
+      shared: R4
+      residue: [R5]
+  ordering:                     # structured — consumable as planner dependencies
+    - before: R1
+      after: R6
+
+# Everything here is confirmed. The planner does NOT re-question scope/accuracy;
+# it turns these into tasks (cross_scope.ordering rows are real sequencing
+# dependencies — respect them when waving). Because this is a strict superset of
+# the base spec, the planner reads it exactly like a single requirement-spec.md —
+# the added keys (kind, combined_from, combined_against, requirements[].from,
+# requirements[].depth_from, coverage, cross_scope) are additive and ignorable.
+scope_closed: true
+```

package/templates/skills/orc/README.md

@@ -0,0 +1,150 @@
+# ORC (installed payload)
+
+A Claude Code skill constellation: intake → planning → scored parallel
+execution → review → verify → ship. One orchestrator spine invoking focused
+subskills, with eager checkpointing that survives compaction, crashes, and
+fresh-session resumes.
+
+Stack-agnostic — detects and adapts to your project's language/tooling.
+
+> This README ships inside the installed payload. The full user docs (install,
+> commands, config, changelog) live in the `orc` npm package's root README:
+> https://github.com/azure-id/orc
+
+## Install / update
+
+Installed by the `orc` npm package — don't copy files by hand:
+
+```bash
+npm i -g github:azure-id/orc
+orc init            # install into ./.claude   (orc init --global for ~/.claude)
+orc update          # re-copy the installed package's files (offline)
+orc upgrade         # fetch the latest package, then apply it
+orc config          # view/change settings — zero model tokens
+```
+
+`orc init` installs **skills/**, **commands/** (`/orc` `/orc-mini` `/orc-fast`
+`/orc-analyze`
+`/orc-plan` `/orc-verify` `/orc-wiki` `/orc-pattern`), **agents/** (single-role,
+model-pinned subagents + `MODEL-MAPPING.md`), and **hooks/** (effort hard-block,
+statusline tier warning, behavior trace), merging the hook wiring
+non-destructively into `.claude/settings.json`.
+
+After installing:
+
+1. **Paste your PR template** into `orc/subskills/orc-pr/pr.md` (replaces the
+   placeholder).
+2. Add `.claude/orc/run/` to your project `.gitignore` (a local
+   .gitignore inside run/ is included, but confirm).
+3. Run `/agents` to confirm the model IDs your Claude Code accepts, and **run
+   your main session on Opus** — a subagent's model can't exceed the main
+   session's tier.
+
+## Use
+
+```
+use orc to build <feature>        # or /orc
+```
+
+It will: rough-size → ask tiered intake questions (2/4/6) → draft an intent-spec
+for your sign-off → plan (Superpowers/OpenSpec/Requirement Planner/self) →
+recommend sequential vs parallel dispatch (workers always spawned) → score every
+task (rubric → config preset → named executor agent) and show you the table →
+execute in conflict-free waves with batch pauses → at every stop: checkpoint,
+usage report, and a paste-block to resume in a FRESH session (recommended for
+long runs) → review → verify → optional security pass / test authoring →
+summary → commit/push/PR.
+
+## Layout (this skill)
+
+```
+orc/
+├── SKILL.md                     # thin orchestrator spine (progressive disclosure)
+├── config.md                    # shipped defaults + the single score→model table
+├── schemas/                     # orchestrator-owned; workers get slices
+│   ├── intent-spec.md
+│   ├── planning-output.md
+│   └── checkpoint.md            # + state-of-play format
+├── references/                  # loaded only when their phase fires
+│   ├── intake.md
+│   ├── effort-and-mode.md       # dispatch-style gate + scoring rubric
+│   ├── wave-grouping.md
+│   ├── log-protocol.md
+│   ├── stop-and-resume.md       # stop sequence, /usage, resume block
+│   ├── house-rules.md           # standing behavioral card, injected into every slice
+│   ├── security-checklist.md    # Phase 5.5 OWASP/STRIDE items (opt-in)
+│   └── trace-protocol.md        # behavior trace (PERMANENT — always on)
+├── subskills/
+│   ├── orc-execution/           # SKILL.md + core.md + subagent.md (always spawned)
+│   ├── orc-review-verify/       # review / verify / security modes (always spawned)
+│   ├── orc-planner/             # Requirement Planner (+ orc-planner-mini fast lane)
+│   ├── orc-testgen/             # opt-in Phase 6.5 test authoring
+│   ├── orc-checkpoint/          # stateless write/read service
+│   └── orc-pr/                  # SKILL.md + pr.md (YOUR template goes here)
+├── examples/full-run-mock.md
+└── run/                         # gitignored — all run artifacts live here
+```
+
+Sibling skills installed alongside: `orc-mini` (fast path), `orc-fast`
+(fastest lane — knowledge-gated on a fresh wiki + pattern cache, falls back to
+orc-mini), `orc-verify`
+(standalone git-diff verify), `orc-analyze` + `orc-analyze-mini` (System
+Analyst), `orc-wiki` (project knowledge base), `orc-pattern` (code-pattern
+codifier: 9 language playbooks + a11y/perf rule packs), `context-combiner`
+(merge related analyses).
+
+## Key behaviors to know
+
+- **The orchestrator NEVER implements — it always spawns scored subagents,
+  even for tiny tasks.** Orchestrator (Opus 4.8 high, or Opus 5 / Fable 5 at
+  medium+) only coordinates; each task's 0–100 score (computed arithmetically
+  from the planner's per-task `facets`) maps to a named executor agent via the
+  single 8-band table in `config.md` (`rubric_bands` = report granularity only),
+  Haiku 4.5 → Opus 4.8 high [80,90) → Opus 5 high [90,100].
+- **Every executor slice carries** the intent-spec constraints, the task's
+  sliced acceptance criteria, the standing
+  house-rules card, and — when a code-pattern is resolved — your project's
+  conventions + blocking invariants + the playbook's measurable validation
+  gate. Executors echo `actual_model`/`actual_effort` (claimed-vs-actual tier
+  check), `pattern_version`/`invariants_checked`, plus verbatim build/test
+  `evidence` and an `unmet[]` honesty field — a `done` without proof (or with
+  admitted unmet lines) is a malformed return.
+- **Plans are grounded, not trusted:** every declared file carries an
+  `exists|new` attestation the orchestrator spot-checks with Glob before
+  scoring — hallucinated paths bounce the plan back to the planner.
+- **P0–P3 severity ladder** on review/verify findings: P0 (objective breakage)
+  auto-fixed once without asking · P1 (correctness/security risk) gates ship,
+  you're asked before the fix · P2/P3 advisory, offered as an optional
+  fix-batch in the summary. Every P0–P2 finding must be anchored (file:line +
+  verbatim quote — spot-checked before any fix); unanchored findings are
+  auto-P3 and never gate.
+- **Opt-in phases** (all default OFF, via `orc config`): security pass
+  (`security_review`, fires only on runs with a task scored ≥ 70), test
+  authoring (`generate_tests`, writes tests + a TEST-PLAN.md + curl bundle to a
+  visible `test-generator/<change-slug>/` folder at the project root, never runs
+  them), behavior trace (PERMANENT — persistent per-run `.txt`).
+- **Usage is reported at every pause AND at run completion** — limits reminder
+  plus the full per-task dispatch table (score, model, effort).
+- **Disk is truth.** Every pause emits a resume block; paste it into a fresh
+  session to continue with near-zero context cost. state-of-play.md +
+  checkpoint carry everything.
+- **Strict contracts.** Workers receive slices, return fixed structures;
+  malformed = failure. `needs_context` (cap 2) is the only way a worker asks
+  for more.
+
+## Verify at first run (environment-dependent)
+
+- Whether `/usage` can be invoked programmatically (fallback: dispatch-log
+  report + instruct you to run /usage yourself — already built in).
+- That the orchestrator loads subskills by PATH (subskills/...) — it should
+  never rely on nested-skill auto-discovery.
+- The planner hand-off: if Superpowers/OpenSpec output lacks declared files,
+  the orchestrator extracts them — watch that seam on run one.
+
+## Tuning after first runs
+
+- Waves over-serializing → declared_files globs too broad; narrow them.
+- Collisions slipping through → workers under-declaring; emphasize tests too.
+- Rubric scores feel off → adjust weights in references/effort-and-mode.md;
+  audit the override log to see where the orchestrator disagreed with it.
+- Cached pattern drifted from the codebase → `/orc-pattern --refresh`.