scip-query 0.10.11 → 0.11.0

package/skills/scip-concrete-plan/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: scip-concrete-plan
+description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require source citations, reuse audit, test seams, side-effect boundaries, contracts, and verification.
+commands:
+  - template: "scip-query status --capabilities"
+    when: "Discover: confirm the index is fresh before citing graph facts."
+  - template: "scip-query plan-context <target>"
+    when: "Discover: anchor the plan with pre-edit context for the target."
+  - template: "scip-query refs <symbol>"
+    when: "Reuse audit: find existing consumers before proposing a new unit."
+  - template: "scip-query code <symbol>"
+    when: "Reuse audit: read source before citing a behavior claim."
+  - template: "scip-query trace <symbol>"
+    when: "Verify the plan: rerun source-producing context for cited targets."
+---
+
+# Concrete Plan
+
+Use this skill to write an implementation plan that another agent can execute without guessing. A concrete plan is a dated Markdown checklist whose code claims come from scip-query evidence and whose design makes the intended behavior easy to test before it is easy to ship.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need lookup tips, command families, postchecks, or subagent rules.
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query status --capabilities` | Show index status for this project | Discover: confirm the index is fresh before citing graph facts. |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Discover: anchor the plan with pre-edit context for the target. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Reuse audit: find existing consumers before proposing a new unit. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reuse audit: read source before citing a behavior claim. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Verify the plan: rerun source-producing context for cited targets. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rules
+
+1. Start with `scip-query status --capabilities`; reindex only when freshness is `stale`, `missing`, or `unknown`.
+2. Anchor the plan with `scip-query plan-context <target>`. If the target is not indexed, record that fact and use scip-query for every code-adjacent claim it can answer.
+3. Put the plan in `docs/plans/YYYY-MM-DD-<short-name>.md`.
+4. Every code step includes a `Source` field naming the scip-query command that produced the path, line range, and behavior claim.
+5. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
+6. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+
+## Planning Terms
+
+A reuse audit is the part of a plan that proves a proposed new symbol, file, option, wrapper, or contract is needed; what makes it useful is that it ties the new shape to existing definitions, consumers, and rejected extension points.
+
+A test seam is the entry point a test can call to prove a behavior without replaying the whole product path; what makes it valuable in a plan is that it names the exact unit or boundary where correctness will be observed.
+
+A side-effect boundary is the edge where deterministic program decisions meet files, processes, clocks, networks, databases, or other external capabilities; what makes it important is that failures and fakes can be isolated there while core decisions stay easy to test.
+
+A contract is the stable promise one code unit exposes to another, including accepted inputs, returned outputs, errors, timing expectations, and side effects that callers may rely on.
+
+## Workflow
+
+### 1. Discover
+
+Run:
+
+```bash
+scip-query status --capabilities
+scip-query plan-context <target>
+```
+
+Use the shared reference for follow-up commands. Fill three gates before designing:
+
+```markdown
+## Goal
+What the user is trying to accomplish and what done looks like for them.
+
+## Current State
+The affected end-to-end flow, with scip-query citations for entry points, callers, data flow, dependencies, downstream impact, and non-obvious invariants.
+
+## Reuse Audit
+For every new symbol or file being considered: reuse target, extension target, or evidence-backed reason new code is justified.
+```
+
+This step is complete only when the plan can explain the current flow, its consumers, and every proposed new unit's reuse decision with citations.
+
+### 2. Shape for Tests
+
+Before writing implementation phases, add:
+
+```markdown
+## Testability Design
+
+| Behavior | Test seam | Dependencies to inject | Pure core | Side-effect shell | Contract |
+| --- | --- | --- | --- | --- | --- |
+| <behavior> | <test entry point> | <clock/db/http/logger/etc.> | <calculation/decision function> | <I/O wrapper> | <small interface or call shape> |
+```
+
+Plan the code so tests can call the pure core directly and exercise the side-effect shell with injected replacements. Prefer this shape:
+
+1. Parse and validate at the boundary.
+2. Pass domain data and injected dependencies into a small orchestrator.
+3. Put calculations, filtering, selection, formatting decisions, and state transitions in pure functions.
+4. Keep database, network, filesystem, clock, randomness, logging, email, and payment calls in thin side-effect shells.
+5. Depend on small contracts at boundaries; avoid broad option objects, booleans that hide behavior, and wrappers that merely forward.
+
+This step is complete only when every changed behavior has a named test seam and the plan makes clear which logic can be tested without real external services.
+
+### 3. Design the Checklist
+
+Write phases in execution order. Keep each phase deployable or explicitly mark why it is not. Use this step format:
+
+```markdown
+### N.M - Imperative title
+
+- [ ] **File**: `path/to/file.ts:LINE-LINE`
+- **Source**: `scip-query <command>`
+- **What**: Current behavior verified from source.
+- **Change**: Exact edit to make.
+- **Testability**:
+  - Test seam:
+  - Injected dependencies:
+  - Pure core:
+  - Side-effect shell:
+  - Contract:
+- **Validation**: Targeted test, smoke command, or manual check that proves the behavior.
+- **Why**: Why this step is needed and why this order is safe.
+```
+
+This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, and validation.
+
+### 4. Stress-Test
+
+Apply these lenses to every phase. Add or change steps until each answer is concrete:
+
+| Lens | Plan must answer |
+| --- | --- |
+| Purpose | Why does the current code exist, and what invariant must survive? |
+| Blast radius | Which direct and transitive consumers move with this change? |
+| Valid intermediate state | Would the project still work after only this phase? |
+| Reversibility | Is this a one-way or two-way door, and what rollback exists? |
+| Failure | What happens when I/O, external APIs, malformed data, retries, or crashes occur? |
+| Concurrency | What shared state can be touched twice or out of order? |
+| Boundaries | Who can call this entry point, and where is input validated? |
+| Data integrity | What existing data, generated artifacts, or persisted contracts are affected? |
+| Observability | Can a maintainer diagnose failures from logs/errors without rereading the source? |
+| Human experience | What would surprise, confuse, or block a real user? |
+| Reuse | Does existing code already solve this problem or most of it? |
+| Testability | Are dependencies injectable, logic pure where practical, concerns separated, and contracts small? |
+
+This step is complete only when every discovered gap has either a new plan step or a written reason it is accepted.
+
+### 5. Verify the Plan
+
+Run or delegate phase-by-phase reference checks. Each verifier confirms:
+
+- every path exists;
+- every line range is still within about five lines;
+- every behavior claim matches source;
+- every new unit has reuse evidence;
+- every behavior-changing step has a validation command and testability design.
+
+Then rerun the source-producing context for the cited targets:
+
+```bash
+scip-query plan-context <target>
+```
+
+Use the shared reference for subagent briefing text when delegating.
+
+This step is complete only when stale references are fixed and every phase has a validation path.
+
+## Output Shape
+
+The plan file contains:
+
+1. Title and date.
+2. Goal.
+3. Current State.
+4. Reuse Audit.
+5. Testability Design.
+6. Design Phases.
+7. Stress-Test Findings.
+8. Execution Order and deployable phase notes.
+9. Ship Order with one-way doors flagged.
+10. Summary of files to create, edit, delete, and verify.

package/skills/scip-concrete-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Concrete Plan"
+  short_description: "SCIP-grounded implementation plans"
+  default_prompt: "Use $scip-concrete-plan to create a SCIP-grounded implementation plan for this change."

package/skills/scip-conductor/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: scip-conductor
+description: Plan and conduct multi-step engineering programs like a skeptical principal engineer. Use for writing executable multi-phase plans, delegating implementation, reviewing another agent's work, or carrying a large change end to end with verification at every handoff.
+commands:
+  - template: "scip-query plan-context <target>"
+    when: "Anchor each phase's step before delegating it."
+  - template: "scip-query diff-gate --json"
+    when: "Verify a handoff before accepting it and before closing the program."
+  - template: "scip-query health --json"
+    when: "Pre-register or check a program-level health benchmark."
+---
+
+# scip-conductor
+
+This skill is how to run a *program* of work — planning, delegation, review,
+and closure — not how to write one change plan (use a dedicated planning
+skill such as `scip-concrete-plan` for individual changes when one is available).
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Anchor each phase's step before delegating it. |
+| `scip-query diff-gate --json` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | Verify a handoff before accepting it and before closing the program. |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | Pre-register or check a program-level health benchmark. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## The Three Laws
+
+1. **A green result you have never seen fail is unverified.** Applies to
+   tests, gates, reports from other agents, and your own checks. (Where
+   available, `scip-integrity-audit` is the same law aimed at code.)
+2. **A plan is a contract for a less-capable executor, not a note to self.**
+   If a competent-but-uninspired agent could not execute a step without
+   guessing, the step is not finished being written.
+3. **Nothing is silent.** Every finding, deviation, and shortcut is either
+   fixed or written down with a reason someone else would accept. 0%
+   silent is the invariant; "fixed everything" is not.
+
+## Writing the Plan
+
+- **Goal states what DONE MEANS falsifiably** — a command someone can run
+  and a result they can check, not an aspiration.
+- **Pre-register acceptance benchmarks.** Before any work: measure the
+  current number (test count, timing, finding count, proof line), write it
+  in the plan, and state the target number. Work that cannot move a
+  pre-registered number is scope to question.
+- **Every step carries five fields**: file anchor with verified current
+  behavior (cite how you know); the exact change; the validation command
+  with expected output; testability design (pure core, injected effects);
+  why this step is safe *in this order*. "Update X" with no current/target
+  behavior is a wish, not a step.
+- **Order phases by information gain and risk**: blockers and
+  evidence-integrity first; cheap discriminating probes before expensive
+  builds; measurement before optimization; anything not yet decided by the
+  human is a GATED phase the executor must not start. Infrastructure the
+  later steps inherit (a labeling choke point, a shared helper layer)
+  lands before the features that need it.
+- **Flag one-way doors** with their migration path, and keep an explicit
+  DEFER list so cut scope is visible instead of forgotten.
+- **Include the working agreement**: ONE COMMIT PER STEP (bisectability is
+  non-negotiable; phase-level commits hide which step broke), the exact
+  gate commands — the FULL gate set the repo defines per phase: tests,
+  typecheck, lint/format, and build, not just focused tests (focused tests
+  hide cross-phase regressions; omitting the linter is how red mains ship),
+  regeneration duties,
+  and the deviation protocol —
+  "if source contradicts an anchor, BLOCKED-note it and continue; never
+  improvise silently."
+
+## Conducting the Work
+
+- **Delegate breadth, keep judgment.** Fan out mechanical/scoped work;
+  personally own anything requiring taste, cross-cutting context, or the
+  final word on "is this real."
+- **Concurrent agents get disjoint write scopes**, named in their briefs.
+  If a collision happens anyway: stop racing, apply-verify-commit
+  atomically in one action, and re-sequence to a single writer.
+- **Never accept a report — reproduce its evidence.** On every handoff,
+  choose the *minimal discriminating probe*: the one command most likely to
+  expose the report being wrong (a mutation input, a hand count, the
+  benchmark number), and run it yourself. A report verified by reading it
+  is not verified.
+- **Loop until the gate is quiet**: fix → re-run the discriminating probe →
+  re-run the gate → only then move on. After the program: fold what was
+  learned back into the durable layer (docs, skills, followups) — insight
+  that lives only in the conversation is lost.
+- **Escalate only genuine decision points** — one-way doors, scope changes,
+  taste, spending. Everything else: decide, act, disclose.
+
+## Scar Rules (each bought with a real failure)
+
+- **Verify your verifier.** A gate check that cannot fail is no gate: a
+  lint grep that only matches one linter's output, a diff-gate run on a
+  clean tree, a test suite that skips the new path. Prove the check catches
+  a planted failure once before trusting its green.
+- **Never `git checkout`/`restore`/`stash` on a tree with uncommitted
+  work** — yours or anyone's. Revert probe edits by targeted deletion.
+  If source is lost, check `dist/*.map` sourcesContent before panicking.
+- **Commit working states early and surgically** (explicit paths, never
+  `add -A` on a shared tree); an unbisectable pile of work is a liability.
+- **Make the commit cadence mechanical, not aspirational.** At every step
+  boundary run the arithmetic check: steps completed == commits made. If
+  they differ, stop and commit before touching anything new. "I'll commit
+  when it's all done" is the signature decay of a long or low-effort run —
+  two real executions finished an entire plan with zero or one commit, and
+  both times the deviation was rationalized mid-run, not decided. A
+  self-check that is a count cannot be rationalized.
+- **Watch for your own gate holes**: after any "all green," ask what that
+  check does NOT cover (eslint vs prettier; unit vs integration; clean-tree
+  vacuity).
+
+## Self-Report (required output)
+
+End every conducted program — and every plan written under this skill —
+with a checklist mapping each section above to concrete evidence:
+the pre-registered benchmarks and their before/after values; each handoff's
+discriminating probe and its OBSERVED result (a probe listed but not run
+counts as not run); the deviation ledger; the DEFER list;
+which learnings were folded back and where. A reviewer must be able to
+audit the *conduct*, not just the artifact.
+
+## Completion
+
+The program is complete only when: every pre-registered benchmark met or
+its miss explained; every handoff probe run and recorded; the gate quiet on
+the final state; nothing silent — every finding fixed or ledgered; and the
+self-report written.

package/skills/scip-conductor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Conductor"
+  short_description: "Conduct multi-phase engineering programs"
+  default_prompt: "Use $scip-conductor to plan and conduct this multi-phase program end to end with verified handoffs."

package/skills/scip-debug/SKILL.md

@@ -1,49 +1,73 @@
 ---
 name: scip-debug
-description: Root-cause bugs and regressions with scip-query evidence. Use when the user reports a bug, failing behavior, regression, confusing runtime path, broken data flow, or asks to debug, diagnose, reproduce, trace, or explain why code behaves incorrectly before fixing it.
+description: Debug bugs and regressions with scip-query evidence. Use for failing behavior, wrong data flow, confusing runtime paths, broken tests, root-cause analysis, reproduction, tracing, or minimal fixes.
+commands:
+  - template: "scip-query files <feature-or-error-term>"
+    when: "Find the entry point from a feature name or error term."
+  - template: "scip-query trace <candidate-symbol>"
+    when: "Find the entry point: definition plus every reference."
+  - template: "scip-query call-graph <entry-symbol>"
+    when: "Follow execution: callers and callees along the failing path."
+  - template: "scip-query dataflow <symbol-or-variable>"
+    when: "Follow data: producers, consumers, and usage sites."
+  - template: "scip-query similar <suspect-symbol> --json --full"
+    when: "Compare nearby implementations for missing guards or handling."
+  - template: "scip-query change-surface <suspect-file> --json --full"
+    when: "Bound the fix: exports, consumers, and blast-radius risk."
 ---
 
-# SCIP Debug
+# scip-debug
 
-Use this skill to move from a reported failure to a minimal verified fix. A bug is a mismatch between expected behavior and observed behavior in a concrete execution path. A root cause is the earliest code fact in that path that explains the mismatch and makes the later symptoms possible.
+Use this skill to move from a reported failure to a minimal verified fix. A bug is a mismatch between expected behavior and observed behavior in a concrete execution path. A root cause is the earliest code fact in that path that explains the mismatch.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query files <feature-or-error-term>` | Find files matching a pattern | Find the entry point from a feature name or error term. |
+| `scip-query trace <candidate-symbol>` | Trace a symbol: definition + all references | Find the entry point: definition plus every reference. |
+| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | Follow execution: callers and callees along the failing path. |
+| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Follow data: producers, consumers, and usage sites. |
+| `scip-query similar <suspect-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | Compare nearby implementations for missing guards or handling. |
+| `scip-query change-surface <suspect-file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | Bound the fix: exports, consumers, and blast-radius risk. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
 ## Rules
 
-1. Reproduce or restate the failure before changing code.
-2. Use scip-query to identify entry points, call paths, data flow, and blast radius. Do not debug from filename guesses alone.
-3. Prefer one narrow fix over broad cleanup. If cleanup is also needed, record it after the bug fix unless it is required for correctness.
-4. Verify the fix with the repo's test or smoke command, then run `scip-verify`.
+1. Reproduce or restate the failure before editing.
+2. Use scip-query to find entry points, call paths, data flow, and blast radius.
+3. Prefer one narrow fix over broad cleanup.
+4. Verify with the narrowest repo test or smoke command, then invoke `scip-verify`.
 
 ## Workflow
 
 ### 1. Pin the failure
 
-Record:
+Record observed behavior, expected behavior, reproducing command/route/UI action/test/job/file, error text or wrong output, and regression window if known.
 
-- observed behavior;
-- expected behavior;
-- command, route, UI action, test, job, or file that exposes it;
-- error text or wrong output;
-- suspected time window if it is a regression.
+If no reproduction is provided, build the smallest runnable reproduction from existing tests, scripts, CLI, or app entry points.
 
-If the user provides no reproduction, make the smallest runnable reproduction you can from the repo's existing tests, scripts, CLI, or app entry points.
+This step is complete only when the mismatch is concrete enough to test or the missing external fact is named.
 
 ### 2. Find the entry point
 
 ```bash
-scip-query status --capabilities
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
 scip-query files <feature-or-error-term>
 scip-query outline <candidate-file>
 scip-query trace <candidate-symbol>
 scip-query code <candidate-symbol>
 ```
 
-Use `scip-query by-kind function --scope <scope>` or `scip-query kind-counts --scope <scope>` when the codebase is unfamiliar and you need an inventory before selecting an entry point.
+Use `kind-counts` or `by-kind` when the codebase is unfamiliar.
+
+This step is complete only when the failing path has a plausible entry point with source evidence.
 
-### 3. Follow execution
+### 3. Follow execution and data
 
 ```bash
 scip-query call-graph <entry-symbol>
@@ -51,73 +75,51 @@ scip-query code <callee-symbol>
 scip-query refs <state-or-api-symbol>
 scip-query fan-in <suspect-symbol>
 scip-query fan-out <suspect-file>
-```
-
-Build the smallest path that explains the observed behavior. Stop expanding once the path reaches the first code fact that can cause the symptom.
-
-### 4. Follow data and state
-
-```bash
 scip-query dataflow <symbol-or-variable>
 scip-query slice <symbol-or-variable>
 scip-query slice <symbol-or-variable> --forward
 ```
 
-Use dataflow when the bug looks like wrong state, wrong input normalization, missing validation, stale cache, dropped field, wrong async order, or an unexpected output value.
+Stop expanding when the first code fact that can cause the symptom is found.
 
-### 5. Compare nearby implementations
+This step is complete only when the path explains the symptom or the missing evidence is explicit.
+
+### 4. Compare nearby implementations
 
 ```bash
 scip-query similar <suspect-symbol> --json --full
-scip-query convergence <suspect-symbol> <similar-symbol>
+scip-query similar <suspect-symbol> <similar-symbol> --plan
 scip-query similar-files <suspect-file> --json --full
 ```
 
-A similar implementation can reveal the missing branch, guard, conversion, lifecycle step, or error handling path. Preserve essential differences; do not copy behavior blindly.
+Use comparisons to find missing guards, conversions, lifecycle steps, or error handling. Preserve essential differences.
+
+This step is complete only when comparisons either support the fix or are rejected with a reason.
 
-### 6. Bound the fix
+### 5. Bound and fix
 
 ```bash
 scip-query change-surface <suspect-file> --json --full
 scip-query affected <suspect-symbol> --json
-scip-query diff-impact --json
 ```
 
-Name the smallest symbol or file that should change. If the blast radius is larger than the bug's scope, explain why before editing.
-
-### 7. Fix and verify
+Make the smallest code change that fixes the root cause.
 
-Apply the minimal code change, then run:
+This step is complete only when the changed symbol/file is justified by blast-radius evidence.
 
-```bash
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query diff-gate --json
-```
+### 6. Verify
 
-Also run the narrowest repo test, app smoke test, or command that reproduces the failure. Invoke `scip-verify` before calling the bug fixed.
+Run the reproduction, narrow test or smoke command, and invoke `scip-verify`.
 
-## Report Format
+## Report
 
 ```markdown
-Bug: <observed mismatch>
-
+Bug:
 Entry point:
-- <file/symbol> from <command>
-
 Root cause:
-- <code fact> from <command>
-
 Fix:
-- <minimal change>
-
 Verification:
-- <repo test or smoke command>
-- `scip-query diff-gate --json`
-
 Remaining risk:
-- <blast radius, unavailable capability, or follow-up cleanup>
 ```
 
-If no root cause is proven, say what evidence is missing and what command or reproduction would unblock it. Do not present a guess as a fix.
+Do not present a guess as a root cause. If no root cause is proven, report the missing evidence.