Release FixMap v0.8.9 reliability sweep

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Question or workflow idea
+    url: https://github.com/aryamthecodebreaker/FixMap/discussions
+    about: Ask usage questions, share examples, or discuss workflow ideas.
   - name: Security vulnerability
     url: https://github.com/aryamthecodebreaker/FixMap/security/advisories/new
     about: Report security-sensitive issues privately.

.github/workflows/ci.yml

@@ -2,18 +2,55 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 45
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: 24
           cache: npm
       - run: npm ci
       - run: npm run ci
+
+  compatibility:
+    name: Node ${{ matrix.node }} on ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            node: "20.11"
+          - os: ubuntu-latest
+            node: "22"
+          - os: windows-latest
+            node: "24"
+          - os: macos-latest
+            node: "24"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test

.github/workflows/external-eval.yml

@@ -10,11 +10,12 @@ permissions:
 
 jobs:
   evaluate:
+    if: github.event_name != 'schedule' || github.repository == 'aryamthecodebreaker/FixMap'
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: 24
           cache: npm

.github/workflows/publish.yml

@@ -14,8 +14,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
-  id-token: write
+  contents: read
 
 concurrency:
   group: fixmap-release
@@ -28,6 +27,9 @@ env:
 
 jobs:
   publish:
+    permissions:
+      contents: write
+      id-token: write
     runs-on: ubuntu-latest
     timeout-minutes: 45
     steps:
@@ -42,7 +44,7 @@ jobs:
           fi
           echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
@@ -176,7 +178,7 @@ jobs:
             exit "$STATUS"
           fi
 
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
           node-version: 24
           cache: npm

CHANGELOG.md

@@ -6,6 +6,47 @@ Accuracy figures inside a released entry are the numbers measured **at that rele
 left as written. The current numbers live on the [evidence page](https://usefixmap.vercel.app/evidence),
 which is generated from the recorded results rather than transcribed by hand.
 
+## 0.8.9 - 2026-08-11
+
+### Added
+
+- `fixmap setup` installs a discoverable `/fixmap` command for Claude Code, Cursor, GitHub Copilot, and Agent Skills; invoking it without a task opens the complete feature catalog. `fixmap features` exposes the same catalog directly.
+- `fixmap validate <report.json>` checks the versioned report contract, while `--fail-on warning` and the Action's `fail-on: warning` provide an opt-in strict Verify gate.
+- Plan, Explain, MCP, and the Action expose a visible fresh-scan path with `--no-cache`/`noCache`, and cache hits now report age with bounded expiry and eviction.
+
+### Fixed
+
+- Ranking, grounding, file mentions, definition detection, import proximity, clustering, confidence, risk vocabulary, diff evidence, exact literals, Unicode text, inflections, typographic quotes, and generated/backup/configuration heuristics were corrected across the complete #500-#627 issue sweep.
+- Repository mapping now handles nested package-manager lockfiles, conflicting roots, Windows and absolute exclusion paths, large ignore lists, tracked dirty cache states, BOM-less UTF-16 task files, oversized diffs, more source extensions, and language/test routing for C#, Java, PHP, Ruby, Go, Rust, Python, and JavaScript ecosystems.
+- Explain, Compare, Verify, Validate, Doctor, remote repository acquisition, CLI parsing/output, MCP schemas, and copy-paste commands now fail clearly and preserve safe paths instead of silently accepting ambiguous or malformed state.
+- GitHub Action comments, outputs, and job summaries stay within platform limits; API errors, pagination, permissions, credentials, Markdown, temporary clones, and generated bundle/metadata drift are handled defensively.
+
+### Security and release engineering
+
+- CI is least-privilege, timeout-bounded, non-duplicating, immutable-action pinned, full-tree audited, non-mutating, and configured for Node 20.11/22 plus Windows and macOS compatibility coverage.
+- The publish workflow scopes write/OIDC permission to the release job and verifies the exact main commit, version metadata, npm packages, clean global install, MCP Registry entry, and GitHub Release before succeeding.
+
+### Website and documentation
+
+- The website uses a restrained editorial product system with clearer navigation, evidence, metadata, copy feedback, visibility-safe motion, and an honest interactive demo instead of synthetic marketing presentation.
+- README and the npm package documentation now contain the full FixMap feature catalog, `/fixmap` setup, exclusion syntax, cache/report compatibility, Action controls, and public evidence boundaries.
+
+### Evidence
+
+- The release ledger maps all 126 open GitHub issues in #500-#627 (excluding already-closed #542 and #599) plus every item in the attached 30-finding review to a resolution and verification source.
+- External, held-out, adversarial, BM25/lexical/path baselines, savings, rendered examples, package smoke tests, and the 1,000-file scan gate were regenerated and checked. The held-out evidence continues to state plainly where BM25 leads FixMap.
+
+### Installation
+
+```bash
+npm install --global @aryam/fixmap@0.8.9
+fixmap doctor
+fixmap setup
+fixmap features
+```
+
+The release is complete only when the exact main commit is tagged `v0.8.9`, npm and MCP Registry serve 0.8.9, the GitHub release and Action tag resolve to that commit, production serves the matching website, and every public smoke check passes.
+
 ## 0.8.8 - 2026-08-08
 
 ### Added

README.md

@@ -33,6 +33,14 @@ For a one-off trial:
 npx -y @aryam/fixmap@latest plan --issue https://github.com/chalk/chalk/issues/624
 ```
 
+Install a discoverable `/fixmap` command for Claude Code, Cursor, GitHub Copilot, and Agent Skills:
+
+```bash
+fixmap setup
+```
+
+Type `/fixmap` with no task to see the full feature menu, or run `fixmap features` in a terminal. Use `fixmap setup --agent <name>` to install one integration, and `--force` only after reviewing an existing customized command.
+
 FixMap fetches a public task, infers its repository, scans a temporary isolated checkout, and removes it when the report is complete. Local repository analysis never uploads source.
 
 ## Everyday workflow
@@ -61,42 +69,56 @@ Verify the completed diff against the saved plan:
 fixmap verify --report plan.json --diff main...HEAD
 ```
 
-Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked` when new files should count as changes, `--exclude` or `.fixmapignore` to focus the map, and `--no-cache` to force a fresh scan. Run `fixmap --help` for the complete command reference.
+Validate a saved report before another tool consumes it:
+
+```bash
+fixmap validate plan.json
+```
+
+Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked` when new files should count as changes, `--exclude` or `.fixmapignore` to focus the map, and `--no-cache` to force a fresh scan. Add `--fail-on warning` to Verify when advisory findings must fail CI. Run `fixmap --help` for the complete command reference.
 
 ## Complete feature catalog
 
 ### Inputs and repository mapping
 
-- Accepts a public GitHub issue or pull-request URL, plain task text, a UTF-8 `--issue-file`, or task text from stdin.
+- Accepts a public GitHub issue or pull-request URL, plain task text, a UTF-8 or UTF-16 `--issue-file` (including common BOM-less Windows UTF-16 files), or task text from stdin.
 - Normalizes supported browser and GitHub API issue URLs, including `www`, query strings, and fragments, while rejecting credentials, lookalike hosts, ports, and unsafe encoded paths.
 - Scans the current checkout, another local path, a `file://` URL, or an isolated checkout of a public GitHub repository.
 - Maps `--diff <spec>`, `--base`/`--head`, or the current `--working-tree`; untracked changes remain opt-in with `--include-untracked`.
-- Reuses repository scans only when the repository root, commit, status, and binary diff are identical. `cache-hit` reports reuse, `--no-cache` bypasses it, and `FIXMAP_CACHE_DIR` moves the OS cache.
-- Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package.
+- Reuses raw repository scans only when the repository root, commit, status, and binary diff are identical. Task text, `--limit`, and exclusion rules are applied after that scan, so changing them can safely reuse the same cached files while still producing a newly ranked and filtered report; Compare scans the current plan, while Verify validates its supplied report against a fresh or exact-state repository map. `cache-hit` reports reuse and scan age, entries expire after seven days, and `FIXMAP_CACHE_DIR` moves the OS cache. Force a fresh scan with CLI `--no-cache`, MCP `noCache: true`, or Action `no-cache: true`.
+- Keeps the current `--issue-file`, `--compare`, `--report`, and `--output` artifacts out of repository ranking, change detection, and cache invalidation, so FixMap never recommends its own report as the fix site.
+- Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package. When the root is silent it can infer an agreed nested lockfile, while conflicting root declarations produce a diagnostic instead of silently choosing.
 
 ### Plan and ranking
 
-- Ranks source, test, configuration, documentation, and other files from path terms, source content, identifiers, quoted fragments, file mentions, and real diff content.
+- Ranks source, test, configuration, documentation, and other files from path terms, source content, identifiers, quoted fragments (including smart quotes and guillemets), file mentions, and real diff content.
 - Recognizes JavaScript/TypeScript declaration tests, Go `_test.go`, Python `test_*.py` and `*_test.py`, common test directories, and framework single-file components.
-- Deprioritizes lockfiles, backups, bundled output, examples, and generated counterparts when maintained source exists.
-- Routes reachable test commands from real package scripts and pairs them with the nearest related test files.
+- Deprioritizes lockfiles, sync-client backups, bundled output, examples, and generated counterparts when maintained source exists, while keeping ordinary modules such as `deep-copy.ts` and tracked first-party `vendor/` source rankable.
+- Routes reachable test commands from real package scripts and pairs them with the nearest related test files. It warns when routed JavaScript, Python, Go, or Rust tests are skipped, ignored, conditional, or gated.
 - Reports six bounded risk areas: authentication, billing, automation, data, public API, and dependencies.
 - Explains task grounding, ranking shape, unresolved or partially matched identifiers, exclusions, scan limits, unread content, skipped submodules, empty diffs, and Git failures.
-- Supports `--limit`, repeatable `--exclude`, and ordered `.fixmapignore` patterns with negation.
+- Supports a strict decimal `--limit`, repeatable `--exclude`, and ordered `.fixmapignore` patterns with negation. Root-leading patterns are repository-relative, pasted absolute paths inside the repository are normalized, and patterns that match nothing produce a warning. Limits change only how many rows are shown, never confidence or ranking-shape analysis.
+
+### Exclusion pattern syntax
+
+`--exclude` and `.fixmapignore` use repository-relative gitignore-style patterns. `/docs/**` anchors at the repository root, `docs/**` matches the same root directory and nested occurrences, `!docs/keep.md` re-includes a path after an earlier exclusion, and trailing `/` targets a directory. `*`, `?`, and `**` are supported; brace groups such as `{src,test}` are literal text, not alternation. Pass repeated `--exclude` flags or put one pattern per `.fixmapignore` line so commas in literal names stay unambiguous.
+
 - Produces Markdown for people or versioned JSON for tools, writes to `--output`, and gives one grounded next action.
 
-### Explain, Compare, Verify, and Doctor
+### Explain, Compare, Verify, Validate, and Doctor
 
 - **Explain** tells you whether a path ranked, fell below the cutoff, was excluded, resolves through a submodule, or was never scanned—and uses the same task and diff evidence as Plan.
 - **Compare** shows files that entered, left, moved, or changed confidence after the task was refined, plus changes in task grounding.
-- **Verify** compares a saved JSON plan with a diff or working tree and flags generated edits, unmapped changes, an untouched leading file, source changes without tests, newly reached risk areas, and plan/repository mismatches.
+- **Verify** compares a saved JSON plan with a diff or working tree and flags generated edits, unmapped changes, an untouched leading file, source changes without tests, newly reached risk areas, and plan/repository mismatches. It fails on errors by default; `--fail-on warning` and the Action's `fail-on: warning` turn advisory findings into an opt-in CI gate.
+- **Validate** checks any saved JSON report with the structural compatibility validator shared by Compare, Verify, the Action, and MCP.
 - **Doctor** prints the running version and executable path and diagnoses project, global, PATH, and npm-exec version shadows.
 - `FIXMAP_PROGRESS` controls remote clone/scan progress, and `FIXMAP_VERBOSE_USAGE` restores full usage text after argument errors.
 
 ### Agent and automation interfaces
 
+- `fixmap setup` installs `/fixmap` discovery for Claude Code, Cursor, GitHub Copilot prompt files, and the open Agent Skills layout; the no-argument command lists every FixMap workflow before making changes.
 - The MCP server exposes `fixmap_plan`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor` over local stdio and is published in the official MCP Registry.
-- The GitHub Action runs Plan or Verify on pull requests, writes a full job summary, and creates or updates one bounded FixMap comment instead of posting duplicates.
+- The GitHub Action runs Plan or Verify on pull requests, appends within the job summary's remaining 1 MiB budget, bounds its report output and comment, and creates or updates one FixMap comment instead of posting duplicates.
 - The Action accepts explicit task input or pull-request context, uses the same report validator as the CLI and MCP server, and fails clearly when a requested diff cannot be resolved.
 - The browser demo runs the real core Plan, Explain, Compare, and Verify logic against a sample repository without uploading the task.
 
@@ -165,12 +187,12 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: aryamthecodebreaker/FixMap@v0.8.8
+      - uses: aryamthecodebreaker/FixMap@v0.8.9
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-The Action writes the complete report to the job summary and maintains one pull-request comment. Its checked-in bundle and metadata are release-gated.
+The Action writes a bounded report to the job summary and maintains one pull-request comment. If GitHub's limits require truncation, the notice points to a local `--output` plus artifact upload for the complete report. Set `no-cache: true` when a workflow must bypass the exact-state scan cache, or `fail-on: warning` when advisory Verify findings must fail the job. Its checked-in bundle and metadata are release-gated.
 
 ## JSON compatibility
 

action.yml

@@ -13,6 +13,12 @@ inputs:
       Verify mode only. Path to the JSON plan this change was made from, usually restored
       from an artifact saved by an earlier plan step.
     required: false
+  fail-on:
+    description: >-
+      Verify mode only. error (default) fails only on error findings; warning also fails
+      when verification raises advisory warnings such as no-test-changed.
+    required: false
+    default: error
   issue:
     description: >-
       Issue, prompt, or review context for FixMap. Accepts a public GitHub issue or pull
@@ -46,6 +52,10 @@ inputs:
     description: With working-tree, include untracked files.
     required: false
     default: "false"
+  no-cache:
+    description: Bypass the exact-state repository scan cache and perform a fresh scan.
+    required: false
+    default: "false"
   format:
     description: >-
       Output format. JSON is posted as a fenced JSON pull-request comment, and the step
@@ -60,7 +70,7 @@ inputs:
     required: false
 outputs:
   report:
-    description: The complete FixMap report, or verification, in the selected format.
+    description: The bounded FixMap report, or verification, in the selected format.
   context-count:
     description: Number of context files returned. Plan mode only.
   test-route-count:

apps/web/app/_components/copy-command.tsx

@@ -1,23 +1,37 @@
 "use client";
 
 import { Check, Copy } from "@phosphor-icons/react";
-import { useState } from "react";
+import { useRef, useState } from "react";
 
 export function CopyCommand({ command, label = "Copy command" }: { command: string; label?: string }) {
-  const [copied, setCopied] = useState(false);
+  const [state, setState] = useState<"idle" | "copied" | "manual">("idle");
+  const codeRef = useRef<HTMLElement>(null);
 
   async function copy() {
-    await navigator.clipboard.writeText(command);
-    setCopied(true);
-    window.setTimeout(() => setCopied(false), 1800);
+    try {
+      if (!navigator.clipboard?.writeText) throw new Error("Clipboard API unavailable");
+      await navigator.clipboard.writeText(command);
+      setState("copied");
+    } catch {
+      const code = codeRef.current;
+      if (code) {
+        const selection = window.getSelection();
+        const range = document.createRange();
+        range.selectNodeContents(code);
+        selection?.removeAllRanges();
+        selection?.addRange(range);
+      }
+      setState("manual");
+    }
+    window.setTimeout(() => setState("idle"), 2400);
   }
 
   return (
     <div className="copy-command">
-      <code>{command}</code>
+      <code ref={codeRef}>{command}</code>
       <button type="button" onClick={copy} aria-label={label}>
-        {copied ? <Check size={18} weight="bold" aria-hidden /> : <Copy size={18} aria-hidden />}
-        <span>{copied ? "Copied" : "Copy"}</span>
+        {state === "copied" ? <Check size={18} weight="bold" aria-hidden /> : <Copy size={18} aria-hidden />}
+        <span aria-live="polite">{state === "copied" ? "Copied" : state === "manual" ? "Press Ctrl+C" : "Copy"}</span>
       </button>
     </div>
   );