refacil-sdd-ai 4.5.5 → 4.5.8

package/README.md

@@ -153,7 +153,7 @@ All invoked as `/refacil:<name>` in Claude Code, Cursor, or OpenCode.
 | `/refacil:test` | Generate unit tests from the artifacts |
 | `/refacil:verify` | Validate implementation vs specs (with optional autofix) |
 | `/refacil:review` | Quality checklist, emits `.review-passed` if approved |
-| `/refacil:archive` | Archive the completed change + sync specs (requests Jira links) |
+| `/refacil:archive` | Archive the completed change + sync specs (requests task references) |
 | `/refacil:up-code` | Commit + push + PR (runs review if missing) |
 | `/refacil:bug` | Full bugfix flow with regression tests |
 | `/refacil:update` | Detect and apply pending methodology migrations to the current repo |
@@ -259,7 +259,7 @@ From there, the full cycle is:
 - For features/improvements: the CLI moves artifacts to `archive/` and extracts `.review-passed` fields to `review.yaml` inside each affected spec.
 - For bugs: manual archiving, creates `refacil-sdd/specs/fix-*/spec.md` in standard format + `review.yaml`.
 - A single branch can accumulate multiple bugs, each in its own independent `fix-*/` folder.
-- `/refacil:archive` always requests one or more **Jira links** associated with the change before proceeding. Links are stored in `review.yaml` under the `jiraTasks` field (YAML list). This field is mandatory — archiving does not proceed until the user provides at least one link.
+- `/refacil:archive` always requests one or more **task references** associated with the change before proceeding. Accepted formats: URL, ticket/issue identifier, or task name. References are stored in `review.yaml` under the `taskReferences` field (YAML list). This field is mandatory — archiving does not proceed until the user provides at least one reference.
 
 ---
 

package/lib/commands/sdd.js

@@ -62,6 +62,47 @@ function validateChangeName(name) {
   return { valid: true };
 }
 
+function resolveExistingChangeName(projectRoot, inputName) {
+  if (!inputName || typeof inputName !== 'string') {
+    return { ok: false, reason: 'El nombre del cambio no puede estar vacío.' };
+  }
+
+  const normalizedInput = inputName.trim();
+  const lowerInput = normalizedInput.toLowerCase();
+  const changesDir = path.join(projectRoot, 'refacil-sdd', 'changes');
+
+  // Keep backward-compatible behavior when directory doesn't exist yet.
+  if (!fs.existsSync(changesDir)) {
+    return { ok: true, name: lowerInput };
+  }
+
+  const entries = fs.readdirSync(changesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== 'archive')
+    .map((e) => e.name);
+
+  if (entries.includes(normalizedInput)) {
+    return { ok: true, name: normalizedInput };
+  }
+
+  if (entries.includes(lowerInput)) {
+    return { ok: true, name: lowerInput };
+  }
+
+  const ciMatches = entries.filter((n) => n.toLowerCase() === lowerInput);
+  if (ciMatches.length === 1) {
+    return { ok: true, name: ciMatches[0] };
+  }
+
+  if (ciMatches.length > 1) {
+    return {
+      ok: false,
+      reason: `Nombre de cambio ambiguo: '${inputName}'. Coincidencias: ${ciMatches.join(', ')}`,
+    };
+  }
+
+  return { ok: true, name: lowerInput };
+}
+
 function autoMigrateOpenspec(root) {
   const oldDir = path.join(root, 'openspec');
   const newDir = path.join(root, 'refacil-sdd');
@@ -180,7 +221,15 @@ function cmdNewChange(argv, projectRoot) {
 
 function cmdArchive(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
+
+  autoMigrateOpenspec(projectRoot);
+  const resolved = resolveExistingChangeName(projectRoot, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
 
   const validation = validateChangeName(name);
   if (!validation.valid) {
@@ -188,8 +237,6 @@ function cmdArchive(argv, projectRoot) {
     process.exit(1);
   }
 
-  autoMigrateOpenspec(projectRoot);
-
   const sourceDir = path.join(projectRoot, 'refacil-sdd', 'changes', name);
   if (!fs.existsSync(sourceDir)) {
     console.error(`No existe el cambio '${name}' en refacil-sdd/changes/${name}/`);
@@ -222,14 +269,21 @@ function cmdArchive(argv, projectRoot) {
 
 function cmdSetMemory(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
 
-  if (!name) {
+  if (!rawName) {
     console.error('Uso: refacil-sdd-ai sdd set-memory <nombre-cambio> [--last-step <value>] [--stack-detected <value>] [--touched-files <csv>] [--commands-run <value>] [--criteria-run <csv>]');
     process.exit(1);
   }
 
   const root = projectRoot;
+  autoMigrateOpenspec(root);
+  const resolved = resolveExistingChangeName(root, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
 
   // Guard: ensure the change directory exists before any file operation
   const changeDir = path.join(root, 'refacil-sdd', 'changes', name);
@@ -274,15 +328,22 @@ function cmdSetMemory(argv, projectRoot) {
 
 function cmdGetMemory(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
   const wantJson = args.json === true;
 
-  if (!name) {
+  if (!rawName) {
     console.error('Uso: refacil-sdd-ai sdd get-memory <nombre-cambio> [--json]');
     process.exit(1);
   }
 
   const root = projectRoot;
+  autoMigrateOpenspec(root);
+  const resolved = resolveExistingChangeName(root, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
   const memoryPath = path.join(root, 'refacil-sdd', 'changes', name, 'memory.yaml');
 
   if (!fs.existsSync(memoryPath)) {
@@ -309,14 +370,21 @@ function cmdGetMemory(argv, projectRoot) {
 
 function cmdSetReviewFails(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
 
-  if (!name) {
+  if (!rawName) {
     console.error('Uso: refacil-sdd-ai sdd set-review-fails <nombre-cambio> --files <csv>');
     process.exit(1);
   }
 
   const root = projectRoot;
+  autoMigrateOpenspec(root);
+  const resolved = resolveExistingChangeName(root, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
   const changeDir = path.join(root, 'refacil-sdd', 'changes', name);
   if (!fs.existsSync(changeDir)) {
     console.error(`No existe el cambio '${name}' en refacil-sdd/changes/${name}/`);
@@ -334,14 +402,21 @@ function cmdSetReviewFails(argv, projectRoot) {
 
 function cmdClearReviewFails(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
 
-  if (!name) {
+  if (!rawName) {
     console.error('Uso: refacil-sdd-ai sdd clear-review-fails <nombre-cambio>');
     process.exit(1);
   }
 
   const root = projectRoot;
+  autoMigrateOpenspec(root);
+  const resolved = resolveExistingChangeName(root, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
   const reviewFailsPath = path.join(root, 'refacil-sdd', 'changes', name, '.review-last-fails.json');
 
   if (fs.existsSync(reviewFailsPath)) {
@@ -392,15 +467,21 @@ function cmdList(argv, projectRoot) {
 
 function cmdStatus(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
   const wantJson = args.json === true;
 
-  if (!name) {
+  if (!rawName) {
     console.error('Uso: refacil-sdd-ai sdd status <nombre-cambio> [--json]');
     process.exit(1);
   }
 
   autoMigrateOpenspec(projectRoot);
+  const resolved = resolveExistingChangeName(projectRoot, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
 
   const changeDir = path.join(projectRoot, 'refacil-sdd', 'changes', name);
   if (!fs.existsSync(changeDir)) {
@@ -481,9 +562,9 @@ function cmdStatus(argv, projectRoot) {
 
 function cmdMarkReviewed(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
 
-  if (!name) {
+  if (!rawName) {
     console.error('Uso: refacil-sdd-ai sdd mark-reviewed <nombre-cambio> --verdict <verdict> --summary "<resumen>" [--fail-count N] [--preexisting-count N] [--blockers]');
     process.exit(1);
   }
@@ -499,6 +580,12 @@ function cmdMarkReviewed(argv, projectRoot) {
   }
 
   autoMigrateOpenspec(projectRoot);
+  const resolved = resolveExistingChangeName(projectRoot, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
 
   const changeDir = path.join(projectRoot, 'refacil-sdd', 'changes', name);
   if (!fs.existsSync(changeDir)) {
@@ -522,9 +609,9 @@ function cmdMarkReviewed(argv, projectRoot) {
 
 function cmdTasksUpdate(argv, projectRoot) {
   const args = parseArgs(argv);
-  const name = args._positional[0];
+  const rawName = args._positional[0];
 
-  if (!name) {
+  if (!rawName) {
     console.error('Uso: refacil-sdd-ai sdd tasks-update <nombre-cambio> --task N --done');
     process.exit(1);
   }
@@ -541,6 +628,12 @@ function cmdTasksUpdate(argv, projectRoot) {
   }
 
   autoMigrateOpenspec(projectRoot);
+  const resolved = resolveExistingChangeName(projectRoot, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
 
   const tasksFile = path.join(projectRoot, 'refacil-sdd', 'changes', name, 'tasks.md');
   if (!fs.existsSync(tasksFile)) {
@@ -661,4 +754,4 @@ function handleSdd(sub, argv, projectRoot) {
   }
 }
 
-module.exports = { handleSdd, parseArgs, autoMigrateOpenspec, validateChangeName, findProjectRoot };
+module.exports = { handleSdd, parseArgs, autoMigrateOpenspec, validateChangeName, resolveExistingChangeName, findProjectRoot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.5.5",
+  "version": "4.5.8",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor and OpenCode",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/archive/SKILL.md

@@ -22,7 +22,7 @@ Verify the change is truly complete:
 
 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.
 
-3. **No pending files**: Run `git status` and verify if there are uncommitted changes related to the feature. If there are, suggest committing before archiving.
+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`.
 
 4. **Review approved (blocking)**: Verify that the `.review-passed` file exists in the change folder (`refacil-sdd/changes/[change-name]/.review-passed`) following **`METHODOLOGY-CONTRACT.md` §8** (dotfile; do not conclude by listings without dotfiles). If it does NOT exist, **stop the archiving** and inform the user:
    ```
@@ -34,23 +34,33 @@ Verify the change is truly complete:
 If any of checks 1-3 fail, inform the user but allow them to decide whether to continue.
 If check 4 fails, archiving cannot continue.
 
-### Step 1.5: Request Jira links (traceability — mandatory)
+### Step 1.5: Request task reference(s) (traceability — mandatory)
 
-Before proceeding to archiving, ask the user for the Jira links associated with the change:
+Before proceeding to archiving, ask the user for the task reference(s) associated with the change (URL, issue/ticket number, or short task name):
 
 ```
-Jira link(s) associated with this change (if multiple, separate with commas):
+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 links separated by commas in a single message.
-- If the user provides no link (answers empty, "n", "no", "none", blank Enter), **block the archiving** and ask again:
+- 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 Jira link.
-  Provide the link to the task that originated this change to continue.
+  Cannot archive without at least one task reference.
+  Provide the task URL, identifier, or name that originated this change to continue.
   ```
-- Repeat until at least one valid URL is received.
-- Save the links in `jiraTasks` to use when writing `review.yaml` in the following steps.
+- 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
 
@@ -75,7 +85,7 @@ Bug fixes only contain `summary.md` (and optionally `.review-passed`). The CLI `
 
 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`.
 
-   **Spec folder name**: Use a short, clear kebab-case description of the bug (e.g. `fix-session-timeout-redis`, `fix-null-pointer-payment-callback`). **Do NOT use ticket IDs** (REF-123, JIRA-456, etc.) — the name must be descriptive so `/refacil:explore` can find and understand the fix without external context.
+   **Spec folder name**: Use a short, clear kebab-case description of the bug (e.g. `fix-session-timeout-redis`, `fix-null-pointer-payment-callback`). **Do NOT use ticket IDs** (REF-123, TASK-456, etc.) — the name must be descriptive so `/refacil:explore` can find and understand the fix without external context.
 
    Content of `spec.md` (Refacil SDD spec layout):
    ```markdown
@@ -97,7 +107,7 @@ Bug fixes only contain `summary.md` (and optionally `.review-passed`). The CLI `
    - **THEN** the system SHALL [normal behavior without regression]
    ```
 
-3. **Persist review metadata separately**: create `$(git rev-parse --show-toplevel)/refacil-sdd/specs/[descriptive-name]/review.yaml` with the fields from `.review-passed` plus the Jira links from Step 1.5:
+3. **Persist review metadata separately**: create `$(git rev-parse --show-toplevel)/refacil-sdd/specs/[descriptive-name]/review.yaml` with the fields from `.review-passed` plus the task references from Step 1.5:
    ```yaml
    verdict: APROBADO|APROBADO CON OBSERVACIONES
    date: 2026-04-10T00:00:00.000Z
@@ -105,8 +115,9 @@ Bug fixes only contain `summary.md` (and optionally `.review-passed`). The CLI `
    summary: "..."
    failCount: 0
    blockers: false
-   jiraTasks:
-     - https://your-company.atlassian.net/browse/REF-123
+   taskReferences:
+     - https://tracker.company.com/TASK-123
+     - TASK-123
    ```
 
 4. Continue to **Step 3**.
@@ -115,6 +126,8 @@ Bug fixes only contain `summary.md` (and optionally `.review-passed`). The 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.
@@ -123,7 +136,7 @@ The spec and review evidence are written **before** running the CLI archive comm
 
 2. **Persist review evidence (before archiving)**:
    - 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 `jiraTasks` from Step 1.5:
+   - Create/update `refacil-sdd/specs/<specName>/review.yaml` with its fields plus `taskReferences` from Step 1.5:
      ```yaml
      verdict: APROBADO|APROBADO CON OBSERVACIONES
      date: 2026-04-10T00:00:00.000Z
@@ -131,8 +144,9 @@ The spec and review evidence are written **before** running the CLI archive comm
      summary: "..."
      failCount: 0
      blockers: false
-     jiraTasks:
-       - https://your-company.atlassian.net/browse/REF-123
+     taskReferences:
+       - https://tracker.company.com/TASK-123
+       - TASK-123
      ```
    - If `review.yaml` already exists, update only the fields that changed without removing others.
 

package/skills/prereqs/METHODOLOGY-CONTRACT.md

@@ -127,6 +127,8 @@ If the user does not request detail, use concise mode.
 
 - `archive` requires `.review-passed` as a blocking precondition (verify existence according to **§8**).
 - When archiving regular changes (proposal-driven flow), the `.review-passed` metadata must be persisted in `refacil-sdd/specs/`.
+- `archive` must request and persist at least one task reference for traceability. Accepted formats: URL, ticket/issue identifier, or short task name.
+- The recommended field in `review.yaml` is `taskReferences` (YAML list). Do not enforce provider-specific fields such as `jiraTasks`.
 - The recommended format is `review.yaml` inside each affected spec folder.
 - If it cannot be reliably mapped to specific specs, record the evidence in `refacil-sdd/specs/review-metadata.yaml`.
 

package/skills/up-code/SKILL.md

@@ -83,15 +83,17 @@ Run `git push -u origin [current-branch]` to push the changes.
    Which branch do you want to create the PR to? (recommended: testing)
    ```
 
-   If the user indicates a different branch than `testing`, verify it exists on the remote with `git branch -r | grep <indicated-branch>` before generating the link. If it does not exist, inform the user and ask them to confirm or correct the name.
+  If the user indicates a different branch than `testing`, verify it exists on the remote by inspecting `git branch -r` output before generating the link. If it does not exist, inform the user and ask them to confirm or correct the name.
 
-3. Get the remote repository URL with `git remote get-url origin` and determine the hosting to generate the correct link:
+3. Get the remote repository URL with `git remote get-url origin` and detect the VCS hosting used by this repository to generate the correct PR/MR link:
    - **GitHub** (url contains `github.com`): `https://github.com/[owner]/[repo]/compare/[target-branch]...[current-branch]?expand=1`
-   - **Bitbucket** (url contains `bitbucket.org`): `https://bitbucket.org/[workspace]/[repo]/pull-requests/new?source=[current-branch]&dest=[target-branch]`
-   - If hosting cannot be determined, show both formats for the user to choose.
-   - Note: for SSH URLs (`git@github.com:owner/repo.git` or `git@bitbucket.org:workspace/repo.git`), extract owner/workspace and repo from the path after `:`.
+   - **Bitbucket Cloud** (url contains `bitbucket.org`): `https://bitbucket.org/[workspace]/[repo]/pull-requests/new?source=[current-branch]&dest=[target-branch]`
+   - **GitLab** (url contains `gitlab.` or `gitlab.com`): `https://[gitlab-host]/[group]/[repo]/-/merge_requests/new?merge_request[source_branch]=[current-branch]&merge_request[target_branch]=[target-branch]`
+   - **Azure DevOps** (url contains `dev.azure.com` or `visualstudio.com`): build the "create PR" URL for the detected project/repo using source and target branches.
+   - For SSH remotes (`git@host:group/repo.git`), extract host/namespace/repo from the segment after `:`.
+   - If hosting cannot be determined, do not assume a provider: show the detected remote URL and ask the user which platform is used before generating the final PR/MR link.
 
-4. Show the link to the user and recommend PR to `testing`:
+4. Show the generated link (provider-specific) to the user and recommend PR to `testing`:
 ```
  Create your PR here: [link]