@azure-id/orc 0.56.1 → 1.0.0

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

@@ -1,187 +1,214 @@
----
-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.
+---
+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
+    `../_shared/phases/trace.md`.
+
+## Phases
+
+`orc lane phases context-combiner --json` is this lane's pipeline: the ordered list, where
+each phase lives, and how much of it to read. **The CLI owns the order** — never
+derive it from the headings below, and never renumber or rename one without the
+manifest, because a `read: section` pointer names a HEADING and a renamed heading
+is a pointer into nothing.
+
+## 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.
+
+## Config
+
+Resolve with `orc lane config context-combiner --json` and obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
+say so and use `../_shared/config-precedence.md`'s documented defaults, out
+loud. Nothing this lane reads is contested, gated or a stop, so it owes no
+preflight line and has no gate to honour.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls context-combiner --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+state words, and **an exit code is an ANSWER wherever that contract says so, not
+a failure**. A call the answer does not name is a call this lane does not make.
+Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
+command you are about to run, out loud, before running it.