refacil-sdd-ai 5.0.4 → 5.0.7

package/README.md

@@ -19,49 +19,62 @@ Installs **skills** and **sub-agents** for **Claude Code**, **Cursor**, and **Op
 
 ## Installation
 
-Recommended: install globally once, then run `init` per repo.
+### Step 1 — Install the package globally
 
 ```bash
-# 1. Global (once)
 npm install -g refacil-sdd-ai
+```
+
+### Step 2 — Run `init` to install skills into your IDEs
 
-# 2. In the repo root
+```bash
 refacil-sdd-ai init
-#    Interactive IDE selector (Claude Code / Cursor / OpenCode) — pre-selects IDEs
-#    whose folder already exists. Use --all to install for all three without prompting.
-#    Copies skills and sub-agents to the selected IDEs, configures hooks,
-#    and creates/updates .claudeignore, .cursorignore and .opencodeignore.
-#    Also prompts for global branch config (baseBranch, protectedBranches, artifactLanguage)
-#    pre-filled from ~/.refacil-sdd-ai/config.yaml. Skipped with --yes or --defaults.
+```
+
+`init` installs skills, sub-agents, and hooks into your IDE's **global user directories** (`~/.claude/`, `~/.cursor/`, `~/.config/opencode/`). Skills are available in all your repos from this point — no need to re-run `init` when you open a new repo.
+
+- Interactive IDE selector (Claude Code / Cursor / OpenCode) — pre-selects installed IDEs.  
+  Use `--all` to install for all three without prompting.
+- Your IDE selection is saved to `~/.refacil-sdd-ai/selected-ides.json` and reused on every `update`.
+- Also prompts for global branch config (`baseBranch`, `protectedBranches`, `artifactLanguage`)  
+  stored in `~/.refacil-sdd-ai/config.yaml`. Skip with `--yes` or `--defaults`.
+
+Re-run `init` if you install a new IDE or want to change which IDEs have the methodology.
 
-# 3. Restart your IDE session
-#    (new skills are not detected until you restart)
+**After `init`, restart your IDE session** — new skills are not detected until you restart.
 
-# 4. In the IDE
+### Step 3 — Configure each repo with `/refacil:setup`
+
+In each repo where you want to use the methodology, open the IDE and run:
+
+```
 /refacil:setup
-#    Generates AGENTS.md and the .agents/ directory for the project
 ```
 
+This generates `AGENTS.md` and the `.agents/` project index for that repo. It is the only step required per repo. Skills will prompt you to run it if it has not been done yet.
+
 ### Adding a new IDE to an existing installation
 
-If you already have the methodology installed for Claude Code or Cursor and want to add OpenCode (or any other IDE), just run `init` again from the repo root:
+To add an IDE that was not selected during the original `init`, run `init` again:
 
 ```bash
 refacil-sdd-ai init
 ```
 
-The selector will pre-select the IDEs whose folders already exist (`.claude/`, `.cursor/`). Check the new IDE you want to add (e.g. OpenCode), leave the existing ones checked, and confirm — only the newly selected IDE will receive files; existing installations are refreshed in place.
+The selector pre-marks your previously selected IDEs (from `~/.refacil-sdd-ai/selected-ides.json`). Check the new IDE, leave the others checked, and confirm — the new IDE is added and the selection is updated.
 
-> **`update` does not add new IDEs** — it only updates IDEs already installed. Use `init` to add a new one.
+> **`update` does not add new IDEs** — it only updates the IDEs already in your selection. Use `init` to add a new one.
 
 ### Update
 
 ```bash
 npm update -g refacil-sdd-ai
-refacil-sdd-ai update          # in each repo where it is used
+refacil-sdd-ai update
 ```
 
-`update` detects which IDEs are installed by folder presence (`.claude/`, `.cursor/`, `.opencode/`) and only updates those — it never creates IDE directories that did not exist before. In Claude Code and Cursor the `check-update` hook (every session) syncs skills and `compact-guidance`. In OpenCode the equivalent runs via the `session.created` handler of the embedded plugin (`.opencode/plugins/refacil-hooks.js`). Only if the automatic detection (`lib/methodology-migration-pending.js`) finds a pending methodology migration does it write the flag and allow `notify-update` / `tui.prompt.append` to prompt `/refacil:update`. If there is no migration, the user is not interrupted. The `/refacil:update` skill uses `refacil-sdd-ai migration-pending` as the same criterion.
+`update` reads `~/.refacil-sdd-ai/selected-ides.json` (the selection saved during `init`) and only updates those IDEs — it never touches IDEs you did not select. You do not need to run `update` per repo; it operates on the global install.
+
+In Claude Code and Cursor the `check-update` hook (every session) syncs skills and `compact-guidance` automatically. It also cleans up any leftover project-level `refacil-*` artifacts from older installations and prints a message if it removes anything. In OpenCode the equivalent runs via the `session.created` handler of the embedded plugin. Only if a pending methodology migration is detected does the hook prompt `/refacil:update` — otherwise the user is not interrupted.
 
 ### Uninstall
 
@@ -443,6 +456,8 @@ Local bus (WebSocket over `127.0.0.1`) so agents across different repos can comm
 
 **SDD-AI conventions in the bus**: anyone in the room joined with `/refacil:join` (methodology already active in the repo). **Change requests** to another session go with **clear scope** in the `ask` (no pasting the guide in every message); the destination repo channels with **`/refacil:propose`** and whoever implements **closes via bus** to who requested the work. Details and edge cases: `refacil-prereqs/BUS-CROSS-REPO.md` in the installed skills.
 
+**Contract-first questions (recommended)**: for cross-repo integration clarifications, format `ask/reply` around contract fields (integration point, input contract, output contract, compatibility, source of truth). If the first response is partial, send a focused retry `ask` only for unresolved points. This keeps bus conversations actionable for integration work instead of generic chat.
+
 **Pure observer** (0 tokens): `refacil-sdd-ai bus watch <session>` or `refacil-sdd-ai bus view` for the web UI.
 
 > **Diagrams, scenarios and pitch**: see `refacil-bus-diagrams.md` (included in the package) — includes architecture, flow with attend, flow without attend, comparative impact table, and visual decision guide (Mermaid).

package/agents/debugger.md

@@ -56,20 +56,26 @@ If you prefer to continue here, provide:
 
 The main agent passes you: `mode: investigation` + bug `description`.
 
-### Step 1: Investigate root cause
+### Step 1: Reproduce and minimize first
+
+- Define the minimal reproducible scenario from the description (inputs, trigger, observed failure).
+- Narrow scope to the smallest code path that can still explain the failure.
+
+### Step 2: Investigate root cause
 
 - Search the codebase for symbols/files mentioned in logs or stack traces from the description.
 - Trace the flow from entry (controller/endpoint) to the failure point.
 - Review recent commits if the bug is new: `git log --oneline -20`.
 - If the cause seems to be in an interaction with another repo (unexpected API response, event with a different format, broken contract on the producer/consumer side), indicate it in `hypotheses` with `crossRepo: true` and the protocol from `refacil-prereqs/BUS-CROSS-REPO.md` so the wrapper resolves it.
 
-### Step 2: Formulate hypotheses
+### Step 3: Formulate hypotheses with evidence
 
 Prepare 1-3 hypotheses ordered by confidence (`high`/`medium`/`low`), each with:
 - Suspicious file and line.
 - Description of the unhandled condition.
+- Evidence that supports the hypothesis (repro observation, log, code path check).
 
-### Step 3: Propose fix for hypothesis #1
+### Step 4: Propose fix for hypothesis #1
 
 Describe:
 - Minimum necessary change.
@@ -84,6 +90,7 @@ Describe:
 
 Hypotheses (ordered by confidence):
 1. [high|medium|low] file:line — [description]
+   Evidence: [what validates this hypothesis]
 2. ...
 
 Proposed fix for hypothesis #1:
@@ -101,6 +108,7 @@ Proposed fix for hypothesis #1:
       "file": "<path/file>",
       "line": <int or null>,
       "description": "<description of the cause>",
+      "evidence": "<brief evidence backing this hypothesis>",
       "crossRepo": <bool>
     }
   ],
@@ -197,6 +205,7 @@ Resolve and run the test command according to `METHODOLOGY-CONTRACT.md §3`. All
 ## Rules
 
 - In mode=investigation: **NEVER modify files**. Only report hypotheses and proposed fix.
+- In mode=investigation: follow diagnose loop discipline (reproduce, minimize, hypothesize, validate evidence) before proposing a fix.
 - In mode=fix: the fix must be MINIMAL. Never over-refactor.
 - Regression tests are MANDATORY in mode=fix.
 - Use **concise** output mode by default.

package/agents/tester.md

@@ -11,7 +11,7 @@ You are a test generation agent. You receive a briefing with CA/CR criteria, fil
 
 If a CA/CR criterion is vague, flag it — do not write a test that trivially passes without validating real behavior.
 
-**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + test command from `METHODOLOGY-CONTRACT.md §3`.
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + `METHODOLOGY-CONTRACT.md` §3 and **§3.1** (defaults: scoped tests + **scoped** coverage on changed/new code; **full** suite/repo-wide coverage only when `testScope: full`).
 
 ## Guardrail: direct invocation detection
 
@@ -34,7 +34,7 @@ If you prefer to continue here, provide:
 
 **BEFORE reading any file, read this rule.**
 
-- **The briefing is your primary source.** If the wrapper passed you `criteria`, `filesToTest`, and `testCommand`, use them directly — do not re-read specs to extract the criteria again.
+- **The briefing is your primary source.** If the wrapper passed you `criteria`, `filesToTest`, and `testCommand` (baseline), plus `testScope` / `runCoverage` / `coverageCommand`, use them directly — do not re-read specs to extract the criteria again.
 - **Stack detection**: read ONE of the project configuration files (`package.json` or `jest.config.*` or equivalent) to confirm the framework. Do not read multiple.
 - **Test pattern**: if the briefing includes `testPatternFile`, read that file (1 Read). If not, find ONE existing relevant test. Do not scan the test directory.
 - **Files to test**: read only the files listed in `filesToTest`. Do not read their related modules or transitive dependencies.
@@ -61,7 +61,9 @@ If the briefing includes `testPatternFile`, that file already gives you the patt
 
 ### Change mode (with briefing)
 
-The wrapper passed you the BRIEFING with `changeName`, `criteria`, `filesToTest`, `testCommand`, and optionally `testPatternFile`.
+The wrapper passed you the BRIEFING with `changeName`, `criteria`, `filesToTest`, `testCommand` (baseline per §3 / project), `testScope` (`scoped` \| `full`), `runCoverage` (`true` \| `false`), `coverageCommand` (or `null`), and optionally `testPatternFile`.
+
+Defaults if missing: `testScope: scoped`, `runCoverage: true`.
 
 1. **Detect stack** (maximum 1-2 reads — see previous section).
 2. **Read the pattern** from `testPatternFile` if it comes in the briefing (1 read).
@@ -70,9 +72,9 @@ The wrapper passed you the BRIEFING with `changeName`, `criteria`, `filesToTest`
    - Map: each CA-XX from the briefing = at least 1 test; each CR-XX = at least 1 test.
    - Add edge cases: null/nil, boundary values, errors.
    - Generate the test file following the detected pattern.
-4. **Run** the briefing's `testCommand`.
-5. **Fix** failures iteratively.
-6. **Coverage**: if the project has a coverage script, run it.
+4. **Run tests** (see **Execution rules** below).
+5. **Fix** failures iteratively (re-run with the same narrowed command after fixes).
+6. **Coverage** — see **Coverage rules** below (after tests pass).
 
 **If there is NO briefing** (direct invocation or partial briefing):
 - Read the change specs to extract CA/CR
@@ -81,20 +83,40 @@ The wrapper passed you the BRIEFING with `changeName`, `criteria`, `filesToTest`
 
 ### File mode (targetFile provided)
 
-The wrapper passes you `targetFile`.
+The wrapper passes you `targetFile` and should pass `testCommand`, `testScope`, `runCoverage`, `coverageCommand` with the same defaults as change mode.
 
 1. Detect stack (1-2 reads).
 2. Read the specified file.
 3. Read ONE similar existing test as a pattern reference (if it exists).
 4. Generate the test file following the project conventions.
-5. Run and fix until they pass.
+5. Run and fix until they pass (**Execution rules** below).
+
+### Execution rules (mandatory — §3.1)
+
+Build the shell command actually executed; record it in JSON `tests.command`. Use **`AGENTS.md`**, **`METHODOLOGY-CONTRACT.md` §3**, and **one** project config file (`package.json`, `pytest.ini`, `go.mod`, `Cargo.toml`, `pom.xml`, `.csproj`, `build.gradle.kts`, etc.) so narrowing matches the stack.
+
+- **`testScope: full`** (on-demand): run the baseline `testCommand` unparsed by this agent (whole suite). Add coverage only if `runCoverage: true` — then use the project’s **normal / repo-wide** coverage behavior (heavy).
+- **`testScope: scoped` (default)**:
+  - **After** generating or updating test artifacts in this session, invoke the baseline runner with **explicit scope only**: file paths, package paths, `-Dtest=…`, `--tests …`, `-p` / `./pkg`, or whatever that tool documents — never rely on implicit full-suite discovery.
+  - Where the stack needs a sentinel (e.g. ` -- ` between script args and forwarded paths), follow that tool’s contract.
+  - If paths do not exist yet (edge case): use the narrowest filter the runner supports (pattern, substring, shard) derived from `filesToTest` or `targetFile`, then switch to explicit paths once files exist.
+  - Do **not** run the baseline with zero narrowing unless falling back per §3.1 (and then warn).
+
+### Coverage rules (mandatory — §3.1)
+
+- **`runCoverage: false`**: skip coverage; JSON `coverage: null`, report “skipped”.
+- **`runCoverage: true` + `testScope: scoped`** (default combination): after tests pass, run coverage **with collection/includes limited** to `filesToTest`, generated/updated tests for those files, and the narrowest dirs/packages covering them (`--cov=…` pointing at touched packages only, `--collectCoverageFrom`/include globs for touched subtrees only, Gradle/JaCoCo on affected modules only, etc.). **Do not** run repo-wide collection while remaining in `scoped`.
+- **`runCoverage: true` + `testScope: full`**: after full-suite tests pass, run `coverageCommand` once as the project defines (typically global/report over the module).
+- If `coverageCommand` is null — report `coverage` N/A. If narrowing is unsupported by the tool — report N/A + WARNING (do not widen silently to repo-wide coverage while scoped).
+
+Working directory: module / service / repo root stated in project docs (`AGENTS.md` or config), not assumed.
 
 ## Generation rules
 
 - **NEVER hardcode a stack** — confirm from the actual project.
 - Each CA-XX from the briefing = at least 1 test.
 - Each CR-XX from the briefing = at least 1 test.
-- Minimum 80% coverage on new files.
+- Design tests toward **≥80% logical coverage** of new behaviors; with default `runCoverage: true`, measure on **touched scope** when `testScope: scoped`.
 - Tests independent of each other.
 - Minimal mocks — do not mock what can be tested directly.
 - Place tests where the project expects them.
@@ -107,7 +129,7 @@ The wrapper passes you `targetFile`.
  Tests executed: [N] tests
  Passed: [N]
  Failed: [N]
- Coverage new files: [X]% | N/A
+ Coverage: [X]% (scoped) | [X]% (full) | N/A | skipped (runCoverage: false or no tooling)
  Status: PASS | FAIL | N/A
 ```
 
@@ -115,8 +137,8 @@ The wrapper passes you `targetFile`.
 {
   "result": "APPROVED" | "PARTIAL" | "FAILED",
   "passed": <bool — true if result !== "FAILED">,
-  "filesCreated": ["path/file.test.ts", "..."],
-  "filesRead": ["path/read-for-context.ts", "..."],
+  "filesCreated": ["path/to/generated-or-updated-test", "..."],
+  "filesRead": ["path/read-for-context", "..."],
   "tests": {
     "command": "<command executed>",
     "total": <int>,

package/agents/validator.md

@@ -11,7 +11,7 @@ You are a validation agent. You receive a briefing with CA/CR criteria, a test c
 
 Report every CA/CR violation you find. Do not soften findings because the implementation is mostly correct. A partial pass is a fail.
 
-**Prerequisites**: rules from `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
+**Prerequisites**: rules from `refacil-prereqs/METHODOLOGY-CONTRACT.md` (including §3.1 — default scoped tests **and scoped coverage** on the change).
 
 ## Guardrail: direct invocation detection
 
@@ -36,7 +36,7 @@ If you prefer only the report (without applying fixes), respond with the explici
 
 **BEFORE reading any file or running any command, read this rule.**
 
-- **If the briefing includes `testCommand`**: use it directly — **do not look up the command in `METHODOLOGY-CONTRACT.md`**.
+- **If the briefing includes `testCommand`**: use it directly — **do not look up the command in `METHODOLOGY-CONTRACT.md`**. Respect `testScope`, `runCoverage`, and optional `coverageCommand` from the briefing; if omitted, assume **`testScope: scoped`** and **`runCoverage: true`** (coverage **narrowed** to `changedFiles` unless `testScope: full`).
 - **If the briefing includes `criteria`**: use it for verification — **do not re-read the specs** to extract the CA/CR again.
 - **If the briefing includes `changedFiles`**: focus the 3D verification on those files — do not do a global discovery.
 - Read ONLY the specific files needed to verify each CA/CR.
@@ -79,14 +79,13 @@ Produce a list of issues with severity `CRITICAL` / `WARNING` / `SUGGESTION`.
 
 ### Step 2: Verify tests
 
-**If the briefing includes `testCommand`**: run it directly.
-**If there is NO briefing**: resolve the command by reading `refacil-prereqs/METHODOLOGY-CONTRACT.md §3`.
+**If the briefing includes `testCommand`**: run **only** that command (already narrowed by the wrapper when `testScope: scoped`). Do not substitute a fuller command.
+**If there is NO briefing**: resolve by reading `METHODOLOGY-CONTRACT.md` §3, then narrow per §3.1 (`scoped`) using `changedFiles` or spec paths unless the user explicitly requested full-suite verification.
 
 Verify:
-- All tests pass.
-- Tests cover the acceptance criteria from the briefing (or from the spec if there is no briefing).
-- There are no missing tests for key requirements.
-- If there is a coverage command, run it; if it does not exist, report N/A.
+- All invoked tests pass.
+- Tests substantively cover acceptance criteria from the briefing (or from the spec).
+- **`runCoverage: true`** (briefing default unless user opted out): after tests pass, run coverage narrowed to **`changedFiles`** / touched packages when **`testScope: scoped`**; use standard repo-wide coverage when **`testScope: full`**. If `coverageCommand` is null → N/A. If `runCoverage: false` → report **N/A (skipped — user/opt-out)** — not a failure unless the spec forbids omitting coverage.
 
 ### Step 3: Validate cross-repo ambiguities (optional)
 
@@ -108,7 +107,7 @@ Your final response MUST have this structure:
  [PASS/FAIL] Test command: [command]
  [PASS/FAIL] Tests executed: [N]
  [PASS/FAIL] Tests passed: [N]
- [PASS/FAIL/N/A] Coverage: [X]% (minimum required: 80%)
+ [PASS/FAIL/N/A] Coverage: [X]% (scoped/full) — or **N/A** when skipped or tooling missing; with `runCoverage: true`, expect strong coverage **on touched code** when `scoped`, or project/global expectations when `full`.
 
 RESULT: APPROVED | REQUIRES_CORRECTIONS