refacil-sdd-ai 5.2.2 → 5.3.0

package/lib/testing-policy-sync.js

@@ -15,6 +15,17 @@ function buildBlock(templateContent) {
   return `${MARKER_START}\n${templateContent}\n${MARKER_END}`;
 }
 
+/** Normalize line endings for idempotent compare (CA-02 / Windows CRLF). */
+function normalizeEol(text) {
+  return text.replace(/\r\n/g, '\n');
+}
+
+function contentUnchanged(next, raw) {
+  const a = normalizeEol(next).trimEnd() + '\n';
+  const b = normalizeEol(raw).trimEnd() + '\n';
+  return a === b;
+}
+
 /**
  * Merge or replace the managed SDD-AI testing policy block in `.agents/testing.md`.
  * Skips if `.agents/` does not exist (no SDD layout yet).
@@ -70,11 +81,12 @@ function syncTestingPolicyBlock(projectRoot, packageRoot) {
     action = 'replaced';
   }
 
-  if (next === existing) {
+  const normalized = next.trimEnd() + '\n';
+  if (contentUnchanged(normalized, existing)) {
     return { status: 'unchanged' };
   }
 
-  fs.writeFileSync(testingPath, next);
+  fs.writeFileSync(testingPath, normalized);
   return { status: action };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.2.2",
+  "version": "5.3.0",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor, OpenCode and Codex",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"
@@ -13,6 +13,7 @@
     "agents/",
     "templates/",
     "README.md",
+    "NOTICE.md",
     "refacil-bus-diagrams.md"
   ],
   "keywords": [
@@ -38,13 +39,15 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js test/sdd.test.js test/config.test.js test/refactor-integrar-openspec-nativo.test.js test/refactor-rutas-refacil-sdd.test.js test/refactor-agents-english.test.js test/remove-openspec-legacy.test.js test/find-project-root.test.js test/opencode-installer.test.js test/opencode-plugin.test.js test/toml-converter.test.js test/testing-policy-sync.test.js test/session-repo-sync.test.js"
+    "postinstall": "node ./bin/postinstall.js",
+    "test": "node --test --test-concurrency=1 test/global-paths.test.js test/opencode-global-path-windows.test.js test/opencode-migrate.test.js test/opencode-clean-global.test.js test/skills-parity.test.js test/multi-ide-parity-pass2.test.js test/repo-ide-sync.test.js test/global-install.test.js test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js test/sdd.test.js test/test-scope.test.js test/config.test.js test/refactor-integrar-openspec-nativo.test.js test/refactor-rutas-refacil-sdd.test.js test/refactor-agents-english.test.js test/remove-openspec-legacy.test.js test/find-project-root.test.js test/project-root.test.js test/opencode-installer.test.js test/opencode-plugin.test.js test/check-review.test.js test/toml-converter.test.js test/testing-policy-sync.test.js test/session-repo-sync.test.js test/compact-guidance.test.js test/codegraph.test.js test/codegraph-telemetry.test.js test/compact-codegraph.test.js test/autopilot-skill-install.test.js test/read-spec-md-parser.test.js test/read-spec.test.js test/spec-sync.test.js test/kapso-init-session-removed.test.js test/kapso-preflight.test.js test/autopilot-ready-message.test.js test/stats-observability.test.js test/bus-from-env.test.js test/imp-scoped-test-execution.test.js test/broker-port-env.test.js"
   },
   "dependencies": {
     "smol-toml": "^1.6.1",
     "ws": "^8.18.0"
   },
   "optionalDependencies": {
-    "@clack/prompts": "^0.9.0"
+    "@clack/prompts": "^0.9.0",
+    "@colbymchenry/codegraph": "0.7.9"
   }
 }

package/skills/apply/SKILL.md

@@ -33,16 +33,16 @@ With the selected `changeName`, run `refacil-sdd-ai sdd status <changeName> --js
 ```
 
 Validations:
-- If `artifacts.proposal` is `false` or `artifacts.tasks` is `false` or `artifacts.specs` is `false`:
+- Build `missingArtifacts` from every false value in `artifacts` (`proposal`, `design`, `tasks`, `specs`) and report the complete list. Do not stop at the first missing artifact.
+- If `ready.forApply` is `false` or `missingArtifacts.length > 0`:
   ```
   The change at refacil-sdd/changes/[name]/ is incomplete.
-  Missing: [list of artifacts with false]
+  Missing: [complete list of artifacts with false]
   Run: /refacil:propose to complete the artifacts before implementing.
   ```
   **Stop.**
-- If `ready.forApply` is `false` for the same reason: same message above.
 
-Note: `specs` is `true` if `specs.md` exists in the root **OR** at least one `.md` under the change's `specs/` folder.
+Note: `ready.forApply` is the contract source of truth and is `true` only when `proposal.md`, `design.md`, `tasks.md`, and a valid spec source exist. `specs` is `true` if non-empty `specs.md` exists in the root and/or at least one non-empty `.md` exists under `specs/**/*.md` (recursive; empty folders do not count). The same source set is used by `sdd status`, `sync-spec`, test/verify criteria extraction, and archive.
 
 **IMPORTANT**: This command NEVER generates SDD artifacts. If they do not exist, the user must use `/refacil:propose`.
 
@@ -52,57 +52,24 @@ Run `git branch --show-current` to get the current branch.
 
 If the current branch is already a working branch (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continue without interruption to Step 1.5.
 
-If the current branch is protected, execute the 3-gate protocol below strictly. Each gate is a hard stop — do not proceed to the next gate until the user has replied.
+If the current branch is protected, **read `METHODOLOGY-CONTRACT.md §4 — Protected branch policy`** before acting, then execute the gate protocol defined there. For this skill, Gates 1 and 2 are merged into a single interaction — propose and confirm in one message, wait for one reply.
 
----
-
-**[GATE 1 — STOP AND WAIT: ask for task identifier]**
-
-Ask the user exactly this question and then STOP. Do NOT run any git command. Do NOT propose a branch name. Do NOT continue to Gate 2 until the user replies:
-
-> "What is the task number or identifier for this branch? (e.g. SEGINF-20, REF-123, or a short descriptive name)"
-
-If the user says they have no ID, note that and proceed to Gate 2 with `<ID> = none`.
-
----
-
-**[GATE 2 — STOP AND WAIT: propose branch name and ask for approval]**
-
-Only after receiving the user's reply to Gate 1:
-
-1. Verify clean working directory (`git status --porcelain`).
-2. If there are uncommitted changes, ask for approval to stash them (`git stash push -m "auto-stash-refacil"`). Do NOT stash without approval.
-3. Detect the effective configuration by running:
-   ```
-   refacil-sdd-ai sdd config --json
-   ```
-   Parse `baseBranch` and `protectedBranches` from the JSON output.
-   If the command fails or exits non-zero, fall back to:
-   - `protectedBranches` = [master, main]
-   - `baseBranch` = main (or master if main does not exist in the repo)
-4. Determine the base branch:
-   - Use the `baseBranch` value from the config (or the fallback).
-   - Only if that branch does not exist in the repo (new repo), use `main` or `master` as a temporary exception and recommend adopting the standard flow.
-5. Compose the branch name with `feature/` prefix:
-   - Feature: `feature/<ID>` (e.g. `feature/SEGINF-20`)
-   - Without ID: propose a short descriptive name (e.g. `feature/add-configurable-branches`)
-6. Present the proposed name and ask for approval. Then STOP. Do NOT run `git checkout` or `git switch`. Do NOT create the branch yet. Wait for the user's explicit confirmation:
-
-> "I'll create branch `<proposed-name>` from `<base-branch>`. Shall I proceed?"
-
----
+**See `METHODOLOGY-CONTRACT.md §4 — Protected branch policy`** for the complete gate protocol.
 
-**[GATE 3 — execute only after explicit approval from Gate 2]**
+Apply-specific annotations:
+- Default branch name: `feature/<changeName>` (e.g. `feature/my-change`). If the user provides a ticket or ID → `feature/<ID>`.
+- Stash handling: if uncommitted changes exist, inform the user in the same Gate 1+2 message and stash before creating the branch (`git stash push -m "auto-stash-refacil"`), restoring after (`git stash pop`).
+- If the user explicitly says "no" or "cancelar" → stop entirely. Do not create any branch.
 
-Only after the user explicitly confirms (e.g. "yes", "go", "ok", "proceed"):
+### Step 1.5a: Detect CodeGraph availability (non-blocking)
 
-1. Switch to the base branch and update it (`git checkout <base>` + `git pull origin <base>`).
-2. Create the working branch (`git checkout -b <branch-name>`).
-3. If a stash was approved in Gate 2, restore it (`git stash pop`).
+Run: `refacil-sdd-ai codegraph status --json`
 
-If the user does not approve at Gate 2, stop entirely. Do not create any branch. Do not continue with implementation.
+Parse the JSON output and set `codegraphAvailable`:
+- `true` if and only if the result contains `"installed": true` AND `"initialized": true`
+- `false` in all other cases (not installed, not initialized, command fails, invalid JSON, or any error)
 
----
+**IMPORTANT**: if the index is not available, continue silently — do NOT gate, pause, ask, or wait. Apply does not interrupt for CodeGraph. Unlike `/refacil:propose`, `/refacil:explore`, or `/refacil:bug` (which benefit from graph traversal to discover scope), `/refacil:apply` typically follows a propose that already resolved the architecture. The implementer uses CodeGraph only for structural lookups during implementation, not for scope discovery.
 
 ### Step 1.5: Build structured briefing (reduces sub-agent tool calls)
 
@@ -114,19 +81,11 @@ Before invoking the sub-agent, extract the key context by reading the artifacts.
    - List of files to **modify** (full paths)
 3. **Tasks** — read `refacil-sdd/changes/<changeName>/tasks.md`. Extract the full numbered list.
 4. **`testScope`** — default **`scoped`**. Inspect `$ARGUMENTS` **and** the user message invoking this skill for explicit **whole-repo** regression (e.g. `full`, `all tests`, `whole suite`, `suite completa`, `suite completa del repo`). If present → **`testScope: full`**. Otherwise **`scoped`**.
-5. **`testCommand`** — read `refacil-prereqs/METHODOLOGY-CONTRACT.md` §3 for the baseline. If **`testScope: full`**, set **`testCommand`** to that baseline verbatim. If **`scoped`**, build a **narrowed** command per **§3.1** and the builder below (**never** silently run workspace-wide/monorepo root scripts that fan out to every package unless **every** scoped path warrants it — pick the smallest roots that cover **`scope.create` ∪ `scope.modify`**).
-6. **Architecture context** — read `.agents/stack.md` if it exists; if not, `.agents/architecture.md`; if neither exists, read only the first 60 lines of `AGENTS.md`. **Do not read the entire `.agents/` folder**.
+5. **`testBaselineCommand`** — resolve the §3 baseline command language-agnostically at the **affected component root** (nearest ancestor of the files in `scope.create`/`scope.modify` with a stack manifest — per §3 component principle). Pass it verbatim. The implementer derives its own smoke command dynamically after editing — the BRIEFING must NOT include a precomputed `smokeTestCommand`. Do not pre-narrow the baseline here; narrowing is the implementer's responsibility.
 
-#### Scoped `testCommand` builder (apply — complements §3.1)
+   > **Note — component-rooted, no pre-narrowing**: the wrapper resolves the baseline at the component root (not necessarily the monorepo root). The implementer uses `git diff`/`git status` after editing to discover the actual touched files, then calls `sdd test-scope` itself (which handles the `cd <component>` prefix automatically). This keeps the BRIEFING minimal and makes the smoke reflect what was *actually* changed in this run.
 
-1. **Baseline** — command from METHODOLOGY-CONTRACT §3 detection (respect `AGENTS.md` if it defines tests).
-2. **`T`** — sorted unique **`scope.create` ∪ `scope.modify`**. Omit entries that clearly do not justify a test run (`refacil-sdd/**/*.md` planning-only, etc.).
-3. If **`testScope: full`** or **`T`** is empty: **`testCommand` = baseline** (omit **`verificationWarning`** unless you document user intent).
-4. If **`scoped`** and **`T`** non-empty**:
-   - Prefer **narrowing instructions** documented in **`AGENTS.md`** or **`.agents/testing.md`** when present (follow them strictly).
-   - Otherwise use stack-aware suffixes/path filters documented for that toolchain (examples: **`pnpm exec jest`** / **`npm test`** with **`--`** + dirs or **`--testPathPattern`**, **`pytest`** paths, **`go test ./rel/...`**, **`cargo test -p member`**, **Gradle `-p`/`--tests`**, **Maven `-pl`/`-Dtest=`** — see METHODOLOGY-CONTRACT §3.1 **Scoped command patterns**).
-   - Pick the **smallest** dirs/modules covering all of **`T`**; include explicit test files from **`T`** when they exist.
-   - If narrowing is unsafe: **`testCommand` = baseline** and set **`verificationWarning: Scoped narrowing unavailable — falling back to baseline suite (high CPU/RAM)`**.
+6. **Architecture context** — read `.agents/stack.md` if it exists; if not, `.agents/architecture.md`; if neither exists, read only the first 60 lines of `AGENTS.md`. **Do not read the entire `.agents/` folder**.
 
 Build the BRIEFING block that you will include literally in the delegation prompt:
 
@@ -137,14 +96,16 @@ objective: <objective in 1-2 sentences from the proposal>
 scope:
   create: [path/new-file-1.ts, path/new-file-2.ts, ...]
   modify: [path/existing-1.ts, path/existing-2.ts, ...]
-  doNotTouch: [refacil-sdd/, .claude/, .cursor/, AGENTS.md, package-lock.json]
+  doNotTouch: [refacil-sdd/, .claude/, .cursor/, .opencode/, AGENTS.md, package-lock.json]
+  # Note: also do not modify global Codex user dir (~/.codex/) — skills/agents/hooks are outside the repo.
 tasks:
   1. <task 1>
   2. <task 2>
   ...
 testScope: scoped | full
-testCommand: <exact shell command Step 5 — narrowed when scoped>
-verificationWarning: <optional — set when scoped fallback hits baseline suite>
+testBaselineCommand: <project baseline from METHODOLOGY-CONTRACT.md §3 — the implementer derives the smoke dynamically>
+codegraphAvailable: true | false
+verificationWarning: <optional — set if applicable>
 architectureContext: |
   <extract from stack.md or first lines of AGENTS.md>
 specsNote: <"specs.md" | "specs/**/*.md" | "both — report contradictions in issues">
@@ -176,6 +137,20 @@ This command merges into memory.yaml at the repo root using `findProjectRoot()`
 
 If `result` is `"FAILED"`, skip and wait for user instructions.
 
+### Step 2.6: Log CodeGraph telemetry (silent)
+
+After parsing the `refacil-apply-result` block, run **once** (do not mention it to the user unless it fails):
+
+```bash
+refacil-sdd-ai compact log-codegraph-event --skill implementer --has-graph <codegraphAvailable> --tool-calls <N> --tokens <N>
+```
+
+- `--has-graph`: use the `codegraphAvailable` value detected in Step 1.5a (`true` or `false`).
+- `--tool-calls`: number of `codegraph_*` tool calls the sub-agent made (0 if it did not use the graph).
+- `--tokens`: conservative estimate of tokens saved (~800–1500 per useful tool call; 0 if no graph or no calls).
+
+Estimate `--tool-calls` and `--tokens` from the sub-agent's `<usage>` block using the same criteria as `explore/SKILL.md` Step 1.5. If the command fails, ignore it; it must not block the flow.
+
 ### Step 3: Present result and next step
 
 Show the user the **report** (everything before the `refacil-apply-result` block). Do not show the JSON block — it is internal metadata.
@@ -197,4 +172,4 @@ If the sub-agent returned `result: "PARTIAL"` or `"FAILED"`, present the `issues
 - **Always build the briefing (Step 1.5) before delegating** — it is the key piece that reduces the sub-agent cost.
 - **Always delegate implementation to the sub-agent**. Do not replicate implementation logic or SDD artifact-apply logic here.
 - Even when artifacts are Spanish, implementation output is English-only: created file/folder names, source code, test code, identifiers, and code comments.
-- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 3, immediately invoke the **Skill tool** with `skill: "refacil:test"`. Do not describe it in text or wait for the user to type `/refacil:test`. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 3, immediately execute `/refacil:test`. Do not describe it in text or wait for the user to type it. (See `METHODOLOGY-CONTRACT.md §5`.)

package/skills/archive/SKILL.md

@@ -6,12 +6,16 @@ user-invocable: true
 
 # refacil:archive — Archive Completed Change
 
-This command archives completed SDD changes (bug fixes manually, regular changes via `refacil-sdd-ai sdd archive`), syncs `refacil-sdd/specs/`, and enforces team pre-verification checks.
+This command archives completed SDD changes through `refacil-sdd-ai sdd archive <changeName>`, syncs `refacil-sdd/specs/`, and enforces team pre-verification checks.
 
 **Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md`.
 
 ## Instructions
 
+### Step 0: Autopilot mode detection
+
+Try to read `refacil-sdd/.autopilot-active`. If the file exists and its `changeName` field matches the change being archived → `autopilotMode = true`, extract `taskReference` from the file. Otherwise `autopilotMode = false` (normal mode, ask user as usual).
+
 ### Step 1: Pre-verification checks
 
 Before archiving, run `refacil-sdd-ai sdd status <changeName> --json` and parse the JSON to get the change status.
@@ -20,7 +24,18 @@ Verify the change is truly complete:
 
 1. **Tasks completed**: Use the `tasksProgress` (or `tasks`) field from the JSON — verify that `tasks.pending === 0`. If there are incomplete tasks, inform the user and ask if they want to continue anyway.
 
-2. **Tests pass**: Resolve and run the test command according to `refacil-prereqs/METHODOLOGY-CONTRACT.md`. If there are failing tests, inform and ask if they want to continue.
+2. **Current `/refacil:test` evidence**: Do not re-run the test suite by default. Run `refacil-sdd-ai sdd get-memory <changeName> --json` and verify that:
+   - `memory.lastStep` is `test`, `verify`, or `review` (test evidence remains valid after later validation phases if it is still fresh).
+   - `memory.commandsRun` is present and non-empty.
+   - `memory.criteriaRun` is an array with at least one covered CA/CR criterion.
+   - `memory.touchedFiles`, when present, still covers the files currently changed for this SDD change.
+   - The evidence is fresh: no relevant changed file was modified after the recorded `/refacil:test` evidence. Use reliable timestamps, hashes, or an equivalent snapshot when available. If freshness cannot be proven, treat the evidence as stale.
+
+   If the evidence is current, archive may continue and should report `Tests: PASS (from /refacil:test evidence: <commandsRun>)`.
+
+   If evidence is missing or stale:
+   - `autopilotMode = false`: stop and ask the user whether to run `/refacil:test` now or explicitly continue without current test evidence. Do not silently run tests.
+   - `autopilotMode = true`: abort archiving with a clear error: `Cannot archive in autopilot: current /refacil:test evidence is missing or stale.` Do not ask the user and do not re-run tests.
 
 3. **Working tree scope hygiene**: Run `git status` and check whether there are files unrelated to the current change scope. It is expected to have uncommitted changes in this step. If unrelated files are detected, warn the user and ask whether to continue archiving anyway. Do not suggest commit in this step; commit/push decisions are handled in `refacil:up-code`.
 
@@ -31,57 +46,62 @@ Verify the change is truly complete:
    ```
    This verification is **mandatory and blocking** — it cannot be skipped.
 
-If any of checks 1-3 fail, inform the user but allow them to decide whether to continue.
+If any of checks 1-3 fail, inform the user but allow them to decide whether to continue, except missing/stale test evidence in autopilot mode, which is blocking.
 If check 4 fails, archiving cannot continue.
 
 ### Step 1.5: Request task reference(s) (traceability — mandatory)
 
-Before proceeding to archiving, ask the user for the task reference(s) associated with the change (URL, issue/ticket number, or short task name):
+- `autopilotMode = true`: use `taskReference` from `refacil-sdd/.autopilot-active` directly. Do NOT ask the user. Set `taskReferences = [taskReference]` and continue.
 
-```
-Task reference(s) associated with this change (URL, ticket number, or task name; if multiple, separate with commas):
-```
-
-**Rules:**
-- The user may enter one or multiple references separated by commas in a single message.
-- Accepted formats: URL (`https://tracker.company.com/TASK-123`), identifier (`TASK-123`, `INC-9001`), or short descriptive name (`ajuste checkout`).
-- Minimum validation rule for each reference (operational and mandatory):
-  - `URL`: starts with `http://` or `https://` and has at least one non-space character after the protocol.
-  - `identifier`: matches `^[A-Za-z][A-Za-z0-9_-]*-\d+$` (examples: `BP-4610`, `INC-9001`).
-  - `short name`: 3-80 characters, includes at least one letter, and is not only symbols/spaces.
-- If the user provides no reference (answers empty, "n", "no", "none", blank Enter), **block the archiving** and ask again:
-  ```
-  Cannot archive without at least one task reference.
-  Provide the task URL, identifier, or name that originated this change to continue.
-  ```
-- If the user provides a non-empty but invalid value (for example: `---`, `???`, `123`, `_`), **reject it** and ask again:
+- `autopilotMode = false` (normal): ask the user for the task reference(s) associated with the change (URL, issue/ticket number, or short task name):
   ```
-  Invalid task reference format.
-  Use one of: URL (https://...), identifier (ABC-123), or short task name (3-80 chars, includes letters).
+  Task reference(s) associated with this change (URL, ticket number, or task name; if multiple, separate with commas):
   ```
-- Repeat until at least one valid reference is received.
-- Save the references in `taskReferences` to use when writing `review.yaml` in the following steps.
+
+  **Rules:**
+  - The user may enter one or multiple references separated by commas in a single message.
+  - Accepted formats: URL (`https://tracker.company.com/TASK-123`), identifier (`TASK-123`, `INC-9001`), or short descriptive name (`checkout-adjustment`).
+  - Minimum validation rule for each reference (operational and mandatory):
+    - `URL`: starts with `http://` or `https://` and has at least one non-space character after the protocol.
+    - `identifier`: matches `^[A-Za-z][A-Za-z0-9_-]*-\d+$` (examples: `BP-4610`, `INC-9001`).
+    - `short name`: 3-80 characters, includes at least one letter, and is not only symbols/spaces.
+  - If the user provides no reference (answers empty, "n", "no", "none", blank Enter), **block the archiving** and ask again:
+    ```
+    Cannot archive without at least one task reference.
+    Provide the task URL, identifier, or name that originated this change to continue.
+    ```
+  - If the user provides a non-empty but invalid value (for example: `---`, `???`, `123`, `_`), **reject it** and ask again:
+    ```
+    Invalid task reference format.
+    Use one of: URL (https://...), identifier (ABC-123), or short task name (3-80 chars, includes letters).
+    ```
+  - Repeat until at least one valid reference is received.
+  - Save the references in `taskReferences` to use when writing `review.yaml` in the following steps.
 
 ### Step 2: Determine change type
 
 Inspect the change folder in `refacil-sdd/changes/`:
 
-- **It is a bug fix** if the folder name starts with `fix-` (created by `refacil:bug`).
-- **It is a regular change** in any other case (created by `refacil:propose`).
+- First inspect the artifact structure, then classify:
+  - **Full SDD artifact set present** (`proposal.md`, `specs.md`, `design.md`, and `tasks.md`) → **regular change**, even when the folder name starts with `fix-`.
+    - Example: `fix-seginf-20` containing `proposal.md` + `specs.md` + `design.md` + `tasks.md` → treat as **regular change** and follow Step 2B.
+  - **Minimal bug-fix artifact set** (`summary.md` exists and the full SDD artifact set is absent) → **bug fix**.
+    - Example: `fix-null-pointer-pay` containing only `summary.md` (and optionally `.review-passed`) → treat as **bug fix** and follow Step 2A.
+  - Any other incomplete or ambiguous structure → stop and report the missing artifacts; do not guess from the folder prefix alone.
 
 Depending on the type, follow the corresponding step:
 
 ### Step 2A: Bug fix → Archive with native CLI
 
-Bug fixes only contain `summary.md` (and optionally `.review-passed`). The CLI `refacil-sdd-ai sdd archive` handles the folder move internally with its own `findProjectRoot()`, so there is no need for manual `mv` — use the CLI for the move, and only write specs/review.yaml manually (the CLI does not cover those).
+Minimal bug fixes only contain `summary.md` (and optionally `.review-passed`) and do not include the full SDD artifact set. The CLI `refacil-sdd-ai sdd archive` handles the folder move internally with its own `findProjectRoot()`, so use the CLI for the move, and only write specs/review.yaml yourself (the CLI does not cover those).
 
 0. **Read artifacts before archiving**: read `summary.md` and `.review-passed` from `refacil-sdd/changes/[fix-name]/` **now**, before the CLI moves the folder. The archived path will be different.
 
-1. **Archive with the CLI** — let the CLI handle the move (it automatically deletes memory.yaml if present):
+1. **Archive with the CLI** — let the CLI handle the move (it preserves `memory.yaml` by moving the complete change directory):
    ```bash
    refacil-sdd-ai sdd archive [fix-name]
    ```
-   The CLI resolves the repo root internally, deletes memory.yaml if present, moves the folder to `refacil-sdd/changes/archive/[ISO-date]-[fix-name]/`, and exits with code 0 on success. If it exits non-zero, stop and report the error to the user.
+   The CLI resolves the repo root internally, **skips spec sync** for `fix-*` (no `specs.md` in the change folder), preserves `memory.yaml` if present, moves the folder to `refacil-sdd/changes/archive/[ISO-date]-[fix-name]/`, and exits with code 0 on success. If it exits non-zero, stop and report the error to the user.
 
 2. **Document in specs**: using the content read in step 0, create an individual spec at `$(git rev-parse --show-toplevel)/refacil-sdd/specs/[descriptive-name]/spec.md`.
 
@@ -124,17 +144,21 @@ Bug fixes only contain `summary.md` (and optionally `.review-passed`). The CLI `
 
 ### Step 2B: Regular change → Archive with native CLI
 
-The spec and review evidence are written **before** running the CLI archive command, while the artifacts are still at their original paths. The CLI only moves the folder — it never syncs specs.
-
 `refacil-sdd-ai sdd archive` normalizes the provided `changeName` to lowercase before validation/path resolution. Prefer lowercase names for consistency across commands and records.
 
-1. **Sync spec to `refacil-sdd/specs/` (before archiving)**:
-   - Read `refacil-sdd/changes/<changeName>/specs.md` (and all `.md` under `specs/` if that subfolder exists).
-   - Determine the spec folder name: use `<changeName>` unless a more descriptive name is clearly better.
-   - If `refacil-sdd/specs/<specName>/spec.md` already exists, integrate the changes (ADDED → add, MODIFIED → update, REMOVED → delete sections).
-   - If it does NOT exist, create `refacil-sdd/specs/<specName>/spec.md` with the content derived from `specs.md` (convert acceptance/rejection criteria into Requirements + Scenarios format).
+**Spec sync (CLI — mandatory, same language as change artifacts)**:
+
+- `sdd archive` runs **`refacil-sdd-ai sdd sync-spec <changeName>` automatically** before moving the folder.
+- The CLI copies CA/CR blocks from `specs.md` or `specs/**/*.md` into `refacil-sdd/specs/<changeName>/spec.md` using catalog headings that match the change artifact language (Spanish vs English section titles — see `sdd sync-spec` / METHODOLOGY-CONTRACT).
+- **Do NOT translate or rewrite** the criteria in another language. Structural conversion only (Gherkin keywords stay as written in the source artifacts).
+- Language is detected from the change proposal heading marker (Spanish vs English template), not invented by the agent.
+- To sync without archiving: `refacil-sdd-ai sdd sync-spec <changeName>`.
+
+1. **Verify spec sync output** (after archive, or run `sync-spec` manually first):
+   - Confirm `refacil-sdd/specs/<changeName>/spec.md` exists and matches the language of the archived change specs.
+   - Do **not** replace CLI output with an agent-written English summary.
 
-2. **Persist review evidence (before archiving)**:
+2. **Persist review evidence (before or after archive)**:
    - Read `refacil-sdd/changes/<changeName>/.review-passed` (dotfile — use `ls -la` or read by explicit path, not directory listing).
    - Create/update `refacil-sdd/specs/<specName>/review.yaml` with its fields plus `taskReferences` from Step 1.5:
      ```yaml
@@ -150,7 +174,7 @@ The spec and review evidence are written **before** running the CLI archive comm
      ```
    - If `review.yaml` already exists, update only the fields that changed without removing others.
 
-3. **Run the CLI archive**: `refacil-sdd-ai sdd archive <changeName>` — the CLI automatically deletes memory.yaml if present, then moves the change to `refacil-sdd/changes/archive/<date>-<changeName>/`.
+3. **Run the CLI archive**: `refacil-sdd-ai sdd archive <changeName>` — sync-spec, preserves `memory.yaml` if present, then moves the complete change directory to `refacil-sdd/changes/archive/<date>-<changeName>/`.
 4. Verify the command completed successfully (exit 0) and the original folder no longer exists.
 
 5. Continue to **Step 3**.
@@ -162,7 +186,7 @@ The goal is for `refacil-sdd/specs/` to document how the system works TODAY.
 Before showing the summary, run a **final cleanup verification** (applies to both bug fixes and regular changes):
 
 - `$(git rev-parse --show-toplevel)/refacil-sdd/changes/[original-name]/` **must NOT exist** (only the archived version must survive in `refacil-sdd/changes/archive/...`).
-- If the source folder survived for any reason (failed move, partial copy, interrupted move), explicitly delete it with `rm -rf "$(git rev-parse --show-toplevel)/refacil-sdd/changes/[original-name]"` before confirming to the user.
+- If the source folder survived for any reason (failed move, partial copy, interrupted move), do not claim success. Stop, report the residue path, and ask the user whether to remove it after they inspect the archived copy.
 
 ```
 === Change archived ===
@@ -171,25 +195,27 @@ Before showing the summary, run a **final cleanup verification** (applies to bot
  Location: refacil-sdd/changes/archive/[date]-[name]/
  Original folder deleted: YES
  Specs synced: YES
- Tests: PASS
+ Tests: PASS (from /refacil:test evidence)
 
  The change has been completed and archived successfully.
 ```
 
 ### Step 4: Recommend pushing the code
 
-After confirming the archiving, recommend the user push the changes to the remote:
+After confirming the archiving:
 
-```
-The next step is to push the change and create the PR.
-Do you want me to continue with /refacil:up-code?
-```
+- `autopilotMode = false` (normal): ask the user:
+  ```
+  The next step is to push the change and create the PR.
+  Do you want me to continue with /refacil:up-code?
+  ```
+- `autopilotMode = true`: proceed to `/refacil:up-code` immediately without asking.
 
 ## Rules
 
 - Always verify completeness before archiving
-- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 4, immediately invoke the **Skill tool** with `skill: "refacil:up-code"`. Do not describe it in text or wait for the user to type `/refacil:up-code`. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 4, immediately execute `/refacil:up-code`. Do not describe it in text or wait for the user to type it. (See `METHODOLOGY-CONTRACT.md §5`.)
 - Spec synchronization is MANDATORY in the Refacil methodology
 - The `.review-passed` metadata must be persisted separately in YAML (`review.yaml`) inside each spec folder
 - Do not delete artifacts, only move them to archive/ for traceability
-- **The original folder in `refacil-sdd/changes/[name]/` must NOT survive archiving** — neither for bug fixes (Step 2A) nor for regular changes (Step 2B). Use `git mv` or `mv` (not `cp -r`) and verify explicitly. If residue remains, delete it with `rm -rf` before Step 3.
+- **The original folder in `refacil-sdd/changes/[name]/` must NOT survive archiving** — neither for bug fixes (Step 2A) nor for regular changes (Step 2B). Use the native CLI move and verify explicitly. If residue remains, stop and report it instead of performing an automatic destructive cleanup.

package/skills/ask/SKILL.md

@@ -53,23 +53,56 @@ This framing increases response quality and reduces back-and-forth.
 When the question is about cross-repo integration contracts, draft the `--text` using this minimal template:
 
 ```text
-integrationPoint: <endpoint/event/queue + direction X->Y or Y->X>
-inputContract: <required/optional fields + key validation rules>
-outputContract: <expected output/status/errors>
-compatibility: <version/flags/env constraints or "unknown">
-sourceOfTruthRequest: <where to confirm in destination repo>
-question: <concrete doubt to resolve>
+integrationPoint: [endpoint/event/queue + direction X->Y or Y->X]
+inputContract: [required/optional fields + key validation rules]
+outputContract: [expected output/status/errors]
+compatibility: [version/flags/env constraints or "unknown"]
+sourceOfTruthRequest: [where to confirm in destination repo]
+question: [concrete doubt to resolve]
 ```
 
 If some fields are unknown, send `unknown` explicitly — do not invent values.
 
+## Safe bus text delivery
+
+**Use `--text` for simple messages** (no special characters, single-line):
+```bash
+refacil-sdd-ai bus ask --to [destination] --text "Simple question here"
+```
+
+**Do NOT use `<` or `>` inside `--text`** — shells may interpret them as redirection operators and truncate or discard the message.
+
+For messages containing `<`, `>`, `|`, newlines, or other special characters, use `--from-env`:
+
+**PowerShell (Windows)**:
+```powershell
+$env:BUS_TEXT = "integrationPoint: POST /api/pay -> processor`ninputContract: amount<number>, currency<string>"
+refacil-sdd-ai bus ask --to [destination] --from-env BUS_TEXT
+Remove-Item Env:BUS_TEXT
+```
+
+**bash (inline, preferred — automatic cleanup)**:
+```bash
+BUS_TEXT="integrationPoint: POST /api/pay -> processor
+inputContract: amount<number>" refacil-sdd-ai bus ask --to [destination] --from-env BUS_TEXT
+```
+
+**bash (export + unset alternative)**:
+```bash
+export BUS_TEXT="message with <special> chars"
+refacil-sdd-ai bus ask --to [destination] --from-env BUS_TEXT
+unset BUS_TEXT
+```
+
+> Note: the CLI cannot perform cleanup itself — it runs as a child process and cannot modify the parent shell's environment. Cleanup (`Remove-Item` / `unset`) is the responsibility of the invoking script or shell.
+
 ### Step 2: Decide whether to use `--wait`
 
 Two modes:
 
 **Blocking mode (recommended when you need the response to continue)**:
 ```bash
-refacil-sdd-ai bus ask --to <destination> --text "<question>" --wait 180
+refacil-sdd-ai bus ask --to [destination] --text "[question]" --wait 180
 ```
 - The CLI blocks until it receives the response or the timeout passes (default suggested: 60-180s)
 - If the other side is in `/refacil:attend`, the response comes back automatically
@@ -78,7 +111,7 @@ refacil-sdd-ai bus ask --to <destination> --text "<question>" --wait 180
 
 **Fire-and-forget mode**:
 ```bash
-refacil-sdd-ai bus ask --to <destination> --text "<question>"
+refacil-sdd-ai bus ask --to [destination] --text "[question]"
 ```
 - Does not block; returns immediately after sending
 - Use it when you do not know if the other side is active or you do not need the response now
@@ -103,3 +136,5 @@ Use `Bash` with the chosen command.
 - If you **agreed** with another session that they will change their repo, they must use **`/refacil:propose`** there and **notify you via bus** when done; if they request changes from you, you do the same here. Full convention: `refacil-prereqs/BUS-CROSS-REPO.md`.
 - **`ask`s that are change requests** must be **substantive in scope** (Step 1.5): the recipient already uses the methodology; do not repeat the guide in the text. Do not use the bus to request opaque quick fixes when the impact requires SDD-AI.
 - For cross-repo contract clarifications, prefer Step 1.7 template. The same structure should also be expected in replies to ease retries.
+- **Cross-repo contracts, bug reports, and actionable content ALWAYS use `bus ask --to SESSION`**, never `bus say`. `say` is a broadcast-only announcement with no delivery guarantee for late-joining sessions and no inbox visibility. If the content is extensive, split it into numbered parts, each as an independent `ask`.
+- Do not use `<` or `>` inside `--text` arguments. Use `--from-env` instead (see "Safe bus text delivery" above).