diff --git a/.github/workflows/ackit-action-dogfood.yml b/.github/workflows/ackit-action-dogfood.yml
index 6f859bb0..09c83033 100644
--- a/.github/workflows/ackit-action-dogfood.yml
+++ b/.github/workflows/ackit-action-dogfood.yml
@@ -16,22 +16,20 @@ jobs:
steps:
# actions/checkout@v4 (f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a)
- uses: actions/checkout@f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a
- # actions/setup-node@v4 (ae0d4ed08881f17d1511386f5be3e62356acd4a6)
- - uses: actions/setup-node@ae0d4ed08881f17d1511386f5be3e62356acd4a6
- with:
- node-version: "24"
- # pnpm/action-setup@v4 (b906affcce14559ad1aafd4ab0e942779e9f58b1)
- - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
- with:
- package_json_file: package.json
- - run: pnpm install --frozen-lockfile
- - run: pnpm build
- name: Run ACKit via local action (scan)
+ id: ackit
uses: ./
with:
command: scan
args: "--json"
- fail-threshold: low
- upload-sarif: "false"
+ fail-threshold: medium
+ upload-sarif: "true"
- name: Verify findings JSON exists
- run: test -f "${RUNNER_TEMP}/ackit-findings.json" && echo "findings JSON present" && cat "${RUNNER_TEMP}/ackit-findings.json" | head -20
+ env:
+ FINDINGS: ${{ steps.ackit.outputs.findings-json }}
+ SARIF: ${{ steps.ackit.outputs.sarif-path }}
+ run: |
+ test -f "${FINDINGS}"
+ test -f "${SARIF}"
+ - name: Clean external Action consumer
+ run: pnpm run smoke:action
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b8a5f76c..dfac7e86 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -41,6 +41,14 @@ jobs:
run: pnpm typecheck
- name: Build
run: pnpm build
+ - name: Schema drift
+ run: |
+ pnpm gen:schemas
+ git diff --exit-code -- schemas
+ - name: CLI smoke
+ run: pnpm smoke:cli
+ - name: Version parity
+ run: node scripts/check-version-parity.mjs
- name: Offline-egress static gate
run: node scripts/check-offline-egress.mjs
- name: Text hygiene (C0 controls)
@@ -107,7 +115,8 @@ jobs:
run: |
node -e "
const pkg=require('./extensions/vscode/package.json');
- if(pkg.version!=='0.5.4') throw new Error('extension version must be 0.5.4');
+ const root=require('./package.json');
+ if(pkg.version!==root.version) throw new Error('extension/root version mismatch');
if(pkg.publisher!=='Cynrath') throw new Error('publisher must be Cynrath');
if(pkg.displayName!=='ACKit Toolkit') throw new Error('displayName must be ACKit Toolkit');
if(!pkg.contributes.views.ackit.find(v=>v.id==='ackit.readiness')) throw new Error('ackit.readiness view missing');
@@ -116,85 +125,31 @@ jobs:
console.log('manifest contract PASS');
"
- name: Extension typecheck
- run: |
- pnpm --filter ackit-vscode exec tsc -p tsconfig.json --noEmit
- pnpm --filter ackit-vscode exec tsc -p tsconfig.test.json --noEmit
+ run: pnpm --filter ackit-vscode run typecheck
- name: Extension lint (vscode src)
- run: |
- pnpm --filter ackit-vscode exec biome check src --diagnostic-level=warn || true
+ run: pnpm --filter ackit-vscode run lint
- name: Extension build
run: |
- pnpm --filter ackit-vscode exec esbuild src/extension.ts --bundle --platform=node --target=node20 --outfile=dist/extension.js --external:vscode --sourcemap
+ pnpm --filter ackit-vscode run build
test -f extensions/vscode/dist/extension.js
- name: Extension unit tests
- run: |
- pnpm --filter ackit-vscode run compile:test
- # run mocha unit tests directly (without Electron) if available
- pnpm --filter ackit-vscode exec mocha out/test/suite/unit.test.js --timeout 5000 || echo "unit tests done"
+ run: pnpm --filter ackit-vscode run test:unit
- name: VS Code Electron integration (xvfb)
- run: |
- pnpm --filter ackit-vscode run compile:test
- xvfb-run -a pnpm --filter ackit-vscode test || echo "Electron integration completed (check logs)"
+ run: xvfb-run -a pnpm --filter ackit-vscode test
+ - name: Version parity
+ run: node scripts/check-version-parity.mjs
- name: vsce ls
run: |
cd extensions/vscode
- npx --yes @vscode/vsce ls --no-dependencies --no-yarn
+ npx --yes @vscode/vsce@4.1.1 ls --no-dependencies --no-yarn
- name: vsce package --no-dependencies
run: |
- cd extensions/vscode
- npx --yes @vscode/vsce package --no-dependencies --no-yarn --out ackit-vscode-0.5.4.vsix
- test -f ackit-vscode-0.5.4.vsix
- ls -lh ackit-vscode-0.5.4.vsix
- - name: VSIX content audit
- run: |
- cd extensions/vscode
- npx --yes @vscode/vsce ls --no-dependencies --no-yarn > /tmp/vsce-ls.txt
- cat /tmp/vsce-ls.txt
- if grep -q "node_modules" /tmp/vsce-ls.txt; then echo "::error::VSIX contains node_modules"; exit 1; fi
- # check icon exists and size
- ls -lh images/icon.png
- file images/icon.png
- # check VSIX size <2MB
- size=$(stat -c%s ackit-vscode-0.5.4.vsix 2>/dev/null || stat -f%z ackit-vscode-0.5.4.vsix)
- echo "VSIX size $size bytes"
- if [ "$size" -gt 2097152 ]; then echo "::error::VSIX >2MB"; exit 1; fi
- # check no secrets in VSIX
- unzip -l ackit-vscode-0.5.4.vsix | head -20
- if unzip -p ackit-vscode-0.5.4.vsix extension/package.json | grep -q "AKIA"; then echo "::error::secret in VSIX"; exit 1; fi
- - name: Packaged VSIX parity (Marketplace content)
- run: |
- cd extensions/vscode
- pkgver=$(node -p "require('./package.json').version")
+ pkgver=$(node -p "require('./extensions/vscode/package.json').version")
vsix="ackit-vscode-${pkgver}.vsix"
- test -f "$vsix"
- manver=$(unzip -p "$vsix" extension/package.json | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).version))")
- if [ "$manver" != "$pkgver" ]; then echo "::error::VSIX manifest $manver != $pkgver"; exit 1; fi
- unzip -p "$vsix" extension/readme.md > /tmp/vsix-readme.md
- grep -q "\*\*Version:\*\* \`$pkgver\`" /tmp/vsix-readme.md || { echo "::error::VSIX README Version != $pkgver"; exit 1; }
- grep -q "ackit.status.v1" /tmp/vsix-readme.md || { echo "::error::VSIX README missing ackit.status.v1"; exit 1; }
- grep -qi "verification freshness" /tmp/vsix-readme.md || { echo "::error::VSIX README missing verification freshness"; exit 1; }
- grep -qi "checkpoint freshness" /tmp/vsix-readme.md || { echo "::error::VSIX README missing checkpoint freshness"; exit 1; }
- unzip -p "$vsix" extension/changelog.md > /tmp/vsix-changelog.md
- latest=$(grep -m1 -o '^## \[[^]]*\]' /tmp/vsix-changelog.md)
- echo "VSIX CHANGELOG latest: $latest"
- echo "$latest" | grep -q "## \[$pkgver\]" || { echo "::error::VSIX CHANGELOG latest != $pkgver"; exit 1; }
- echo "packaged VSIX parity PASS ($pkgver)"
- - name: Icon dimensions
- run: |
cd extensions/vscode
- node -e "
- const fs=require('fs');
- const buf=fs.readFileSync('images/icon.png');
- const w=buf.readUInt32BE(16), h=buf.readUInt32BE(20);
- console.log('icon',w+'x'+h, buf.length+' bytes');
- if(w<128||h<128) throw new Error('icon <128');
- if(w!==h) throw new Error('icon not square');
- if(w!==256) console.log('warning: icon not 256x256 but square and >=128, accepting');
- if(buf.length<=1024) throw new Error('icon too small');
- "
+ npx --yes @vscode/vsce@4.1.1 package --no-dependencies --no-yarn --out "${vsix}"
+ echo "VSIX_PATH=$(pwd)/${vsix}" >> "${GITHUB_ENV}"
+ - name: VSIX content audit and packaged parity
+ run: node scripts/check-vsix.mjs "${VSIX_PATH}"
- name: Offline-egress extension audit
- run: |
- node scripts/check-offline-egress.mjs
- # also ensure extension src has no fetch/http
- if grep -R "fetch.*http" extensions/vscode/src; then echo "::error::extension fetch"; exit 1; fi
- echo "offline-egress PASS"
+ run: node scripts/check-offline-egress.mjs
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 9aeb4368..04cd168c 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -184,10 +184,10 @@ jobs:
echo "::error::extension publisher '${EXT_PUB}' != 'Cynrath'"
exit 52
fi
- pnpm --filter ackit-vscode exec esbuild src/extension.ts --bundle --platform=node --target=node20 --outfile=dist/extension.js --external:vscode --sourcemap
+ pnpm --filter ackit-vscode run build
test -f extensions/vscode/dist/extension.js
cd extensions/vscode
- npx --yes @vscode/vsce package --no-dependencies --no-yarn --out "ackit-vscode-${RELEASE_VERSION}.vsix"
+ npx --yes @vscode/vsce@4.1.1 package --no-dependencies --no-yarn --out "ackit-vscode-${RELEASE_VERSION}.vsix"
test -f "ackit-vscode-${RELEASE_VERSION}.vsix"
VSIX_ABS="$(pwd)/ackit-vscode-${RELEASE_VERSION}.vsix"
VSIX_SHA256="$(sha256sum "${VSIX_ABS}" | cut -d' ' -f1)"
@@ -250,7 +250,7 @@ jobs:
exit 61
fi
cd extensions/vscode
- npx --yes @vscode/vsce ls --no-dependencies --no-yarn > /tmp/vsce-ls.txt
+ npx --yes @vscode/vsce@4.1.1 ls --no-dependencies --no-yarn > /tmp/vsce-ls.txt
cat /tmp/vsce-ls.txt
if grep -q "node_modules" /tmp/vsce-ls.txt; then
echo "::error::vsce ls lists node_modules"
@@ -267,6 +267,7 @@ jobs:
echo "::error::secret pattern in VSIX manifest"
exit 64
fi
+ node scripts/check-vsix.mjs "${VSIX_PATH}"
node scripts/check-offline-egress.mjs
if grep -R "fetch.*http" extensions/vscode/src; then
echo "::error::extension source contains remote fetch"
@@ -326,7 +327,7 @@ jobs:
fi
seen=0
for attempt in 1 2 3; do
- if npx --yes @vscode/vsce show Cynrath.ackit-vscode --json > /tmp/mkt-pre.json 2> /tmp/mkt-pre.err; then
+ if npx --yes @vscode/vsce@4.1.1 show Cynrath.ackit-vscode --json > /tmp/mkt-pre.json 2> /tmp/mkt-pre.err; then
PRE_VER="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-pre.json','utf8')).versions?.[0]?.version ?? 'unknown'")"
echo "Marketplace live latest: ${PRE_VER} (release target ${RELEASE_VERSION})"
if [ "${PRE_VER}" = "${RELEASE_VERSION}" ]; then
@@ -425,7 +426,7 @@ jobs:
set -euo pipefail
seen=0
for attempt in $(seq 1 30); do
- if npx --yes @vscode/vsce show Cynrath.ackit-vscode --json > /tmp/mkt-show.json 2> /tmp/mkt-show.err; then
+ if npx --yes @vscode/vsce@4.1.1 show Cynrath.ackit-vscode --json > /tmp/mkt-show.json 2> /tmp/mkt-show.err; then
MKT_VER="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-show.json','utf8')).versions?.[0]?.version ?? ''")"
if [ "${MKT_VER}" = "${RELEASE_VERSION}" ]; then
seen=1
@@ -532,8 +533,17 @@ jobs:
echo "::error::npm latest='${NPM_LATEST}' != '${RELEASE_VERSION}'"
exit 90
fi
- npx --yes @vscode/vsce show Cynrath.ackit-vscode --json > /tmp/mkt-final.json
- MKT_FINAL="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-final.json','utf8')).versions?.[0]?.version ?? ''")"
+ MKT_FINAL=""
+ for attempt in $(seq 1 6); do
+ if npx --yes @vscode/vsce@4.1.1 show Cynrath.ackit-vscode --json > /tmp/mkt-final.json 2> /tmp/mkt-final.err; then
+ MKT_FINAL="$(node -p "JSON.parse(require('fs').readFileSync('/tmp/mkt-final.json','utf8')).versions?.[0]?.version ?? ''")"
+ if [ "${MKT_FINAL}" = "${RELEASE_VERSION}" ]; then
+ break
+ fi
+ fi
+ echo "final Marketplace read attempt ${attempt}/6: stale or unreadable; target ${RELEASE_VERSION}"
+ if [ "${attempt}" -lt 6 ]; then sleep 10; fi
+ done
if [ "${MKT_FINAL}" != "${RELEASE_VERSION}" ]; then
echo "::error::Marketplace latest='${MKT_FINAL}' != '${RELEASE_VERSION}'"
exit 91
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 79e15ae5..fb8cfd53 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,11 +6,50 @@ This project follows Semantic Versioning.
## [Unreleased]
+## [0.5.5] - 2026-11-17
+
+Compatible audit and reliability patch. Public CLI/SDK exports and offline
+analysis remain unchanged; the corrections below restore documented behavior.
+
+### Fixed
+
+- GitHub Action threshold failures survive a successful CLI process exit;
+ policy-suppressed findings do not fail the Action. CLI errors and bounded
+ process failures remain failures, and SARIF uses the canonical 2.1.0 writer.
+- The Action builds its exact source checkout with pinned Node/pnpm setup and a
+ frozen install, then runs offline against the consumer. Clean-tag consumers
+ no longer depend on missing ignored CLI files. Setup needs registry access;
+ no generated `dist` is tracked (ADR-0034).
+- SDK scans run the built-in rule catalog by default and append trusted extra
+ rules. VS Code now receives real findings, keeps packaged SDK identity/templates
+ available in its CommonJS bundle, and confines finding paths to the workspace.
+- Action setup locates its own pinned manifest relative to the consumer workspace;
+ VS Code serializes overlapping refreshes per root and publishes completed snapshots.
+ Consumer diagnostics redact canonical path aliases on macOS as well.
+- MCP tool reference matches all 16 live input schemas; scan `ci` controls the
+ severity exit hint. CLI `--root` now binds MCP startup ahead of environment/cwd
+ fallback without reopening per-tool root overrides.
+- CI propagates extension lint/unit/Electron failures, verifies schema drift and
+ CLI smoke, derives version/VSIX names, and audits actual packaged content/CRC.
+ Extension tests assert real runtime data; VSIX excludes source maps and tools.
+- Final Marketplace verification retries stale/unreadable visibility reads within
+ a fixed bound and still fails closed unless the exact release version is seen.
+- Repaired README links, SDK example/signatures and portable path fixtures;
+ documented the separate historical task namespace and truthful Docs7 blockers.
+
+### Security
+
+- Updated compatible MCP SDK/Zod versions and affected runtime transitives;
+ production dependency audit reports zero known advisories. Existing development
+ tool advisories are separately triaged in TASK-0101, not hidden or suppressed.
+- Marketplace-first manual gate, npm OIDC/provenance, exact-tag identity and
+ immutable artifact checks remain in force. No credential or permission change.
+
### Added
- Context7 library parsing configuration and optional Docs7 Free documentation
- site manifest, with a guide for owner claiming, verification and automatic refresh;
- no CLI/runtime, package version or existing hosting changes.
+ site manifest, with a guide for ownership, verification and automatic refresh;
+ documentation hosting/account verification remains separate from offline runtime.
- Community integration docs for GitHub Spec Kit: new
`docs/guides/spec-kit-bridge.md`, README ecosystem section and docs index
link pointing at [`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge)
@@ -612,4 +651,4 @@ PROJECT-CONTROL-0107 planning commit `c249a13` opens with the post-0158 state sy
### Fixed
- Added NuGet package README metadata for local pack readiness.
-- Refined self-scan stack accuracy so sample ASP.NET Core, Minimal API, TypeScript, and Tailwind CSS signals are not reported as the main repository stack.
\ No newline at end of file
+- Refined self-scan stack accuracy so sample ASP.NET Core, Minimal API, TypeScript, and Tailwind CSS signals are not reported as the main repository stack.
diff --git a/README.md b/README.md
index c26a42cd..4ad38746 100644
--- a/README.md
+++ b/README.md
@@ -172,7 +172,7 @@ OpenCode, Copilot, Gemini, Cursor, Cline, any MCP-capable agent).
| ๐ฉบ | Diagnostics | ackit diagnostics bundle | ackit.diagnostics.v1 + deterministic bundle-manifest.json (sha256 + redaction count), 5-secret [REDACTED] proof |
| โก | Benchmarks | benchmarks/run.mjs | 7 deterministic fixtures, 8 metrics (coldScanMs/warmScanMs/incrementalMs/peakRssMb/filesPerSec/packMs/graphMs/cacheHitRatio), median-of-3 |
| ๐ | SDK v1 | import { scanRepository } from "@cynrath/agent-context-kit" | sideEffects:false, type:module, exports {".","./mcp"}, AbortSignal <200ms, AckitError |
-| ๐งฉ | VS Code | extensions/vscode | 0.5.4, Cynrath, lints Linters, onStartupFinished, readiness tree + Problems ACKITxxx + status-integrated Tasks view (canonical blockers/next actions, no mutation), <2MB VSIX โ Marketplace: Cynrath.ackit-vscode |
+| ๐งฉ | VS Code | extensions/vscode | 0.5.5, Cynrath, lints Linters, onStartupFinished, readiness tree + Problems ACKITxxx + status-integrated Tasks view (canonical blockers/next actions, no mutation), <2MB VSIX โ Marketplace: Cynrath.ackit-vscode |
| ๐ค | MCP | ackit mcp serve | Official SDK stdio, 16 read-only tools (incl. canonical ackit_status, workflow status, intent, checkpoint, verification bundle, drift, roles), 5 resources, 4 prompts, InMemoryTransport cancellation |
| ๐ | Trust-Flow Demo | docs/guides/demo-trust-flow.md | reproducible offline proof: missing proof blocks โ bound independent verdict enables โ mutation stales โ fresh re-verification restores โ handoff exports โ second process resumes (tests/e2e/trust-flow-demo.test.ts) |
@@ -356,7 +356,7 @@ ackit diagnostics --json | jq .profile
ackit diagnostics bundle --out ./ackit-diag.zip --redact-check
```
-Guides: [`docs/guides/watch-dashboard.md`](docs/guides/watch-dashboard.md) ยท Reference: [`docs/reference/diagnostics.md`](docs/reference/diagnostics.md)
+Reference: [watch, dashboard and diagnostics commands](docs/reference/cli.md)
---
@@ -386,13 +386,19 @@ ACKit is available on the VS Code Marketplace as
From source:
```bash
-pnpm --filter vscode build
-vsce package # โ ackit-vscode-0.5.4.vsix
+pnpm install --frozen-lockfile
+pnpm build
+pnpm --filter ackit-vscode run build
+node -e "require('node:fs').mkdirSync('artifacts', { recursive: true })"
+cd extensions/vscode
+npx --yes @vscode/vsce@4.1.1 package --no-dependencies --no-yarn --out ../../artifacts/ackit-vscode-0.5.5.vsix
+cd ../..
+node scripts/check-vsix.mjs artifacts/ackit-vscode-0.5.5.vsix
```
Features: readiness tree, Problems `ACKITxxx`, graph โinstructions for current fileโ, tasks/policy/optimize, palette `Refresh/Show Graph/Optimize/Diagnostics`, file watcher debounced, no telemetry.
-Guide: [`docs/guides/vscode.md`](docs/guides/vscode.md)
+Guide: [`extensions/vscode/README.md`](extensions/vscode/README.md)
---
@@ -402,10 +408,10 @@ Guide: [`docs/guides/vscode.md`](docs/guides/vscode.md)
|---|---|
| Architecture | [`docs/architecture/overview.md`](docs/architecture/overview.md) |
| Concepts | `instruction-graph` ยท `context-budget` ยท `provider-profiles` ยท `readiness` ยท [`workflows`](docs/concepts/workflows.md) ยท [`intent`](docs/concepts/intent.md) ยท [`checkpoints`](docs/concepts/checkpoints.md) ยท [`evidence-verification`](docs/concepts/evidence-verification.md) |
-| Guides | [`getting-started`](docs/guides/getting-started.md) ยท [`readiness`](docs/guides/readiness.md) ยท [`optimize`](docs/guides/optimize.md) ยท [`provider-profiles`](docs/guides/provider-profiles.md) ยท [`instruction-graph`](docs/guides/instruction-graph.md) ยท [`rule-packs`](docs/guides/rule-packs.md) ยท [`ci`](docs/guides/ci.md) ยท [`watch-dashboard`](docs/guides/watch-dashboard.md) ยท [`diagnostics`](docs/guides/diagnostics.md) ยท [`sdk`](docs/guides/sdk.md) ยท [`vscode`](docs/guides/vscode.md) ยท [`monorepo`](docs/guides/monorepo.md) ยท [`workflow-adoption`](docs/guides/workflow-adoption.md) ยท [`workflow-example`](docs/guides/workflow-example.md) ยท [`demo-trust-flow`](docs/guides/demo-trust-flow.md) ยท [`spec-kit-bridge`](docs/guides/spec-kit-bridge.md) |
+| Guides | [`getting-started`](docs/guides/getting-started.md) ยท [`readiness`](docs/reference/cli.md) ยท [`optimize`](docs/reference/cli.md) ยท [`provider-profiles`](docs/reference/cli.md) ยท [`instruction-graph`](docs/concepts/instruction-graph.md) ยท [`rule-packs`](docs/reference/policy.md) ยท [`ci`](docs/guides/ci.md) ยท [`watch-dashboard`](docs/reference/cli.md) ยท [`diagnostics`](docs/reference/cli.md) ยท [`sdk`](docs/reference/sdk.md) ยท [`vscode`](extensions/vscode/README.md) ยท [`monorepo`](docs/guides/monorepo.md) ยท [`workflow-adoption`](docs/guides/workflow-adoption.md) ยท [`workflow-example`](docs/guides/workflow-example.md) ยท [`demo-trust-flow`](docs/guides/demo-trust-flow.md) ยท [`spec-kit-bridge`](docs/guides/spec-kit-bridge.md) |
| Reference | `cli` ยท `config` ยท `rules` ยท `readiness` ยท `profile` ยท `rule-pack` ยท `instruction-graph` ยท `diagnostics` ยท `sdk` ยท `exit-codes` ยท `mcp` ยท `schemas` ยท [`drift`](docs/reference/drift.md) ยท [`policy`](docs/reference/policy.md) ยท [`status`](docs/reference/cli.md#cli-reference) ยท [`provider-surfaces`](docs/reference/provider-surfaces.md) |
| Decisions | [`docs/decisions/`](docs/decisions/) ยท `v0.2.0`: [`docs/v0.2.0/`](docs/v0.2.0/) ยท `ADR-0025..0028`: workflow/evidence/checkpoint/policy-v2 |
-| Tasks | [`docs/tasks/active`](docs/tasks/active) |
+| Tasks | [`task records`](docs/tasks/README.md) |
| Ecosystem | [Spec Kit bridge](docs/guides/spec-kit-bridge.md) โ community integration ([`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge)) connecting Spec Kit intent artifacts to ACKit tasks, evidence, verification gates, and handoffs |
---
@@ -450,7 +456,7 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the docs-first workflow.
### ๐ Versioning
-Development: **`0.5.4`** on `master` ยท Latest stable: **`0.5.4`** ยท [Changelog](CHANGELOG.md) ยท [Releases](https://github.com/Cynrath/agent-context-kit/releases/latest) ยท `latest โ 0.5.4` via OIDC Trusted Publishing with provenance. Stable pointer: [`release-state.json`](release-state.json). Legacy `.NET/NuGet 1.0.0-rc.1` at `258918b` is frozen.
+Development: **`0.5.5`** on `master` ยท Latest stable: **`0.5.4`** ยท [Changelog](CHANGELOG.md) ยท [Releases](https://github.com/Cynrath/agent-context-kit/releases/latest) ยท `latest โ 0.5.4` via OIDC Trusted Publishing with provenance. Stable pointer: [`release-state.json`](release-state.json). Legacy `.NET/NuGet 1.0.0-rc.1` at `258918b` is frozen.
---
diff --git a/action.yml b/action.yml
index 7f051dce..f08e8cd7 100644
--- a/action.yml
+++ b/action.yml
@@ -24,8 +24,40 @@ inputs:
outputs:
findings-json:
description: "path to findings JSON"
+ value: ${{ steps.ackit.outputs.findings-json }}
sarif-path:
description: "SARIF file path when upload-sarif=true"
+ value: ${{ steps.ackit.outputs.sarif-path }}
runs:
- using: "node24"
- main: "dist/action/index.js"
+ using: "composite"
+ steps:
+ # actions/setup-node@v4
+ - uses: actions/setup-node@ae0d4ed08881f17d1511386f5be3e62356acd4a6
+ with:
+ node-version: "24"
+ - name: Locate the Action manifest
+ id: action-package
+ shell: bash
+ env:
+ ACKIT_ACTION_PATH: ${{ github.action_path }}
+ run: node "${ACKIT_ACTION_PATH}/scripts/action-package-path.mjs" >> "${GITHUB_OUTPUT}"
+ # pnpm/action-setup@v4
+ - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
+ with:
+ package_json_file: ${{ steps.action-package.outputs.path }}
+ - name: Build the exact Action source
+ shell: bash
+ working-directory: ${{ github.action_path }}
+ run: |
+ pnpm install --frozen-lockfile --ignore-scripts --filter @cynrath/agent-context-kit
+ pnpm build
+ - name: Run ACKit against the consumer
+ id: ackit
+ shell: bash
+ env:
+ ACKIT_ACTION_PATH: ${{ github.action_path }}
+ INPUT_COMMAND: ${{ inputs.command }}
+ INPUT_ARGS: ${{ inputs.args }}
+ INPUT_FAIL_THRESHOLD: ${{ inputs.fail-threshold }}
+ INPUT_UPLOAD_SARIF: ${{ inputs.upload-sarif }}
+ run: node "${ACKIT_ACTION_PATH}/dist/action/index.js"
diff --git a/dist/action/index.js b/dist/action/index.js
deleted file mode 100644
index 1908c51c..00000000
--- a/dist/action/index.js
+++ /dev/null
@@ -1,150 +0,0 @@
-#!/usr/bin/env node
-// Minimal GitHub Action runtime for ACKit (TASK-0014)
-// Uses @actions/core if available, else fallback to console. No shell interpolation, uses execFile.
-import { spawnSync } from "node:child_process";
-import { writeFileSync, existsSync } from "node:fs";
-import path from "node:path";
-import process from "node:process";
-
-function getInput(name) {
- const envName = `INPUT_${name.replace(/ /g, "_").toUpperCase().replace(/-/g, "_")}`;
- return process.env[envName] ?? "";
-}
-
-function safeSplitArgs(input) {
- if (!input || input.trim() === "") return [];
- // Simple shell-like split respecting double quotes, no evaluation
- const args = [];
- let cur = "";
- let inQuote = false;
- for (let i = 0; i < input.length; i++) {
- const c = input[i];
- if (c === '"' && (i === 0 || input[i - 1] !== "\\")) {
- inQuote = !inQuote;
- continue;
- }
- if (c === " " && !inQuote) {
- if (cur.length > 0) {
- args.push(cur);
- cur = "";
- }
- continue;
- }
- cur += c;
- }
- if (cur.length > 0) args.push(cur);
- return args;
-}
-
-function severityRank(s) {
- const map = { low: 1, medium: 2, high: 3, critical: 4 };
- return map[s?.toLowerCase()] ?? 0;
-}
-
-async function run() {
- const command = getInput("command") || "scan";
- const argsRaw = getInput("args") || "";
- const failThreshold = getInput("fail-threshold") || "high";
- const uploadSarif = getInput("upload-sarif") === "true";
- const extraArgs = safeSplitArgs(argsRaw);
-
- const runnerTemp = process.env["RUNNER_TEMP"] || process.env["TMPDIR"] || "/tmp";
- const findingsJsonPath = path.join(runnerTemp, "ackit-findings.json");
- const sarifPath = path.join(runnerTemp, "ackit.sarif");
-
- // Resolve CLI entry (dist/cli/index.js)
- const cliPath = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1")), "..", "cli", "index.js");
-
- // For scan, we invoke ackit scan --json and capture findings
- let findings = [];
- let exitCode = 0;
- try {
- const cliArgs = [cliPath, command, ...extraArgs, "--json"];
- // Use node to run CLI
- const result = spawnSync(process.execPath, cliArgs, { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
- if (result.stdout) {
- try {
- const parsed = JSON.parse(result.stdout);
- findings = parsed.findings ?? parsed.suggestions ?? [];
- // Write findings JSON to temp
- writeFileSync(findingsJsonPath, JSON.stringify(parsed, null, 2), "utf8");
- // Emit outputs via GITHUB_OUTPUT if available
- const outPath = process.env["GITHUB_OUTPUT"];
- if (outPath) {
- try {
- const fs = await import("node:fs/promises");
- await fs.appendFile(outPath, `findings-json=${findingsJsonPath}\n`);
- if (uploadSarif) await fs.appendFile(outPath, `sarif-path=${sarifPath}\n`);
- } catch {}
- }
- // Annotations: map severity to ::error/::warning
- for (const f of findings.slice(0, 10)) {
- const lvl = (f.severity ?? "low").toLowerCase();
- const msg = `${f.ruleId ?? f.id ?? "ACKIT"}: ${f.message ?? ""}`.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
- const file = (f.relativePath ?? f.evidence?.[0]?.relativePath ?? "unknown").replace(/%/g, "%25");
- const line = f.line ?? f.evidence?.[0]?.line ?? 1;
- const annotation = lvl === "critical" || lvl === "high" ? "error" : lvl === "medium" ? "warning" : "notice";
- console.log(`::${annotation} file=${file},line=${line}::${msg}`);
- }
- // SARIF if requested
- if (uploadSarif) {
- const sarif = {
- $schema: "https://json.schemastore.org/sarif-2.1.0.json",
- version: "2.1.0",
- runs: [
- {
- tool: { driver: { name: "ackit", version: "0.2.0" } },
- results: findings.map((f) => ({
- ruleId: f.ruleId ?? f.id ?? "ACKIT",
- level: f.severity === "high" || f.severity === "critical" ? "error" : f.severity === "medium" ? "warning" : "note",
- message: { text: f.message ?? "" },
- locations: [
- {
- physicalLocation: {
- artifactLocation: { uri: f.relativePath ?? f.evidence?.[0]?.relativePath ?? "unknown" },
- },
- },
- ],
- })),
- },
- ],
- };
- writeFileSync(sarifPath, JSON.stringify(sarif, null, 2), "utf8");
- }
- // Job summary
- const summaryPath = process.env["GITHUB_STEP_SUMMARY"];
- if (summaryPath) {
- try {
- const fs = await import("node:fs/promises");
- const counts = {};
- for (const f of findings) counts[f.severity ?? "low"] = (counts[f.severity ?? "low"] ?? 0) + 1;
- let md = `## ACKit ${command} โ ${findings.length} finding(s)\n\n| Severity | Count |\n|---|---|\n`;
- for (const sev of ["critical", "high", "medium", "low"]) if (counts[sev]) md += `| ${sev} | ${counts[sev]} |\n`;
- if (findings.length > 0) md += `\nTop: ${findings[0]?.ruleId ?? findings[0]?.id} โ ${findings[0]?.message ?? ""}\n`;
- await fs.appendFile(summaryPath, md, "utf8");
- } catch {}
- }
- // Fail threshold gating
- const maxRank = findings.reduce((m, f) => Math.max(m, severityRank(f.severity)), 0);
- const thrRank = severityRank(failThreshold);
- if (maxRank >= thrRank && findings.length > 0) {
- console.error(`::error::fail-threshold ${failThreshold} exceeded`);
- exitCode = 1;
- }
- exitCode = result.status ?? exitCode;
- } catch (e) {
- console.error(`::error::failed to parse CLI JSON: ${e}`);
- exitCode = 1;
- }
- } else {
- if (result.stderr) console.error(result.stderr);
- exitCode = result.status ?? 1;
- }
- } catch (e) {
- console.error(`::error::action failed: ${e}`);
- exitCode = 1;
- }
- process.exit(exitCode);
-}
-
-run();
diff --git a/docs/decisions/ADR-0034-source-built-action-distribution.md b/docs/decisions/ADR-0034-source-built-action-distribution.md
new file mode 100644
index 00000000..dac2853f
--- /dev/null
+++ b/docs/decisions/ADR-0034-source-built-action-distribution.md
@@ -0,0 +1,44 @@
+# ADR-0034: Source-built GitHub Action distribution
+
+Status: Accepted ยท Date: 2026-11-17 ยท Task: TASK-0098
+
+## Context
+
+ADR-0020 specified a self-contained Node action but its implementation tracks a
+handwritten `dist/action/index.js` with no owning source. Tags omit the referenced
+CLI and dependencies; the dogfood build hides the missing runtime. Current
+repository governance prohibits tracking generated `dist`. Committing an entire
+CLI/dependency bundle would contradict that rule and duplicate the npm runtime.
+
+## Decision
+
+Supersede only ADR-0020's distribution/entrypoint choice with a composite Action
+that builds the exact tagged source in its own checkout. Preserve inputs,
+outputs, least privilege, injection-safe argv, optional SARIF and offline product
+execution. The original ADR is retained verbatim as historical context.
+
+1. Pin setup-node and pnpm/action-setup to reviewed full SHAs. Select Node 24 and
+ the action checkout's exact `packageManager` version.
+2. Frozen-install the action workspace and build its canonical CLI/Action source.
+ Setup may download locked dependencies; no consumer package script is run.
+3. Run the built TypeScript Action entry with input values passed through
+ environment variables. Resolve CLI files relative to the Action installation;
+ the working directory remains the consumer repository.
+4. No network is used by the CLI/SDK/MCP/Action execution code. No `dist`, bundled
+ dependencies, package archives or generated runtime is committed.
+5. A clean exported checkout consumed from an unrelated fixture, plus hosted
+ dogfood without a preparatory install/build, validates the whole bootstrap.
+
+## Consequences and alternatives
+
+Consumers require registry access during setup and incur an install/build cost.
+Runtime remains the same canonical source/version, without an npm publication
+race at tag creation. A generated committed bundle and runtime `npx latest` were
+rejected for governance and reproducibility reasons respectively. Revisit only
+through a separate task if measured setup cost warrants a distribution change.
+
+## Security and rollback
+
+Trusted Action source, frozen lockfile, pinned setup actions and environment/argv
+boundaries apply. No permission expansion or automatic upload. A forward PR can
+correct the bootstrap; never move existing tags or change published artifacts.
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 56195a66..a81ec7df 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -45,3 +45,9 @@ v0.5 line additions (Accepted 2026-09-05, governing TASK-0078 โฆ TASK-0086):
- ADR-0030 deterministic verification state binding (verdict โ bundle/state digests, staleness + replay at the binding layer)
- ADR-0031 structural verifier independence + replay hardening (reviewed-bundle proof, independence gate, review-artifact lifecycle)
- ADR-0032 canonical read-only status projection (composed task/stage/blockers/staleness/next-actions, no second engine)
+
+Distribution correction (Accepted 2026-11-17):
+
+- [ADR-0034 source-built Action distribution](ADR-0034-source-built-action-distribution.md)
+ amends ADR-0020's entrypoint/bootstrap while preserving offline runtime and
+ avoiding committed generated output.
diff --git a/docs/guides/ci.md b/docs/guides/ci.md
index 7ddc30b1..94dcebfa 100644
--- a/docs/guides/ci.md
+++ b/docs/guides/ci.md
@@ -16,6 +16,32 @@ Matrix: **ubuntu + windows + macos ร Node 22 + 24**.
TASK-0286 hardens this further (SHA-pinned actions, package smoke, self-scan,
MCP smoke).
+## GitHub Action distribution
+
+The Action keeps `command`, `args`, `fail-threshold`, `upload-sarif` and the
+`findings-json` / `sarif-path` outputs. Pin a published tag or full commit SHA.
+It sets up Node 24 and the exact pnpm version from its own `package.json`, then
+installs the frozen lockfile and builds in the Action checkout. Setup requires
+registry access; the resulting CLI execution is offline and scans the consumer's
+working directory. Consumer dependencies and scripts are never installed or run.
+
+`fail-threshold` is inclusive (`low|medium|high|critical`) for scan findings and
+optimize suggestions, ignores explicitly policy-suppressed findings, and cannot
+clear a nonzero CLI exit code. The original command JSON stays intact. SARIF is
+generated only when requested and is not uploaded automatically. Consumers need
+`contents: read`; SARIF upload is a separate opt-in step with its own permissions.
+Use the Action outputs to locate generated files rather than guessing paths.
+
+For `drift check`, blocking maps to high and warning maps to medium for the
+Action threshold; CLI `--ci` errors are still preserved independently. Its
+task-level SARIF results have no fabricated file location. SARIF file paths are
+URI-encoded, including spaces, reserved characters and Unicode.
+
+`pnpm run smoke:action` exports clean source into a separate Action checkout,
+installs/builds it and scans an unrelated Git fixture without consumer runtime
+files. `pnpm run smoke:action --ref vX.Y.Z` repeats the check from a release tag.
+ADR-0034 records the source distribution decision; generated `dist` is untracked.
+
## Using ACKit as a gate in your repo
```bash
diff --git a/docs/guides/context7-docs7.md b/docs/guides/context7-docs7.md
index 333bca44..051e9128 100644
--- a/docs/guides/context7-docs7.md
+++ b/docs/guides/context7-docs7.md
@@ -28,12 +28,14 @@ Open the already-owned library's **Admin** page and select the orange **Apply fo
## 4. Connect Docs7 Free (optional; existing GitHub Pages stays active)
1. Open [Docs7](https://context7.com/docs7) while signed into Context7.
-2. Add a new site from GitHub; select `Cynrath/agent-context-kit`.
+2. In the teamspace's Docs7 tab, choose **Add new repository**, then **Form**;
+ select `Cynrath/agent-context-kit`.
3. Set production branch to `master`, and **Docs path** to `docs`. The `docs/docs.json` file defines the navigation and `docs/index.mdx` is the entry page.
4. Publish the site. Keep the assigned `*.docs7.io` address separate from existing GitHub Pages until you intentionally decide otherwise.
5. Enable **Add to Context7** when connecting the repository (or use the site's **Context7** tab) so successful production builds refresh the library automatically. Do not create a duplicate library if the original GitHub library is already registered.
-Docs7 Free currently allows up to three sites. The hosted documentation site and agent-readable endpoints are available on Free; autonomous Docs7 documentation editing agents and PR previews require Pro.
+See [Docs7 plans](https://context7.com/docs/docs7/plans) for current site limits,
+preview access and documentation-editing agent availability.
## 5. Verify deployment and indexing
diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md
index 98cc0081..f7ece6fc 100644
--- a/docs/reference/mcp.md
+++ b/docs/reference/mcp.md
@@ -11,15 +11,15 @@ truth).
| Tool | Arguments | Returns |
|---|---|---|
-| ackit_scan | changed?, ci?, root? | canonical scan report JSON + exit_code_hint |
-| ackit_doctor | root? | config ok/errors + task-doctor integrity |
-| ackit_pack | maxTokens?, format?, includeGlobs?, root? | pack markdown or JSON |
-| ackit_instruction_graph | root? | instruction graph nodes |
-| ackit_list_skills | root? | skill records |
-| ackit_validate_skills | root? | tiered issues |
-| ackit_list_tasks | all?, root? | task rows (id/status/title) |
-| ackit_get_task | id, root? | full task doc or unknown-task error |
-| ackit_policy_check | root? | policy chain + digest + diagnostics |
+| ackit_scan | changed?, ci? | canonical scan report JSON + exit_code_hint |
+| ackit_doctor | โ | config ok/errors + task-doctor integrity |
+| ackit_pack | maxTokens?, format? | pack markdown or JSON |
+| ackit_instruction_graph | โ | instruction graph nodes |
+| ackit_list_skills | โ | skill records |
+| ackit_validate_skills | โ | tiered issues |
+| ackit_list_tasks | all? | task rows (id/status/title) |
+| ackit_get_task | id | full task doc or unknown-task error |
+| ackit_policy_check | โ | policy chain + digest + diagnostics |
| ackit_workflow_status | taskId | workflow profile/stage/required artifacts + effective evidence/verdict requirements (null for legacy tasks) |
| ackit_get_intent | id | intent document + fingerprint |
| ackit_get_checkpoint | taskId | latest checkpoint + resume context |
@@ -28,6 +28,19 @@ truth).
| ackit_status | taskId? | canonical read-only task status snapshot (same `ackit.status.v1` contract as CLI `status`) |
| ackit_list_roles | โ | portable role contracts |
+The repository root is resolved once at server construction (`--root` for the
+CLI, `ACKIT_ROOT`, or `createAckitMcpServer(repositoryRoot)` for the SDK). Tools
+cannot override that boundary. Per-call `root` and pack `includeGlobs` are not
+supported inputs; repository configuration and the canonical pack safety gates
+control discovery.
+
+`ackit_scan.changed` defaults to `false`; `true` restricts the scan to Git changes.
+`ci` defaults to `false`: report-only scans append `exit_code_hint=0` even when
+findings exist. With `ci: true`, the hint is `1` only when an unsuppressed finding
+meets the configured policy severity threshold; otherwise it is `0`. This hint
+does not terminate the MCP server or turn findings into a protocol error. CLI
+readiness gates are separate from this severity hint.
+
Write tools are intentionally absent (state mutation stays CLI-only by
explicit decision). Any future write tool requires a new ADR with an explicit
capability/permission gate design before registration.
diff --git a/docs/reference/sdk.md b/docs/reference/sdk.md
index 6b802fd5..fb227a3c 100644
--- a/docs/reference/sdk.md
+++ b/docs/reference/sdk.md
@@ -9,16 +9,16 @@ The programmatic SDK is the single supported import for embedding ACKit in Node.
| Symbol | Kind | Description |
|---|---|---|
-| `scanRepository(root, opts?)` | function | Scans a repository, returns `ScanResult` (deterministic findings, diagnostics, filesScanned). `opts.signal?: AbortSignal` cancels within 200ms. |
-| `loadAckitConfig(root, opts?)` | function | Loads `ackit.yml` + policy chain, returns `{ok, config}` or `{ok:false, errors}` with `AckitError`-compatible codes. |
+| `scanRepository(root, opts?)` | function | Scans a repository, returns `ScanResult` (deterministic findings, diagnostics, filesScanned). Accepts `opts.signal?: AbortSignal`. |
+| `loadAckitConfig(rootPath, opts?)` | function | Loads and validates `ackit.yml`, merges configuration defaults and returns `{ok, config}` or `{ok:false, errors}`. `rootPath` is a directory string. |
| `buildContextPack(root, opts?)` | function | Builds a budgeted deterministic context pack (`PackResult`). `opts.signal` supported. |
| `buildInstructionGraph(root, opts?)` | function | Builds the instruction graph (`InstructionGraph`). `opts.signal` supported. |
| `resolveEffectiveStack(graph, provider, forPath?)` | function | Pure function resolving the effective instruction stack for a provider/path. |
| `analyzeOptimize(root, opts?)` | function | Optimization findings + suggestions (pack/context waste analysis). |
| `validateSkills(root)` | function | Validates `.agents/skills/*/SKILL.md` set, returns `{skills, issues}`. |
-| `evaluateRulePacks(root, opts?)` | function | Evaluates declarative rule packs (exported since v0.2.0). |
-| `loadRulePacks(root)` | function | Loads rule pack documents. |
-| `scoreRepository(root, opts?)` | function | Readiness scoring engine (exported since v0.2.0). |
+| `evaluateRulePacks(effectivePacks, context)` | function | Evaluates loaded declarative rules against repository files/configuration (exported since v0.2.0). |
+| `loadRulePacks(root, rulePackPaths)` | function | Loads the explicit repository-relative rule-pack paths. |
+| `scoreRepository(inputs, opts?)` | function | Scores collected graph/pack/scan/skills/policy/task inputs (exported since v0.2.0). |
| `detectProfiles`, `loadBuiltInProfiles`, `resolveProfile` | functions | Stack/profile detection and resolution. |
| `ProfileSchema` | constant | Stack-profile zod schema. |
| `READINESS_ENGINE_VERSION` | constant | Readiness engine version marker. |
@@ -65,13 +65,29 @@ Additions require ADR + contract test update; the allowlist test fails on accide
## Error model
+For scanning, packs, graphs, skills and rule-pack loading, `root` is a descriptor
+`{ canonicalPath: string }`, not a path string. Resolve it with Node's `realpath`:
+
+```js
+import { realpath } from "node:fs/promises";
+const root = { canonicalPath: await realpath(process.cwd()) };
+```
+
+`scanRepository` runs built-in rules plus `opts.extraRules` through the shared
+pipeline. It does not load `ackit.yml` or apply its external policy chain;
+configured CLI/MCP scans add that orchestration. Supply explicit limits and
+exclusions when embedding the lower-level SDK scanner.
+
```ts
import { AckitError, scanRepository } from "@cynrath/agent-context-kit";
+import { realpath } from "node:fs/promises";
+const root = { canonicalPath: await realpath(process.cwd()) };
+const signal = new AbortController().signal;
try {
const result = await scanRepository(root, { signal });
} catch (e) {
if (e instanceof DOMException && e.name === "AbortError") {
- console.log("aborted within 200ms");
+ console.log("aborted");
} else if (e instanceof AckitError) {
console.error(e.code, e.message, e.remediation);
} else if (e instanceof Error) {
@@ -84,14 +100,20 @@ Stable codes: `CONFIG-UNKNOWN-KEY` (did-you-mean hint in `remediation`), `CONFIG
## Cancellation (AbortSignal)
-All async SDK entries accept `{ signal?: AbortSignal }` and reject with `DOMException { name:"AbortError" }` within 200ms when `signal.aborted` is true before the call, and cooperatively abort mid-flight where checkpoints exist (scan batches, pack checkpoints, graph per-file).
+The scanning, context-pack and instruction-graph entries accept
+`{ signal?: AbortSignal }` and reject with `DOMException { name:"AbortError" }`
+within 200ms when `signal.aborted` is true before the call. Mid-flight cancellation
+is cooperative at scan batches, pack checkpoints and graph file boundaries;
+it is not a fixed wall-clock guarantee for arbitrary caller-supplied rules.
```ts
import { scanRepository } from "@cynrath/agent-context-kit";
+import { realpath } from "node:fs/promises";
+const root = { canonicalPath: await realpath(process.cwd()) };
const ac = new AbortController();
setTimeout(() => ac.abort(), 10);
try {
- const result = await scanRepository(process.cwd(), { signal: ac.signal });
+ const result = await scanRepository(root, { signal: ac.signal });
console.log(result.findings.length);
} catch (e) {
if (e instanceof DOMException && e.name === "AbortError") console.log("aborted");
diff --git a/docs/tasks/README.md b/docs/tasks/README.md
new file mode 100644
index 00000000..850507a1
--- /dev/null
+++ b/docs/tasks/README.md
@@ -0,0 +1,17 @@
+# Task record namespaces
+
+The current TypeScript task store reads `docs/tasks/active/` and, with `--all`,
+`docs/tasks/archive/`. Those two directories share one live ID namespace. Create
+new records with the repository-built CLI; `task doctor` validates their IDs,
+dependencies and single-active state.
+
+Root-level `TASK-*.md` and `PROJECT-CONTROL-*.md` files preserve the earlier
+implementation and migration history. They use a separate namespace: a matching
+numeric ID in that history and in the current store is not a duplicate live
+task. The historical files are intentionally not loaded or renumbered by the
+current task store. Keep their contents and paths as evidence.
+
+Completed current tasks are archived only after their literal acceptance
+criteria and completion evidence pass. Historical blocked records retain the
+unperformed/superseded acceptance items they describe; a later successful release
+does not retroactively complete them.
diff --git a/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md b/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md
index 52573e32..025d5e6a 100644
--- a/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md
+++ b/docs/tasks/active/TASK-0097-context7-ownership-and-docs7-distribution.md
@@ -1,7 +1,7 @@
---
id: "TASK-0097"
title: "Context7 ownership-ready configuration and Docs7 documentation distribution"
-status: active
+status: blocked
schemaVersion: 2
dependencies: []
createdAt: "2026-10-15"
@@ -71,3 +71,31 @@ Revert the documentation/configuration PR; keep historical tags/releases untouch
## Completion notes
PENDING. The GitHub connector provides file edits but no checkout/execution; source checkout failed DNS resolution to github.com (`Could not resolve host: github.com`) and pnpm is unavailable in the container, so the repository-built CLI could not allocate a task ID. `TASK-0097` uses the next unused ID after checked `TASK-0096` as a documented manual fallback. No local validation, Docs7 deploy, claim or badge may be asserted.
+
+### Audit checkpoint 2026-11-17
+
+The source checkout and pinned pnpm are now executable. The guide already says
+the maintainer's teamspace owns the library, but this record has no successful
+Docs7 production build, endpoint or exact-head CI evidence. Literal acceptance
+therefore remains open; do not complete/archive it. TASK-0101 will reconcile the
+local checks and external evidence. TASK-0098 is the next dependency-ready audit
+task; historical blocked TASK-0087/0092/0093 remain untouched.
+
+### Local evidence reconciliation 2026-11-17 (TASK-0101)
+
+- The current official Context7 schema was fetched over HTTPS (200) and
+ `context7.json` validated with AJV plus standard formats: true, no errors.
+- All 32 `docs/docs.json` navigation routes resolve to actual `.md`/`.mdx` files.
+ The required name/colors/navigation and filterSidebar fields match the current
+ official Docs7 quickstart/configuration docs. The guide now links current plan
+ details instead of making the obsolete claim that previews require Pro.
+- Formal compilation of the downloaded upstream Docs7 schema is inconclusive:
+ AJV's Unicode regex mode rejects its unrelated PostHog API-key pattern
+ `^phc\_` (`Invalid escape` at
+ `anyOf.0.properties.integrations.properties.posthog.properties.apiKey.pattern`).
+ The repository configuration contains no PostHog integration. No schema gate
+ was disabled or provider schema rewritten to hide this external incompatibility.
+- **Not run:** Docs7 production build, live site/agent endpoints, account/admin
+ ownership or badge verification. No deployment/account action is authorized
+ by the corrective patch tasks. The task stays blocked, not completed/archived;
+ this external documentation work is not a patch-publication prerequisite.
diff --git a/docs/tasks/active/TASK-0103-authorized-patch-publication-and-public-surface-.md b/docs/tasks/active/TASK-0103-authorized-patch-publication-and-public-surface-.md
new file mode 100644
index 00000000..bb5ed7f4
--- /dev/null
+++ b/docs/tasks/active/TASK-0103-authorized-patch-publication-and-public-surface-.md
@@ -0,0 +1,142 @@
+---
+id: "TASK-0103"
+title: "Authorized patch publication and public-surface verification"
+status: pending
+schemaVersion: 2
+dependencies:
+ - "TASK-0102"
+ - "TASK-0105"
+createdAt: "2026-11-17"
+completedAt: null
+---
+
+
+## Purpose
+
+Publish and independently verify the compatible patch through the repository's
+PR and Marketplace-first, npm-second controlled-release process.
+
+## Explicit user authorization (2026-11-17)
+
+The goal objective authorizes scoped file changes/tests/docs/Git operations;
+feature-branch commits and ordinary pushes; PR creation and merge to master;
+creation/push of a NEW next-patch tag (planned v0.5.5); VS Code Marketplace
+publication; tag-triggered npm OIDC Trusted Publishing; and GitHub Release
+creation with audited VSIX assets. This is authorization for these exact actions
+in this task, not permission for direct master push or credential disclosure.
+Force push/reset/rebase/history rewrite/tag movement/deletion, workflow dispatch
+or rerun, deployments, secret/permission changes and legacy .NET releases remain
+prohibited. No release artifact may be overwritten.
+
+## Scope
+
+- Push the fully committed branch, create a reviewable PR and wait for successful
+ exact-head CI (all Node 22/24 ร OS jobs, extension/Electron, consumer smokes).
+- Merge through the existing PR procedure; verify final master SHA and checks.
+- Build/audit the exact release VSIX; publish outside workflow with already
+ authorized maintainer authentication if available, otherwise provide the exact
+ audited artifact/command and request the missing user authentication step.
+- Verify Marketplace target BEFORE pushing the new tag. Let the tag-triggered
+ release workflow perform npm OIDC publication and GitHub Release.
+- Verify registry/latest/fresh npx + SDK + MCP, clean external Action consumer
+ from the new tag, Marketplace/VSIX/Release identity and checksums.
+- Only after live success, update stable pointer/current install pins through a
+ follow-up PR with exact-head CI; record final master/task evidence truthfully.
+
+## Out of scope
+
+- Direct master push, workflow dispatch/rerun, deployment or site publication;
+ credential creation/storage; tag or immutable version replacement; changes to
+ unrelated repositories; closing old blocked tasks without literal evidence.
+
+## Affected files
+
+- Active/archive task evidence, `release-state.json`, current stable install
+ references after live success, PR/release notes via UTF-8 body files; ignored
+ VSIX/tarball/checksum outputs only.
+
+## Dependencies
+
+TASK-0102 and all prior tasks. Missing Marketplace authentication is a real
+external blocker; do independent authorized work first, never partial-publish npm.
+
+## Required tests
+
+- Exact-head PR CI, post-merge CI, target absence, rebuilt VSIX preflight,
+ Marketplace live reads, tag-trigger release run, npm latest/shasum/consumer
+ smokes, SDK/MCP entrypoints, tag Action consumer, Release asset checksum,
+ stable-pointer parity, final ACKit/Git cleanliness.
+
+## Acceptance criteria
+
+- [ ] PR merged only after all exact-head CI checks pass; master SHA verified.
+- [ ] Marketplace target visible before new immutable tag triggers npm publication.
+- [ ] npm latest, fresh CLI/SDK/MCP and new-tag external Action consumer pass.
+- [ ] GitHub Release tag/VSIX identity and downloaded asset checksum pass.
+- [ ] Stable-pointer bookkeeping merged with CI; final master clean/aligned;
+ task evidence and open blockers match the actual public state.
+
+## Test steps
+
+1. Recheck remote HEAD, PR checks, target/tag absence and release prerequisites.
+2. Publish audited Marketplace VSIX using available authorized authentication;
+ never print credentials. Stop the dependent tag/npm sequence if unavailable.
+3. Push new annotated tag only after Marketplace read-back succeeds; monitor
+ the automatic release run and repair only via authorized forward changes.
+4. Independently read all published channels, install in a fresh isolated
+ consumer, compare checksums and merge truthful stable bookkeeping.
+
+## Security considerations
+
+Marketplace-first, npm OIDC/provenance, exact-tag/version checks, no overwrite,
+no credential logging and least privilege remain mandatory. No production data
+or schema migration. No new credential or secret/permission mutation.
+
+## Risks
+
+- Marketplace authentication may require the user. Replicas may be stale; use
+ bounded repeated read-only observations. If release fails, preserve tag and
+ published artifacts, record the exact stage and do not rerun prohibited work.
+
+## Rollback plan
+
+Before publication, forward corrective PR. After publication, only a NEW patch
+can correct artifacts; never overwrite/repoint/delete the released version.
+
+## Completion notes
+
+Plan allocated by repository CLI on 2026-11-17. No publication or tag action yet.
+
+### Publication preflight 2026-11-17
+
+- TASK-0098/0099/0100/0101/0104/0102 are verified and archived. Runtime correction
+ commit `a0e077c`; release preparation `eae5351`; current source/extension 0.5.5.
+ Full local suite: 772 PASS / 3 existing Windows privilege skips; extension
+ 8 unit + 6 Electron PASS; explicit CLI/package/Action consumers, schemas,
+ SARIF validation, offline, production audit and ACKit gates PASS.
+- Local audited VSIX: 414975 bytes, SHA-256
+ `8fa4cfc2f804f1440fcf1c5abe215570b7ee5c4c1762654a53676696c8d9fd9f`;
+ tarball: 497350 bytes, SHA-256
+ `699437eff29c9dbd74ccd7104e2116ea1a384229cfb1b4e65cc49c88fa6b6a7f`.
+- Existing stored Cynrath publisher was found and `vsce@4.1.1 verify-pat Cynrath`
+ exited 0 (publish-right verification). No secret value was printed or written
+ to repository/log files. No new credential or permission was created.
+- Remote master is `64a9c9d56ea36eb475de29d050596b506264a07e`; strict rules require
+ all 12 established CI contexts. No release-owned open PR exists yet. The
+ branch will be pushed only after this status/evidence commit and clean-tree
+ verification. Publishing still waits for exact-head PR and master checks.
+- npm latest/Marketplace are 0.5.4; npm 0.5.5 and remote tag are absent at the
+ preparation read. Stable pointer remains 0.5.4. Recheck immediately before
+ publishing; no immutable version or existing tag will be changed.
+
+### Hosted CI checkpoint โ publication held
+
+PR #43 exists at head `5daa10f9c572462cd89265b73f0affc5d9bb8578`. Linux and
+Windows verification passed, but Action setup, extension lifecycle and macOS
+diagnostic redaction failed. Required checks correctly block merge. TASK-0105
+owns the observed corrections and actual new-head CI proof; this task resumes
+afterward. No master merge, Marketplace publication, tag, npm publication or
+GitHub Release has been performed. Docs7 Preview separately reported success;
+it is not evidence of the production/account acceptance in TASK-0097.
+
+Dependencies: TASK-0102
diff --git a/docs/tasks/active/TASK-0105-hosted-ci-action-setup-path-and-extension-refres.md b/docs/tasks/active/TASK-0105-hosted-ci-action-setup-path-and-extension-refres.md
new file mode 100644
index 00000000..93ab5061
--- /dev/null
+++ b/docs/tasks/active/TASK-0105-hosted-ci-action-setup-path-and-extension-refres.md
@@ -0,0 +1,128 @@
+---
+id: "TASK-0105"
+title: "Hosted CI Action setup path and extension refresh race correction"
+status: active
+schemaVersion: 2
+dependencies:
+ - "TASK-0102"
+createdAt: "2026-11-17"
+completedAt: null
+---
+
+
+## Purpose
+
+Correct the actual PR #43 hosted failures before authorized publication. User
+authorized scoped fixes, tests, commits, ordinary branch pushes and PR work on
+2026-11-17. No old workflow run may be dispatched or rerun.
+
+## Scope
+
+- Action dogfood job 134079004647 failed before build: pinned pnpm/action-setup
+ joins GITHUB_WORKSPACE with package_json_file, so the composite's absolute
+ Action manifest path resolves incorrectly. Derive a workspace-relative path
+ to the Action's own pinned packageManager without copying a release number or
+ reading the consumer's packageManager. Test different checkout/consumer paths.
+- Extension job 134079005179 failed the real lifecycle finding assertion.
+ Concurrent watcher/manual refreshes share one abort controller and mutate/re-
+ publish the old snapshot even on cancellation. Serialize refreshes per root,
+ publish fresh completed snapshots atomically, and abort safely on disposal.
+ Preserve the real lifecycle assertion and add overlapping-request coverage.
+- macOS jobs 134079005992/134079006277 failed the diagnostic redaction assertion:
+ actual cwd is /private/var while the supplied temporary path is /var. Redact
+ both declared and canonical aliases, longest first. Keep exact error/stdout/
+ redaction assertions and test an actual link alias where portable.
+- Preserve exact-head CI requirements and all gates; push successor commits to
+ trigger normal PR CI. Rebuild/re-audit changed artifacts before publication.
+
+## Out of scope
+
+- New public SDK/CLI features, dependency upgrades, relaxed tests/timeouts,
+ workflow dispatch/rerun, permission/secret changes, publication or tag actions.
+
+## Affected files
+
+- `action.yml`, a narrow Action manifest-path helper, Action distribution and
+ independent-consumer tests; workspace refresh service and real Electron tests;
+ consumer-command diagnostic helper/tests; affected task/CI guide notes.
+
+## Dependencies
+
+TASK-0102 (and its full audit chain). TASK-0103 waits on this correction.
+
+## Required tests
+
+- Action path/consumer/diagnostic contracts, root lint/format/typecheck/build/full
+ suite, extension strict lint/typechecks/unit/Electron, real exported consumer,
+ offline/ACKit gates and new-head required PR CI including macOS.
+
+## Acceptance criteria
+
+- [x] Pinned pnpm setup reads the Action manifest correctly for local and
+ external consumer layouts; no preparatory dogfood build or mutable version pin.
+- [x] Every explicit overlapping refresh awaits a completed current scan;
+ lifecycle/diagnostics assertions pass with disposal/cancellation respected.
+- [x] Canonical temporary path aliases are fully redacted on macOS and other
+ hosts without weakening the exact stdout/status/path assertions.
+- [~] Local focused/full/host checks and all required exact-head hosted checks
+ pass; failures and corrective evidence are recorded truthfully.
+
+## Test steps
+
+1. Preserve the failed job logs and inspect the pinned setup implementation.
+2. Add overlapping-refresh and path-layout/alias regressions before the fixes;
+ record reproduced failures where the local platform permits.
+3. Apply minimal owner-side changes; run local focused/full/extension/consumer
+ checks and normal successor commits/pushes to PR #43.
+4. Wait for actual new-head CI proof; no reruns, skipped tests or gate bypass.
+
+## Security considerations
+
+Action path comes only from trusted Action metadata and the workspace context,
+not consumer-controlled tool input. No untrusted consumer script is installed.
+Maintain root-bound file access, offline execution, credential redaction and
+strict types. No data migration, production mutation or permission change.
+
+## Risks
+
+- Queueing changes refresh timing; preserve completed-snapshot semantics without
+ performance claims and test actual overlapping commands in the host.
+- Path aliases differ by OS; local link fixtures supplement, but never replace,
+ required real macOS CI evidence.
+
+## Rollback plan
+
+Forward corrective commit/PR only; no history rewrite or immutable artifact change.
+
+## Completion notes
+
+Planned from actual hosted failures on PR head
+`5daa10f9c572462cd89265b73f0affc5d9bb8578`. Source investigation verified pinned
+pnpm/action-setup readTarget uses path.join(GITHUB_WORKSPACE, packageJsonFile).
+The existing lifecycle and macOS redaction assertions exposed real owner-side
+defects; none will be removed or turned into warnings.
+
+### Local corrective evidence 2026-11-17
+
+- Pinned upstream source confirms path.join(workspace, input). The new locator
+ resolves the Action's own canonical manifest to a relative input, validates its
+ exact packageManager pin, and handles distinct checkout/workspace directories.
+ Its contract reads the target with the same path.join operation while a consumer
+ has a deliberately different pin. Real exported consumer PASS with that locator.
+- New real-host overlap regression failed before the service fix: [false,true]
+ instead of [true,true]. Per-root request queues and fresh snapshot objects now
+ publish only completed/non-disposed results. After-fix Electron: 7 PASS,
+ including the unchanged lifecycle assertion; 8 host-free unit tests PASS.
+- Diagnostic helper now redacts declared and realpath aliases longest first.
+ Both exact failure/status/stdout assertions remain; a real directory link/
+ junction test covers canonical output without depending on a machine path.
+- Focused root contracts: 4 files / 32 PASS. Full root suite: 126 files PASS,
+ 774 PASS / 3 unchanged Windows privilege-dependent symlink skips (777 total).
+ Root lint/format/typecheck/build, schema regeneration/no drift, extension strict
+ lint/typechecks/build, cold Action consumer, offline and ACKit doctor/task doctor
+ and git diff --check PASS. No timeout, assertion or publish gate was weakened.
+- Required hosted checks are still unproven for the successor commit. This task
+ remains active until the new exact-head matrix/Action/extension checks pass;
+ no old run will be rerun. No publication or tag action has occurred.
+
+Dependencies: TASK-0102
diff --git a/docs/tasks/archive/TASK-0098-action-threshold-and-self-contained-source-distr.md b/docs/tasks/archive/TASK-0098-action-threshold-and-self-contained-source-distr.md
new file mode 100644
index 00000000..fbcd9996
--- /dev/null
+++ b/docs/tasks/archive/TASK-0098-action-threshold-and-self-contained-source-distr.md
@@ -0,0 +1,114 @@
+---
+id: "TASK-0098"
+title: "Action threshold and self-contained source distribution"
+status: completed
+schemaVersion: 2
+dependencies:
+ []
+createdAt: "2026-11-17"
+completedAt: 2026-11-17
+---
+
+
+## Purpose
+
+Restore reliable Action threshold enforcement and make a clean tag consumable
+without pre-existing ignored build output. User authorized this repository audit,
+local changes, tests, commits, branch pushes and PRs on 2026-11-17.
+
+## Scope
+
+- Confirmed: the tracked handwritten `dist/action/index.js` overwrites a threshold
+ failure with CLI status 0. No Action TypeScript source exists, and the referenced
+ CLI/runtime dependencies are absent from Git tags.
+- Move the owning runtime to strict TypeScript; preserve the existing inputs,
+ outputs, read-only status/drift projection, annotations and optional SARIF.
+- Use a source-built composite bootstrap under ADR-0034: pinned Node/pnpm actions,
+ frozen dependency install and build in the action checkout, then offline CLI
+ execution against the consumer. Do not commit generated `dist`.
+- Preserve nonzero CLI errors, ignore policy-suppressed findings when applying the
+ Action threshold, reject invalid threshold/input syntax, and bound child execution.
+
+## Out of scope
+
+- Changing CLI/SDK contracts, release ordering, telemetry, automatic SARIF upload,
+ unrelated architecture, legacy .NET artifacts or credentials.
+
+## Affected files
+
+- `action.yml`, `src/action/**`, tracked legacy Action entry, Action contracts,
+ projection tests, offline gates, `.github/workflows/ackit-action-dogfood.yml`,
+ `docs/guides/ci.md`, ADR-0034 and decision index.
+
+## Dependencies
+
+None. Successor TASK-0099 starts after local acceptance is verified and committed.
+
+## Required tests
+
+- Focused Action behavior/security/consumer tests; projection and composition
+ parity; `pnpm lint`, `format:check`, `typecheck`, `build`, `test`;
+ offline-egress, ACKit doctor/task doctor/scan and `git diff --check`.
+
+## Acceptance criteria
+
+- [x] Threshold breach fails; below-threshold and suppressed findings pass;
+ CLI nonzero/invalid input/timeout errors remain failures.
+- [x] Optional SARIF is canonical 2.1.0 with actual package identity and valid
+ relative locations; outputs exist only when their files exist.
+- [x] Clean exported Action source installs/builds separately from an unrelated
+ consumer fixture and scans it without consumer dependencies or build output.
+- [x] Dogfood exercises the bootstrap without a preparatory build; focused and
+ affected full tests plus quality/offline/ACKit checks pass.
+
+## Test steps
+
+1. Reproduce old exit-code overwrite and missing clean-tag runtime from inspected
+ source; record the exact change and regression results.
+2. Exercise real CLI scan on clean/breaching/suppressed fixtures and a CLI usage
+ failure. Validate SARIF shape and injection-safe argv handling.
+3. Export tracked/planned source into an isolated action checkout, frozen-install
+ and build it, execute from a separate Git fixture, then run affected full gates.
+
+## Security considerations
+
+Bootstrap dependency download is a workflow setup operation, not product egress.
+Only trusted Action source and frozen lockfile may build; never execute consumer
+scripts. Inputs cross through environment variables and argv, never shell code.
+No secrets, permission changes, data migrations or production operations.
+
+## Risks
+
+- Bootstrap needs registry connectivity and adds setup cost. Document it; runtime
+ remains offline. Preserve existing public Action behavior and canonical outputs.
+
+## Rollback plan
+
+Forward corrective PR for the focused commits; immutable tags remain untouched.
+No reset, rebase, force push or release mutation is authorized.
+
+## Completion notes
+
+Verified 2026-11-17 on Windows / Node 26.13.1 / pinned pnpm 11.22.0.
+
+- Root cause confirmed in the old tracked handwritten entry: after setting
+ threshold failure to 1, `result.status` reset it to 0. The entry also depended
+ on ignored CLI files absent from a tag. Strict owning source now builds both
+ entries, preserves CLI nonzero codes, and filters suppressed threshold inputs.
+- The canonical SARIF writer replaces the divergent hand-built report (which
+ hardcoded an old tool version). Output/annotation/timeout/input regressions
+ are covered. The tracked legacy `dist` entry is removed from Git; generated
+ outputs stay ignored.
+- `pnpm run smoke:action` PASS: clean exported source, independent frozen install
+ and build, unrelated consumer with no dependencies/dist, high threshold 0,
+ low threshold 1, CLI invalid-option 2, SARIF 2.1.0 and source-version parity.
+- Focused Action/projection/composition/offline tests: 5 files, 29 tests PASS.
+ Full `pnpm test --maxWorkers=2`: 118 files PASS; 735 tests PASS, 3 existing
+ platform-conditional symlink tests skipped (Windows privilege probe).
+- `pnpm lint`, `pnpm format:check`, `pnpm typecheck`, `pnpm build`, offline-egress
+ (203 files), doctor, task doctor, `scan --ci` (exit 0), text hygiene and
+ `git diff --check` PASS. No new unsuppressed High/Critical finding.
+- Dogfood contract proves no preparatory install/build; hosted exact-head
+ execution and the OS/Node matrix are explicit TASK-0103 release prerequisites.
+- No data migration, credential, permission or publication action. Successor:
+ TASK-0099 (CI/extension gates). Forward PR correction is the rollback path.
diff --git a/docs/tasks/archive/TASK-0099-ci-extension-gates-schema-drift-and-artifact-int.md b/docs/tasks/archive/TASK-0099-ci-extension-gates-schema-drift-and-artifact-int.md
new file mode 100644
index 00000000..2ba21bda
--- /dev/null
+++ b/docs/tasks/archive/TASK-0099-ci-extension-gates-schema-drift-and-artifact-int.md
@@ -0,0 +1,136 @@
+---
+id: "TASK-0099"
+title: "CI extension gates schema drift and artifact integrity"
+status: completed
+schemaVersion: 2
+dependencies:
+ - "TASK-0098"
+createdAt: "2026-11-17"
+completedAt: 2026-11-17
+---
+
+
+## Purpose
+
+Make every extension validation failure visible to CI and keep schema, version,
+CLI/package consumer and VSIX integrity gates effective across patch releases.
+User authorized scoped changes, tests, commits, branch pushes and PRs on 2026-11-17.
+
+## Scope
+
+- Confirmed CI masks extension lint, unit and Electron failures with shell
+ fallbacks, and hardcodes the source version/VSIX filename.
+- Remove bypasses and correct underlying lint/test defects. Add usable extension
+ scripts and narrowly scoped formatting configuration if necessary.
+- Pre-implementation inspection also found fabricated Electron assertions,
+ standalone unit tests importing the host-only `vscode` module, CommonJS
+ bundling of SDK `import.meta.url` asset lookups, and string-prefix finding path
+ checks. Replace these with real host/data assertions, a tested pure diagnostic
+ boundary, and a resource-aware bundle without changing the public SDK.
+- The first real host run then proved an SDK defect: `scanRepository` documents
+ built-in rules plus optional extra rules but passes only `extraRules` (empty by
+ default) to the pipeline. Restore the existing built-in contract with a focused
+ SDK regression before rerunning extension tests; this is required for real
+ extension findings and remains backward-compatible with the documented API.
+- Add schema drift and CLI smoke to CI; preserve real-tarball consumer smoke.
+- Derive extension version from manifests, strengthen parity guard and packaged
+ VSIX inspection, and keep release security gates and Marketplace-first order.
+
+## Out of scope
+
+- Dependency upgrades, permission or protection changes, workflow dispatch/rerun,
+ release publication and unrelated extension UI redesign.
+
+## Affected files
+
+- `.github/workflows/ci.yml`, extension scripts/source/tests/configuration as
+ required by real failures, extension build/resource metadata, parity
+ scripts/contracts and VSIX integrity checks.
+- `src/api/scan-repository.ts` and focused SDK scanning tests for the observed
+ missing-catalog defect; no new API or dependencies.
+
+## Dependencies
+
+TASK-0098. TASK-0100 follows this task.
+
+## Required tests
+
+- Root lint/format/typecheck/build/test, schema drift, CLI/package smokes;
+ extension typecheck/lint/unit/Electron/build; VSIX package/content checks;
+ workflow contracts, version parity, offline-egress and ACKit gates.
+
+## Acceptance criteria
+
+- [x] Lint, unit and Electron commands propagate real failures with no bypass.
+- [x] Extension source/test typechecks and lint/unit/Electron tests actually pass.
+- [x] CI has schema drift, CLI/package smoke, version parity and VSIX integrity
+ checks; source version and package filename are derived, not release literals.
+- [x] VSIX manifest/README/CHANGELOG identity, file allowlist, size and secret
+ checks pass; release fail-closed gates remain effective.
+- [x] Bundled SDK version/templates load inside the extension host and finding
+ navigation/diagnostics cannot resolve traversal or sibling-prefix paths.
+
+## Test steps
+
+1. Run the unmasked extension checks and fix observed failures, recording counts.
+2. Add workflow contracts that reject suppressed exit codes and missing checks;
+ test version-parity negative probes against dynamic workflow configuration.
+3. Package an actual VSIX and inspect packaged content, then run affected gates.
+
+## Security considerations
+
+No credential, data, migration or permission changes. Preserve strict types and
+all existing publish gates. Electron uses a disposable local workspace.
+
+## Risks
+
+- Previously hidden failures may require focused source/test fixes. Preserve
+ assertions and validate Electron behavior in an actual VS Code host.
+
+## Rollback plan
+
+Forward corrective PR; no weakening checks, history rewriting or tag changes.
+
+## Completion notes
+
+Verified 2026-11-17; source/extension remain at the existing 0.5.4 during audit.
+
+- Removed all three CI exit-code fallbacks. Added schema drift, CLI smoke and
+ dynamic source/extension/VSIX parity gates; the existing real-tarball jobs stay.
+ Pinned packaging/probes to published vsce 4.1.1. Release retains every original
+ preflight, absence, Marketplace-first, npm OIDC and immutable-artifact gate;
+ the portable VSIX audit is an additional pre-publish check.
+- Unmasked lint initially failed (4 errors/2 warnings). The old standalone unit
+ suite required host-only `vscode` and the Electron suite contained unconditional
+ assertions/catches. Production diagnostic/path logic now has 8 passing host-free
+ tests; Electron has 6 passing real data/command/diagnostic/lifecycle tests on
+ VS Code 1.146.0 (exit 0). No test failure fallback or disabled assertion remains.
+- Host tests exposed SDK's empty default rule list, now restored to built-ins
+ plus extras. SDK scan/cancellation tests: 6 PASS. Initial runtime packaging
+ errors were corrected through the real host; the final bundled SDK identity,
+ templates and readiness calculation pass. Finding paths reject traversal,
+ sibling prefixes and escaping directory links, with real filesystem tests.
+- Source maps were actually found in the first VSIX because the old ignore
+ matched only top-level maps. `**/*.map` now excludes them. Final audited VSIX:
+ 31 entries, 375515 bytes, SHA-256
+ `ac731ccd09af55f23726dd7a16d329118e3ceefcd97bc5027a44fb0effadc2fd`.
+ Manifest/XML/SDK/README/CHANGELOG, profiles/roles, icon, path/file list, ZIP
+ bounds/CRC, size and credential-material checks PASS. Seven gate contracts
+ reject version/resource drift, unexpected files, actual synthetic key/token
+ material and payload corruption; detector header text is correctly accepted.
+- Focused workflow/version/VSIX/SDK suites: 5 files / 69 tests PASS.
+ Full `pnpm test --maxWorkers=2`: 120 files PASS; 745 tests PASS, 3 unchanged
+ Windows privilege-dependent symlink skips. The full suite also exercises
+ isolated real-tarball consumers.
+- Root lint/format/typecheck/build, extension source/test typechecks/lint/build,
+ schema generation with zero drift, CLI smoke, version parity, offline-egress
+ (204 files), text hygiene, doctor/task doctor, `scan --ci` exit 0 and
+ `git diff --check` PASS. No suppression/baseline or permission change.
+- Separate audit discovery: registry audit of unchanged production dependencies
+ returns 40 advisories (1 critical/11 high). Dependency remediation belongs to
+ the preplanned TASK-0101 audit, outside this task's explicit no-upgrade scope;
+ TASK-0102/0103 cannot release without its disposition and verification.
+- Successor TASK-0100: MCP schema/reference/CI hint parity. Hosted CI remains a
+ TASK-0103 prerequisite; no publication, tag or remote push occurred here.
+
+Dependencies: TASK-0098
diff --git a/docs/tasks/archive/TASK-0100-mcp-schema-documentation-and-ci-hint-parity.md b/docs/tasks/archive/TASK-0100-mcp-schema-documentation-and-ci-hint-parity.md
new file mode 100644
index 00000000..3c45a489
--- /dev/null
+++ b/docs/tasks/archive/TASK-0100-mcp-schema-documentation-and-ci-hint-parity.md
@@ -0,0 +1,103 @@
+---
+id: "TASK-0100"
+title: "MCP schema documentation and CI hint parity"
+status: completed
+schemaVersion: 2
+dependencies:
+ - "TASK-0099"
+createdAt: "2026-11-17"
+completedAt: 2026-11-17
+---
+
+
+## Purpose
+
+Align the documented read-only MCP contract with actual schemas and give the
+advertised `ackit_scan.ci` option CLI-compatible exit hint semantics.
+Scoped edits/tests/commits/PRs are user-authorized (2026-11-17).
+
+## Scope
+
+- Confirmed: docs advertise removed `root` and `includeGlobs` arguments; `ci` is
+ accepted but unused, so report-only scans hint failure as if CI was requested.
+- Correct documentation without reopening root overrides or arbitrary file
+ inclusion. Wire `ci` to the advisory exit hint while retaining report content.
+- Add schema/documentation and real-fixture behavioral contracts.
+- Startup inspection also confirmed that CLI `--root` is accepted globally but
+ the MCP side-effect entry ignores it. Bind only the startup root through an
+ explicit stdio serve function; preserve ACKIT_ROOT/cwd fallbacks and never add
+ a per-tool root override. Verify precedence via real CLI stdio clients.
+
+## Out of scope
+
+- New tools, write capabilities, SDK upgrades, changed root/security boundaries,
+ transport redesign and broader error-format changes.
+
+## Affected files
+
+- `src/mcp/server.ts`, `docs/reference/mcp.md`, MCP contract/integration tests.
+- `src/mcp/stdio.ts`, CLI MCP registration and startup-root integration tests.
+
+## Dependencies
+
+TASK-0099. TASK-0101 follows this task.
+
+## Required tests
+
+- MCP conformance, stdio, cancellation, root-boundary and cross-surface tests;
+ root lint/format/typecheck/build/full tests; offline and ACKit gates.
+
+## Acceptance criteria
+
+- [x] Docs list precisely the tool input properties; no per-call root or pack
+ includeGlobs is reintroduced.
+- [x] Report-only scan hints 0, `ci: true` hints 1 only for unsuppressed findings
+ at the configured threshold; clean/suppressed cases hint 0.
+- [x] Cancellation, stdio purity, root confinement and CLI/SDK/MCP parity pass.
+
+## Test steps
+
+1. Compare live `tools/list` schemas to the reference table in a contract test.
+2. Call scan with default/false/true CI on real clean/breaching/suppressed fixtures.
+3. Run MCP/security/parity subsets followed by the affected full gates.
+
+## Security considerations
+
+No network/write capability, data migration or permission change. The server
+continues to bind a canonical root once at construction. The hint is advisory;
+tool calls never terminate the server process.
+
+## Risks
+
+- Consumers relying on the incorrect default hint must request `ci: true`;
+ document this patch correction. No argument removal from the actual API.
+
+## Rollback plan
+
+Forward corrective PR limited to MCP implementation/docs/tests; no tag changes.
+
+## Completion notes
+
+Verified 2026-11-17 on Windows / Node 26.13.1 / pnpm 11.22.0.
+
+- Actual `tools/list` properties for all 16 tools now match the reference table.
+ The docs no longer advertise per-call root or pack includeGlobs. No removed
+ security-sensitive input was restored.
+- `ci` was accepted but unused. Default/false scans now hint 0; true hints 1 at
+ an unsuppressed policy threshold and 0 for clean/suppressed fixtures. Reports
+ remain available, the hint is advisory, and the server stays responsive.
+- CLI accepted global `--root` but imported a side-effect entry that read only
+ environment/cwd. An explicit stdio serve function now receives the startup
+ root. Real CLI stdio clients prove flag-over-environment, environment-over-cwd
+ and cwd fallback, with paths containing spaces. Direct stdio entry still works.
+- MCP/stdio/cancellation/status projection suites: 7 files, 30 tests PASS.
+ Filesystem/adversarial boundary subset: 23 PASS / 2 existing privilege skips.
+ Final full `pnpm test --maxWorkers=2`: 122 files PASS; 754 PASS / 3 unchanged
+ Windows privilege-dependent symlink skips (757 total).
+- `pnpm lint`, `format:check`, `typecheck`, `build`, offline-egress, doctor,
+ task doctor, `scan --ci` exit 0 and `git diff --check` PASS.
+- No public SDK export change, new tool, network/write capability, data migration,
+ permission or publication action. Successor TASK-0101 owns docs/portability and
+ the already identified dependency-security audit. Forward PR is rollback.
+
+Dependencies: TASK-0099
diff --git a/docs/tasks/archive/TASK-0101-documentation-task-integrity-portability-and-cro.md b/docs/tasks/archive/TASK-0101-documentation-task-integrity-portability-and-cro.md
new file mode 100644
index 00000000..56fa3f6d
--- /dev/null
+++ b/docs/tasks/archive/TASK-0101-documentation-task-integrity-portability-and-cro.md
@@ -0,0 +1,151 @@
+---
+id: "TASK-0101"
+title: "Documentation task integrity portability and cross-surface audit"
+status: completed
+schemaVersion: 2
+dependencies:
+ - "TASK-0100"
+createdAt: "2026-11-17"
+completedAt: 2026-11-17
+---
+
+
+## Purpose
+
+Audit maintained documentation, task integrity and runtime boundaries; fix
+verified scoped defects while preserving historical evidence. User authorized
+necessary edits, tests, commits and PRs on 2026-11-17.
+
+## Scope
+
+- Check README links, Docs7 routes/schema, Context7 config, ADR references and
+ live task IDs versus the frozen legacy namespace. Preserve legacy task files.
+- Reconcile TASK-0097 with actual repository/CI/external hosting evidence; close
+ and archive only if every literal acceptance criterion passes.
+- Inspect machine-specific fixtures, cross-surface exit contracts, cancellation,
+ bounded processes, filesystem/traversal/secret boundaries, dependencies,
+ offline behavior and packaging. Fix confirmed in-scope defects with tests.
+- Registry audit on 2026-11-17 found 40 advisories in the unchanged production
+ graph (1 critical/11 high). Inspect primary advisory ranges and reachability;
+ perform only necessary compatible security updates (SDK 1.x, Zod 4.x and
+ affected transitives), with frozen lockfile/schema/contract/runtime checks.
+ No major-version migration or indiscriminate dependency refresh.
+- Record source-grounded findings and distinguish external validation gaps.
+
+## Out of scope
+
+- Rewriting historical ADR/task evidence; casually closing TASK-0087/0092/0093;
+ hosted account setup/deployment; speculative refactoring or unrelated dependency upgrades.
+
+## Affected files
+
+- README and maintained docs/configuration, task records, focused fixture/tests,
+ documentation checks; runtime files only for confirmed audit defects.
+- Root package manifest/lockfile only for necessary audited dependency fixes;
+ regenerate schemas only if the validated generator actually changes them.
+- `examples/sdk-consumer.mjs` and SDK reference signatures: inspection found
+ string roots where the actual scanner requires `{ canonicalPath }` and stale
+ rule-pack/readiness signatures. Verify the corrected example on a real fixture.
+
+## Dependencies
+
+TASK-0100. TASK-0102 follows; external Docs7 setup is not a patch-release prerequisite.
+
+## Required tests
+
+- Local link/route/config validation, documentation smoke, portability/security
+ and cross-surface tests, dependency audit, full affected gates and ACKit checks.
+
+## Acceptance criteria
+
+- [x] Maintained README links, docs routes, Context7 config and ADR references
+ resolve; active/archive task IDs are unique and legacy collisions explained.
+- [x] Machine-specific test literals are either portable synthetic fixtures or
+ replaced; historical proof remains intact.
+- [x] Audit results record exact evidence and no unresolved new High/Critical
+ finding remains in release scope.
+- [x] TASK-0097 status reflects real evidence; incomplete external acceptance
+ stays explicitly blocked and historical blocked tasks remain unchanged.
+
+## Test steps
+
+1. Inspect current source/security tests and published documentation schemas.
+2. Verify all maintained local links/routes and task namespace integrity; run
+ actual CLI documentation quickstart in a disposable fixture.
+3. Run targeted boundary/portability/cancellation tests and dependency audit,
+ then affected full checks. Record any external hosting/account blocker.
+
+## Security considerations
+
+Use source review and existing defensive tests with synthetic fixtures; no live
+attack probes, real secrets or production data. No permission/data migrations.
+Do not change suppression rules or baselines merely to obtain a passing scan.
+
+## Risks
+
+- Historical root-level task IDs intentionally overlap the live TypeScript
+ namespace. External Docs7 ownership/build evidence may be unavailable.
+
+## Rollback plan
+
+Forward corrective PR; retain historical records and immutable release artifacts.
+
+## Completion notes
+
+Verified 2026-11-17 on Windows / Node 26.13.1 / pnpm 11.22.0.
+
+- Fixed 12 broken README link occurrences by pointing to existing owning
+ references/concepts/extension docs. All 32 Docs7 navigation routes resolve.
+ Checked ADR IDs across 30 maintained files: no unresolved reference.
+ Task store has 103 records / 103 unique live IDs; the new task README explains
+ the separate root-level historical namespace. No historical record was moved,
+ deleted, renumbered or falsely completed.
+- The SDK example and cancellation snippet passed a path string to an API that
+ requires `{ canonicalPath }`. They now resolve a portable canonical root;
+ the real example runs on an unrelated one-file fixture and finds its marker.
+ Corrected rule-pack/readiness signatures, config-loading description and
+ overly broad cancellation claims without changing the public SDK API.
+- Personal Windows profile literals in two content-only scanner fixtures became
+ `fixture-user`; they never accessed that path. Generic Windows drive/case
+ vectors remain intentionally synthetic. Maintained product docs/tests contain
+ no former machine-specific user/repository path. Historical evidence is intact.
+- Registry production audit initially returned 40 advisories (1 critical,
+ 11 high). Necessary compatible updates: MCP SDK 1.30.0 -> 1.32.2, Zod 4.4.3 ->
+ 4.6.7 and affected SDK transitives. Direct dependency major versions and all
+ unrelated direct dependencies remain unchanged. Frozen install PASS.
+ `pnpm audit --prod --json` now exits 0, zero advisories at every severity.
+ Primary patch evidence: [SDK 1.32.2](https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.32.2),
+ [Zod advisory](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5),
+ [proxy-addr advisory](https://github.com/advisories/GHSA-jqcg-44mw-7w3h).
+- Full development-tool audit still exits 1: 19 pre-existing advisories
+ (6 high / 11 moderate / 2 low), confined to Mocha/glob/esbuild/Vitest/Vite
+ development paths, not the production graph or packaged VSIX runtime.
+ Mocha's serialize-javascript use is in its parallel worker pool; both harnesses
+ run serial TDD. No .mocharc YAML payload is supplied; glob patterns are fixed
+ test-discovery patterns. esbuild serves no development HTTP endpoint here;
+ Vitest runs without its API/UI and product code imports none of these tools.
+ Arbitrary major tool migrations are outside this patch; these metadata
+ advisories are disclosed, not suppressed or reported as a clean full audit.
+- Zod regenerated three tracked schemas, replacing string/null anyOf branches
+ with equivalent type arrays. Recursive normalized comparison against HEAD
+ proved equivalence in all three; a second generation has no unstaged drift.
+- Focused documentation/SDK/portable-pack/security/MCP/API suites: 11 files /
+ 48 tests PASS. Full suite: 124 files PASS; 758 tests PASS / 3 unchanged Windows
+ privilege-dependent symlink skips (761 total). Extension typechecks/lint/build,
+ 8 unit and 6 real Electron host tests PASS after the dependency update.
+ Audited VSIX: 31 entries / 414645 bytes / SHA-256
+ `e24783d4a19ce45587e69f6a73fccd4b3f31d95e73a85517bf5cba7bab9e9e95`.
+- Root lint/format/typecheck/build, schema stability, actual documentation
+ quickstart, version parity, offline-egress (204 files), config/doctor/task
+ doctor/skills (4 skills, 0 issues), `scan --ci` exit 0, text hygiene and
+ `git diff --check` PASS. Full-suite tarball consumers also PASS.
+- Context7 validates against the downloaded official schema. The upstream
+ Docs7 schema has an unrelated invalid Unicode regex; production hosting,
+ endpoints and account verification are **Not run**. TASK-0097 records the
+ exact external gap and remains blocked. TASK-0087/0092/0093 stay untouched.
+- No new confirmed High/Critical finding remains in the shipped/runtime scope.
+ No credentials, permissions, data migrations, deployment, tag or publication
+ action. Successor TASK-0102 prepares the compatible patch; hosted matrix and
+ final publication remain explicit TASK-0103 prerequisites.
+
+Dependencies: TASK-0100
diff --git a/docs/tasks/archive/TASK-0102-patch-release-preparation-and-full-validation.md b/docs/tasks/archive/TASK-0102-patch-release-preparation-and-full-validation.md
new file mode 100644
index 00000000..1c4ce224
--- /dev/null
+++ b/docs/tasks/archive/TASK-0102-patch-release-preparation-and-full-validation.md
@@ -0,0 +1,147 @@
+---
+id: "TASK-0102"
+title: "Patch release preparation and full validation"
+status: completed
+schemaVersion: 2
+dependencies:
+ - "TASK-0101"
+ - "TASK-0104"
+createdAt: "2026-11-17"
+completedAt: 2026-11-17
+---
+
+
+## Purpose
+
+Prepare the next compatible patch only after fixing and verifying the audit
+chain. npm latest and Marketplace were both independently read as 0.5.4 on
+2026-11-17, so the planned source version is 0.5.5 if no breaking change emerges.
+
+## Scope
+
+- Align source/extension manifests, lockfile if affected, source-facing README,
+ root/extension CHANGELOG and extension README/packaged metadata.
+- Preserve `release-state.json.publishedStable = 0.5.4` and stable install pins
+ until TASK-0103 proves all public channels at the new version (ADR-0029).
+- Execute the entire requested local verification matrix and audit VSIX/tarball.
+- Record authorization, exact evidence, risks and release-ready decision.
+- Correct the final read-only Marketplace visibility probe: TASK-0094 records
+ that the 0.5.4 release's last one-shot read saw a stale replica after successful
+ publication. Add bounded retries while requiring exact target visibility and
+ retaining exit 91 on exhaustion; no publish order, permission or gate changes.
+
+## Out of scope
+
+- Publication/tag creation before validation, dependency upgrades, speculative
+ source changes, changing historical version references or public stable early.
+
+## Affected files
+
+- Root/extension manifests and release docs, relevant lockfile metadata, task
+ evidence; ignored local packages/checksums are never tracked.
+- `.github/workflows/release.yml` final visibility read and its focused workflow
+ contract, planned before implementing this demonstrated release-wrapper fix.
+
+## Dependencies
+
+TASK-0101 and TASK-0104. TASK-0103 requires all acceptance below and exact-head PR CI.
+
+## Required tests
+
+- Frozen install; lint/format/typecheck/build/gen:schemas/no drift; full tests;
+ CLI/package/doc smokes; config/doctor/task doctor/skills/instructions/scan;
+ extension typechecks/lint/unit/Electron/build/package; VSIX integrity;
+ Action clean-consumer, release/version parity, offline and text hygiene gates.
+
+## Acceptance criteria
+
+- [x] Source/extension/package docs are coupled at the next absent patch;
+ published-stable claims remain truthful until publication.
+- [x] All required local checks pass with exact counts/commands recorded;
+ no skipped mandatory tests or unresolved release-scope security finding.
+- [x] Actual tarball/VSIX audited, SHA-256 recorded and release notes reviewed.
+- [x] Final diff and ACKit checks pass; all pre-release work is committed and
+ the tree is clean before an authorized push.
+
+## Test steps
+
+1. Recheck npm/Marketplace versions and target absence; couple source metadata.
+2. Run the required checks with repository-pinned pnpm 11.22.0. Environment
+ preflight: PowerShell 7.6.9/Git 2.56.1/Node 26.13.1 work; broken global pnpm
+ 12.21.0 launchers are bypassed by an ignored isolated 11.22.0 toolchain.
+3. Build/audit packages and record checksums, then review final diff/state.
+
+## Security considerations
+
+No secrets in outputs/artifacts; no data/migration/permission changes. User
+explicitly authorized scoped commits, ordinary branch push and PR creation.
+No workflow dispatch, rerun, deployment or direct master push is authorized.
+
+## Risks
+
+- Hosted Node 22/24 and Linux/macOS verification is required in TASK-0103; local
+ Windows Node 26 evidence alone never proves that matrix. Existing historical
+ blocked tasks retain their real status.
+
+## Rollback plan
+
+Forward corrective PR before release; never reuse or move immutable versions.
+
+## Completion notes
+
+Final local validation 2026-11-17, after TASK-0104 corrective verification:
+
+- Source/extension/packaged metadata 0.5.5; stable pointer/install pins remain
+ 0.5.4 as required by ADR-0029. npm/Marketplace both re-read 0.5.4; target npm
+ 0.5.5 returns E404 and remote v0.5.5 tag is absent. No breaking public SDK/CLI
+ export/argument removal. Source README build instructions now use the real
+ package selector and audited bundled VSIX command.
+- Pinned pnpm 11.22.0 frozen install PASS; root lint, format, typecheck, build,
+ version 0.5.5 and schema generation/no drift PASS. Full current code suite:
+ 125 files PASS, 772 tests PASS / 3 unchanged Windows privilege-dependent
+ symlink skips (775 total). Release/version/tag/VSIX/docs subset also passed.
+- CLI smoke, explicit real-tarball package consumer smoke, documentation command
+ smoke and clean Action source consumer PASS. The Action consumer now exercises
+ scan/optimize/drift thresholds, CLI error preservation, legacy no-op and
+ canonical CLI/Action optimize SARIF equality with no consumer runtime files.
+- Final extension source/test typechecks, strict lint, build, 8 unit and 6 real
+ Electron host tests PASS at 0.5.5. An initial command batch used an incorrect
+ relative toolchain prefix; it was cancelled and not counted. The verified
+ root-cwd run explicitly reported pnpm 11.22.0 and all actual checks above.
+- Audited artifacts in ignored `artifacts/release-0.5.5/`:
+ - `ackit-vscode-0.5.5.vsix`: 31 entries, 414975 bytes, SHA-256
+ `8fa4cfc2f804f1440fcf1c5abe215570b7ee5c4c1762654a53676696c8d9fd9f`.
+ - `cynrath-agent-context-kit-0.5.5.tgz`: 497350 bytes, SHA-256
+ `699437eff29c9dbd74ccd7104e2116ea1a384229cfb1b4e65cc49c88fa6b6a7f`.
+ Actual VSIX manifest/XML/SDK/README/CHANGELOG, templates, file list, icon,
+ bounded ZIP extraction/CRC, size and secret checks PASS. Local checksum file
+ contains filenames/hashes only. Extracted 0.5.5 release notes pass text hygiene.
+- Production dependency audit: zero known advisories (TASK-0101 has the explicit
+ separate development-tool advisory disposition). Offline-egress, config,
+ doctor/task doctor, skills (4/0 issues), instructions, scan --ci (exit 0),
+ text hygiene, version parity and git diff --check PASS.
+- Final Marketplace read now has six bounded attempts with exact target
+ comparison and exit 91 retained. Focused workflow contracts PASS; all original
+ publish-order/security/absence/OIDC/artifact gates remain. No dispatch/rerun,
+ permission, credential or deployment action.
+- Final diff reviewed. The implementation/evidence commit and clean-tree proof
+ are the remaining Git criterion before completion. Hosted OS/Node matrix,
+ protected PR merge and all publication actions belong to TASK-0103.
+
+Git criterion verified: implementation/evidence commit
+`eae5351fd3df07106a83a8bb12935241ed69f8bd` exists and `git status --short --branch`
+shows only the branch header (clean tree). All pre-release implementation is
+committed before any push. This closure record follows the observed proof.
+
+### Dependency checkpoint 2026-11-17
+
+Source/extension metadata is coupled at 0.5.5, stable remains 0.5.4, npm target
+and remote tag are absent. The versioned full suite passed 758 tests (3 unchanged
+Windows privilege skips), extension 8 unit/6 Electron tests passed, and the final
+visibility-read contract passed. The actual clean Action consumer then failed
+at frozen install with an opaque diagnostic; source review also found optimize
+suggestions omitted from Action threshold projection. TASK-0104 owns corrective
+verification before this task resumes final checks. All working changes remain
+preserved. No push, tag, PR merge or publication has occurred.
+
+Dependencies: TASK-0101
diff --git a/docs/tasks/archive/TASK-0104-action-optimize-projection-and-cold-consumer-cor.md b/docs/tasks/archive/TASK-0104-action-optimize-projection-and-cold-consumer-cor.md
new file mode 100644
index 00000000..857d89a6
--- /dev/null
+++ b/docs/tasks/archive/TASK-0104-action-optimize-projection-and-cold-consumer-cor.md
@@ -0,0 +1,152 @@
+---
+id: "TASK-0104"
+title: "Action optimize projection and cold consumer corrective verification"
+status: completed
+schemaVersion: 2
+dependencies:
+ - "TASK-0101"
+createdAt: "2026-11-17"
+completedAt: 2026-11-17
+---
+
+
+## Purpose
+
+Correct the final-audit gaps in the Action's advertised optimize command and
+clean-consumer bootstrap before TASK-0102/0103 may proceed. Scoped edits, tests,
+commits and PR work are authorized by the 2026-11-17 goal.
+
+## Scope
+
+- Confirmed source gap: the typed Action wrapper reads only report.findings,
+ while CLI optimize emits report.suggestions; its severity threshold is ignored.
+- Restore optimize projections without changing the original JSON report or
+ scanner behavior. Reuse the canonical SARIF writer with source suggestion IDs,
+ severities and relative locations; do not invent a parallel report format.
+- The same scanner-only validation rejects advertised `drift check` findings
+ (`code/detail`, blocking/warning). Add its explicit projection, preserving raw
+ JSON and CLI codes; map blocking to high and warning to medium for Action
+ thresholds. Global task drift has no invented file location in SARIF.
+- The shared SARIF writer currently emits raw path characters. Encode URI path
+ segments for spaces, fragment/query characters and Unicode per SARIF 2.1.0
+ section 3.10.4, preserving path separators and the existing report contract.
+- CLI optimize has its own raw-path SARIF construction. Route that existing
+ format through the same typed suggestion projection and canonical writer, so
+ CLI and Action reports stay semantically identical and URI-safe.
+- The real clean-consumer smoke failed at its frozen install with an empty error
+ because the helper reads only stderr. Surface safe stdout/error/status details,
+ diagnose the actual bootstrap failure, and fix its source contract without
+ bypassing frozen install, build or process exit checks.
+- Extend focused and actual consumer regressions for optimize and bootstrap.
+
+## Out of scope
+
+- New public CLI/SDK features, untrusted rule execution, network in product code,
+ unrelated dependency upgrades, publication, permission or credential changes.
+
+## Affected files
+
+- `src/action/runtime.ts`, canonical SARIF input typing if required,
+ `tests/unit/action/runtime.test.ts`, Action distribution contracts,
+ `scripts/action-consumer-smoke.mjs`, `action.yml` only if the observed bootstrap
+ contract requires correction, and affected CI guide/task evidence.
+- `src/cli/commands/optimize.ts` for its existing SARIF format only; JSON and
+ business logic remain unchanged.
+- A small adjacent consumer-command helper to isolate real subprocess diagnostic
+ testing from the expensive repository export/install fixture. The first full
+ run had 771 passes/1 failure: the diagnostic test ended with empty stderr
+ before its expected marker, while focused/real consumer checks passed. Test
+ the same actual failing child/status/stdout/redaction boundary directly; do
+ not raise timeouts, remove assertions or skip the full consumer check.
+
+## Dependencies
+
+TASK-0101 (including TASK-0098). TASK-0102 is temporarily pending on this task;
+its existing version/docs/workflow changes are preserved on the same branch.
+
+## Required tests
+
+- Action/scanner/SARIF/parity contracts, real clean-source consumer including
+ optimize; lint/format/typecheck/build and affected full tests; offline/ACKit
+ doctor/task doctor/scan and `git diff --check`.
+
+## Acceptance criteria
+
+- [x] Optimize above/below-threshold and CLI-error cases return correct codes;
+ original JSON remains unchanged and canonical SARIF has source IDs/locations.
+- [x] Real exported source frozen-installs and builds, then scan/optimize work
+ from an independent repository with no consumer dependencies/dist.
+- [x] A failed consumer command reports a useful sanitized status/cause and
+ remains a hard failure; no frozen/build/threshold test is skipped or masked.
+- [x] SARIF artifact URIs encode reserved/Unicode path characters correctly.
+- [x] Nonempty drift reports remain available, with documented severity mapping
+ and valid location-free SARIF results for task-level findings.
+- [x] Focused/full affected quality, offline and ACKit checks pass with evidence.
+
+## Test steps
+
+1. Add the optimize regression and record its failure against the current wrapper.
+2. Improve only the consumer diagnostic, reproduce its frozen-install failure,
+ then fix the verified cause at the owning bootstrap/export surface.
+3. Validate optimize JSON/SARIF/thresholds and rerun the actual clean-consumer flow.
+4. Run affected full gates; record real results before completion/commit, then
+ immediately resume TASK-0102's final release preparation.
+
+## Security considerations
+
+No environment/credential dump. Redact scratch/source paths in diagnostics.
+Only trusted Action source is installed/built; never consumer scripts. Preserve
+offline execution, injection-safe argv, policy suppression and nonzero CLI codes.
+No data migration, deployment, tag or publication operation.
+
+## Risks
+
+- Suggestions differ from scanner findings; projection must preserve their
+ category/identity without weakening scanner schema validation.
+- A bootstrap failure may be environmental; distinguish it using observed output
+ rather than assuming a repository or dependency defect.
+
+## Rollback plan
+
+Forward corrective PR/commit only; preserve all existing work and immutable tags.
+
+## Completion notes
+
+Verified 2026-11-17 on Windows / Node 26.13.1 / pnpm 11.22.0.
+
+- Before-fix optimize regression: expected exit 1, actual 0. Typed projections
+ now handle scanner findings, optimize suggestions and drift code/detail data
+ while preserving original JSON. Scan schemas remain strict; missing expected
+ arrays fail closed. CLI nonzero codes win over threshold results.
+- Drift blocking/warning map to high/medium only in the Action projection.
+ Task-level SARIF omits invented file locations; check-active's successful
+ silent legacy no-op is preserved. CLI optimize and Action share one canonical
+ SARIF suggestion projection/writer. Reserved/Unicode path segments are encoded.
+- Real clean export/frozen install/build/independent consumer PASS repeatedly
+ at 0.5.5: scan/optimize/drift above/below thresholds, actual invalid-option
+ CLI errors, legacy no-op, original reports, and CLI/Action optimize SARIF
+ equality. Consumer supplies no node_modules or dist.
+- The initial opaque install failure was not reproduced; original stdout was
+ unavailable, so no source/environment root cause is invented. Frozen/build
+ gates were unchanged. A bounded process helper now includes stdout/error/status
+ and sanitizes source/fixture paths. Its real failing-child test asserts exact
+ outer exit 1, inner exit 7, stdout cause and path redaction.
+- First full run: 771 PASS / 1 diagnostic-test failure (empty stderr before its
+ expected marker) / 3 existing skips. The diagnostic boundary was isolated from
+ unnecessary full repository export; no timeout was raised and no assertion
+ or consumer gate was removed. Final full run: 125 files PASS; 772 tests PASS,
+ 3 unchanged Windows privilege-dependent symlink skips (775 total).
+- Focused Action/diagnostic/reporting/projection/drift suites: 5 files / 36 PASS.
+ Root lint, format, typecheck, build, doctor/task doctor, scan --ci (exit 0),
+ offline-egress and git diff --check PASS. A transient Windows Biome file-mapping
+ write error cleared on the explicit rerun; final lint/format passed normally.
+- Actual scan/optimize/drift SARIF documents validate against both current
+ [OASIS 2.1.0 errata schema](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json)
+ and the producer-declared SchemaStore schema, with standard format validation.
+ A deliberately invalid URI was rejected by both. No provider schema was edited
+ and URI checks remained enabled.
+- No new public SDK export, dependency, network/runtime capability, credential,
+ permission, deployment, tag or publication change. Forward corrective commit
+ is rollback. Resume TASK-0102 immediately, preserving its metadata/workflow work.
+
+Dependencies: TASK-0101
diff --git a/examples/sdk-consumer.mjs b/examples/sdk-consumer.mjs
index 3e701c78..c719c846 100644
--- a/examples/sdk-consumer.mjs
+++ b/examples/sdk-consumer.mjs
@@ -1,10 +1,11 @@
#!/usr/bin/env node
+import { realpath } from "node:fs/promises";
// Minimal SDK consumer smoke (ESM) โ documented in docs/reference/sdk.md
// Run: node examples/sdk-consumer.mjs (or after `pnpm pack` install via `node -e "import(...)"`)
import { scanRepository } from "@cynrath/agent-context-kit";
-const root = process.cwd();
+const root = { canonicalPath: await realpath(process.cwd()) };
const result = await scanRepository(root, {});
console.log(`sdk-consumer: findings=${result.findings.length} filesScanned=${result.filesScanned}`);
-if (result.findings.length === 0) console.log("no findings (repo may be clean or suppressed)");
+if (result.findings.length === 0) console.log("no findings");
// No process.exit from SDK โ CLI layer owns exit codes
diff --git a/extensions/vscode/.vscodeignore b/extensions/vscode/.vscodeignore
index 3ee8d94b..e89a63a9 100644
--- a/extensions/vscode/.vscodeignore
+++ b/extensions/vscode/.vscodeignore
@@ -3,10 +3,13 @@
src/**
node_modules/**
out/**
+scripts/**
+test-fixture/**
+*.vsix
.gitignore
.eslintrc*
-tsconfig.json
+tsconfig*.json
webpack.config.js
-*.map
+**/*.map
**/*.ts
!dist/extension.js
diff --git a/extensions/vscode/CHANGELOG.md b/extensions/vscode/CHANGELOG.md
index 024c6e5e..955d9070 100644
--- a/extensions/vscode/CHANGELOG.md
+++ b/extensions/vscode/CHANGELOG.md
@@ -1,5 +1,20 @@
# Changelog โ VS Code Extension
+## [0.5.5] - 2026-11-17
+
+- Restored built-in SDK scanning so repository markers and security findings
+ appear in the Findings tree and Problems diagnostics.
+- Bundled SDK identity and built-in profiles/roles resolve inside the packaged
+ extension; readiness now works without relying on checkout files.
+- Finding navigation and diagnostics reject traversal, sibling-prefix paths and
+ directory links escaping the workspace.
+- Overlapping watcher/manual refreshes are serialized per root, so explicit
+ refresh commands return a completed current scan rather than cancelled stale data.
+- Real host-free unit and Electron data/command/lifecycle tests are enforced in CI;
+ VSIX packaging excludes source maps and verifies manifest/README/CHANGELOG parity.
+- Compatible runtime security dependency updates; offline analysis and existing
+ commands/views remain unchanged. Version coupled to the root package at 0.5.5.
+
## [0.5.4] - 2026-09-22
- Recovery: no extension UI behavior change beyond 0.5.3; manifest
diff --git a/extensions/vscode/README.md b/extensions/vscode/README.md
index 8fbe19b0..94efc546 100644
--- a/extensions/vscode/README.md
+++ b/extensions/vscode/README.md
@@ -3,7 +3,7 @@
Offline-first agent readiness for your repository โ directly inside VS Code.
- **Publisher:** `Cynrath` (`Cynrath.ackit-vscode`)
-- **Version:** `0.5.4` (Marketplace stable; source checkouts build `0.5.4`)
+- **Version:** `0.5.5` (extension release metadata; source checkouts build `0.5.5`)
- **Engine:** `VS Code ^1.90.0`
- **Activation:** `onStartupFinished` (debounced, lazy refresh)
- **Category:** `Linters`
diff --git a/extensions/vscode/package.json b/extensions/vscode/package.json
index 7ea198fd..976f4685 100644
--- a/extensions/vscode/package.json
+++ b/extensions/vscode/package.json
@@ -2,7 +2,7 @@
"name": "ackit-vscode",
"displayName": "ACKit Toolkit",
"description": "Offline-first repository readiness, task status, verification-aware workflow and developer tooling for AI-assisted development in VS Code.",
- "version": "0.5.4",
+ "version": "0.5.5",
"publisher": "Cynrath",
"engines": {
"vscode": "^1.90.0"
@@ -101,9 +101,12 @@
}
},
"scripts": {
- "build": "esbuild src/extension.ts --bundle --platform=node --target=node20 --outfile=dist/extension.js --external:vscode --sourcemap",
+ "build": "node scripts/build.mjs",
+ "lint": "biome check src scripts --error-on-warnings",
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
"compile:test": "tsc -p tsconfig.test.json",
- "test": "npm run compile:test && node ./out/test/runTest.js",
+ "test:unit": "npm run compile:test && mocha --ui tdd out/test/suite/unit.test.js --timeout 5000",
+ "test": "node ./out/test/runTest.js",
"pretest": "npm run compile:test"
},
"devDependencies": {
diff --git a/extensions/vscode/scripts/build.mjs b/extensions/vscode/scripts/build.mjs
new file mode 100644
index 00000000..bdc732d5
--- /dev/null
+++ b/extensions/vscode/scripts/build.mjs
@@ -0,0 +1,54 @@
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "esbuild";
+
+const extensionRoot = fileURLToPath(new URL("../", import.meta.url));
+const repoRoot = path.resolve(extensionRoot, "../..");
+const sdkSource = path.join(repoRoot, "src");
+const output = path.join(extensionRoot, "dist");
+const pkg = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8"));
+await mkdir(output, { recursive: true });
+
+await build({
+ absWorkingDir: extensionRoot,
+ entryPoints: ["src/extension.ts"],
+ bundle: true,
+ platform: "node",
+ target: "node20",
+ format: "cjs",
+ outfile: "dist/extension.js",
+ external: ["vscode"],
+ sourcemap: true,
+ banner: {
+ js: '"use strict";\nconst __ackitBundleModuleUrl = (relative) => require("node:url").pathToFileURL(require("node:path").join(__dirname, "sdk", relative)).href;',
+ },
+ plugins: [
+ {
+ name: "bundled-sdk-resources",
+ setup(builder) {
+ builder.onResolve({ filter: /^@cynrath\/agent-context-kit$/ }, () => ({
+ path: path.join(sdkSource, "index.ts"),
+ }));
+ builder.onLoad({ filter: /\.ts$/ }, async ({ path: file }) => {
+ const relative = path.relative(sdkSource, file);
+ if (relative.startsWith("..") || path.isAbsolute(relative)) return;
+ const source = await readFile(file, "utf8");
+ if (!source.includes("import.meta.url")) return;
+ // Preserve canonical module-relative asset lookup inside a CommonJS
+ // bundle. Embed only package-relative paths, never build-machine paths.
+ const virtualPath = JSON.stringify(relative.split(path.sep).join("/"));
+ const moduleUrl = `__ackitBundleModuleUrl(${virtualPath})`;
+ return { contents: source.replaceAll("import.meta.url", moduleUrl), loader: "ts" };
+ });
+ },
+ },
+ ],
+});
+// SDK modules resolve package.json/templates from this bundled package root.
+await writeFile(
+ path.join(output, "package.json"),
+ `${JSON.stringify({ name: pkg.name, version: pkg.version }, null, 2)}\n`,
+);
+await cp(path.join(repoRoot, "templates"), path.join(output, "templates"), { recursive: true });
+console.log(`Extension bundle PASS (${pkg.version}; SDK identity and templates included)`);
diff --git a/extensions/vscode/src/diagnostics.ts b/extensions/vscode/src/diagnostics.ts
new file mode 100644
index 00000000..28a69db4
--- /dev/null
+++ b/extensions/vscode/src/diagnostics.ts
@@ -0,0 +1,35 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+export function diagnosticKind(severity: string): "Error" | "Warning" | "Information" | "Hint" {
+ if (severity === "critical" || severity === "high") return "Error";
+ if (severity === "medium") return "Warning";
+ if (severity === "low") return "Information";
+ return "Hint";
+}
+
+/** Findings may only address existing files inside the canonical workspace. */
+export function resolveFindingPath(root: string, relativePath: string): string | null {
+ if (
+ !relativePath ||
+ relativePath.includes("\0") ||
+ path.win32.isAbsolute(relativePath) ||
+ path.posix.isAbsolute(relativePath)
+ )
+ return null;
+ try {
+ const canonicalRoot = realpathSync(root);
+ const full = realpathSync(path.resolve(canonicalRoot, relativePath.replaceAll("\\", path.sep)));
+ const relative = path.relative(canonicalRoot, full);
+ if (
+ !relative ||
+ relative === ".." ||
+ relative.startsWith(`..${path.sep}`) ||
+ path.isAbsolute(relative)
+ )
+ return null;
+ return full;
+ } catch {
+ return null;
+ }
+}
diff --git a/extensions/vscode/src/extension.ts b/extensions/vscode/src/extension.ts
index 6e35568d..f02498ca 100644
--- a/extensions/vscode/src/extension.ts
+++ b/extensions/vscode/src/extension.ts
@@ -3,10 +3,9 @@ import {
analyzeOptimize,
buildInstructionGraph,
resolveEffectiveStack,
- scanRepository,
- scoreRepository,
} from "@cynrath/agent-context-kit";
import * as vscode from "vscode";
+import { diagnosticKind, resolveFindingPath } from "./diagnostics.js";
import { AckitWorkspaceService } from "./services/ackitWorkspace.js";
let service: AckitWorkspaceService | undefined;
@@ -398,11 +397,8 @@ export async function activate(context: vscode.ExtensionContext) {
service?.getSnapshot()?.root ?? vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? "";
if (!root) continue;
// Only create diagnostics for files that are inside workspace
- const full = path.isAbsolute(f.relativePath)
- ? f.relativePath
- : path.join(root, f.relativePath);
- // Ensure inside root
- if (!full.startsWith(root)) continue;
+ const full = resolveFindingPath(root, f.relativePath);
+ if (full === null) continue;
uri = vscode.Uri.file(full);
} catch {
continue;
@@ -411,14 +407,7 @@ export async function activate(context: vscode.ExtensionContext) {
const col = Math.max(0, (f.column ?? 1) - 1);
// Handle invalid line/col: if 0, use 0,0 range
const range = new vscode.Range(line, col, line, col + 10);
- const severity =
- f.severity === "critical" || f.severity === "high"
- ? vscode.DiagnosticSeverity.Error
- : f.severity === "medium"
- ? vscode.DiagnosticSeverity.Warning
- : f.severity === "low"
- ? vscode.DiagnosticSeverity.Information
- : vscode.DiagnosticSeverity.Hint;
+ const severity = vscode.DiagnosticSeverity[diagnosticKind(f.severity)];
const diag = new vscode.Diagnostic(range, f.message, severity);
diag.code = f.ruleId;
diag.source = "ackit";
@@ -450,6 +439,7 @@ export async function activate(context: vscode.ExtensionContext) {
const roots = service?.getRoots() ?? [];
for (const r of roots) await service?.refreshRoot(r);
vscode.window.showInformationMessage(`ACKit: refreshed ${roots.length} workspace(s)`);
+ return service?.getSnapshot();
}),
vscode.commands.registerCommand("ackit.showGraph", async (nodeId?: string) => {
const snap = service?.getSnapshot();
@@ -502,7 +492,8 @@ export async function activate(context: vscode.ExtensionContext) {
vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ??
"";
if (!root) return;
- const full = path.join(root, finding.relativePath);
+ const full = resolveFindingPath(root, finding.relativePath);
+ if (full === null) return;
const uri = vscode.Uri.file(full);
const doc = await vscode.workspace.openTextDocument(uri);
const editor = await vscode.window.showTextDocument(doc);
@@ -512,8 +503,8 @@ export async function activate(context: vscode.ExtensionContext) {
);
editor.selection = new vscode.Selection(pos, pos);
editor.revealRange(new vscode.Range(pos, pos));
- } catch (e) {
- vscode.window.showErrorMessage(`Could not open finding: ${e}`);
+ } catch {
+ vscode.window.showErrorMessage("Could not open finding.");
}
},
),
diff --git a/extensions/vscode/src/services/ackitWorkspace.ts b/extensions/vscode/src/services/ackitWorkspace.ts
index 041350f1..05531d36 100644
--- a/extensions/vscode/src/services/ackitWorkspace.ts
+++ b/extensions/vscode/src/services/ackitWorkspace.ts
@@ -5,7 +5,6 @@ import {
buildInstructionGraph,
buildStatusReport,
loadAckitConfig,
- resolveEffectiveStack,
scanRepository,
scoreRepository,
validateSkills,
@@ -39,7 +38,9 @@ export class AckitWorkspaceService implements vscode.Disposable {
private snapshots = new Map();
private disposables: vscode.Disposable[] = [];
private debounceTimer: NodeJS.Timeout | undefined;
- private currentAbort: AbortController | undefined;
+ private refreshes = new Map>();
+ private controllers = new Map();
+ private disposed = false;
private readonly _onDidChange = new vscode.EventEmitter();
readonly onDidChange = this._onDidChange.event;
@@ -65,8 +66,11 @@ export class AckitWorkspaceService implements vscode.Disposable {
}
dispose() {
+ if (this.disposed) return;
+ this.disposed = true;
if (this.debounceTimer) clearTimeout(this.debounceTimer);
- this.currentAbort?.abort();
+ for (const controller of this.controllers.values()) controller.abort();
+ this.controllers.clear();
this._onDidChange.dispose();
for (const d of this.disposables) d.dispose();
}
@@ -94,6 +98,7 @@ export class AckitWorkspaceService implements vscode.Disposable {
}
async refreshAll(): Promise {
+ if (this.disposed) return;
const roots = this.getRoots();
for (const root of roots) {
await this.refreshRoot(root);
@@ -101,30 +106,46 @@ export class AckitWorkspaceService implements vscode.Disposable {
}
private scheduleRefresh() {
+ if (this.disposed) return;
if (this.debounceTimer) clearTimeout(this.debounceTimer);
this.debounceTimer = setTimeout(() => {
+ this.debounceTimer = undefined;
void this.refreshAll();
}, 400);
}
- async refreshRoot(root: string): Promise {
- // Cancel previous
- this.currentAbort?.abort();
+ refreshRoot(root: string): Promise {
+ if (this.disposed) return Promise.resolve();
+ // A watcher must not cancel an explicit caller and return stale data.
+ // Each root publishes complete snapshots in request order.
+ const previous = this.refreshes.get(root) ?? Promise.resolve();
+ const current = previous.then(() => this.performRefreshRoot(root));
+ this.refreshes.set(root, current);
+ return current.finally(() => {
+ if (this.refreshes.get(root) === current) this.refreshes.delete(root);
+ });
+ }
+
+ private async performRefreshRoot(root: string): Promise {
+ if (this.disposed) return;
const ac = new AbortController();
- this.currentAbort = ac;
+ this.controllers.set(root, ac);
const signal = ac.signal;
- const snapshot: WorkspaceSnapshot = this.snapshots.get(root) ?? {
- root,
- scan: null,
- readiness: null,
- graph: null,
- diagnostics: null,
- optimize: null,
- taskStatus: null,
- error: null,
- updatedAt: 0,
- };
+ const oldSnapshot = this.snapshots.get(root);
+ const snapshot: WorkspaceSnapshot = oldSnapshot
+ ? { ...oldSnapshot }
+ : {
+ root,
+ scan: null,
+ readiness: null,
+ graph: null,
+ diagnostics: null,
+ optimize: null,
+ taskStatus: null,
+ error: null,
+ updatedAt: 0,
+ };
try {
// Avoid scanning own cache/dist
@@ -142,16 +163,16 @@ export class AckitWorkspaceService implements vscode.Disposable {
// Use scoreRepository with minimal inputs
const readiness = scoreRepository(
{
- graph: graph as never,
- pack: pack as never,
+ graph,
+ pack,
scan,
- skills: skills as never,
- policy: { findings: [] } as never,
- tasks: { dirExists: true, totalTasks: 0 } as never,
+ skills,
+ policy: { findings: [] },
+ tasks: { dirExists: true, totalTasks: 0 },
},
{},
);
- snapshot.readiness = readiness as unknown as ScoreReport;
+ snapshot.readiness = readiness;
} catch {
snapshot.readiness = null;
}
@@ -203,9 +224,12 @@ export class AckitWorkspaceService implements vscode.Disposable {
if ((e as DOMException).name === "AbortError") return;
snapshot.error = (e as Error).message;
} finally {
- snapshot.updatedAt = Date.now();
- this.snapshots.set(root, snapshot);
- this._onDidChange.fire(root);
+ if (this.controllers.get(root) === ac) this.controllers.delete(root);
+ if (!this.disposed && !signal.aborted) {
+ snapshot.updatedAt = Date.now();
+ this.snapshots.set(root, snapshot);
+ this._onDidChange.fire(root);
+ }
}
}
}
diff --git a/extensions/vscode/src/test/runTest.ts b/extensions/vscode/src/test/runTest.ts
index cdd96195..af365480 100644
--- a/extensions/vscode/src/test/runTest.ts
+++ b/extensions/vscode/src/test/runTest.ts
@@ -1,26 +1,37 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
import * as path from "node:path";
import { runTests } from "@vscode/test-electron";
async function main() {
+ const workspacePath = mkdtempSync(path.join(tmpdir(), "ackit-vscode-test-"));
+ if (
+ path.dirname(workspacePath) !== path.resolve(tmpdir()) ||
+ !path.basename(workspacePath).startsWith("ackit-vscode-test-")
+ )
+ throw new Error("Unsafe test workspace");
try {
const extensionDevelopmentPath = path.resolve(__dirname, "../../");
const extensionTestsPath = path.resolve(__dirname, "./suite/index");
- const workspacePath = path.resolve(__dirname, "../../test-fixture");
- // Create a disposable workspace with a simple fixture
- const { mkdirSync, writeFileSync, existsSync } = await import("node:fs");
- if (!existsSync(workspacePath)) {
- mkdirSync(workspacePath, { recursive: true });
- writeFileSync(path.join(workspacePath, "AGENTS.md"), "# AGENTS\nUse ackit task\n", "utf8");
- writeFileSync(path.join(workspacePath, "README.md"), "# Fixture\n", "utf8");
- }
+ writeFileSync(path.join(workspacePath, "AGENTS.md"), "# AGENTS\nUse ackit task\n", "utf8");
+ writeFileSync(path.join(workspacePath, "README.md"), "# Fixture\n", "utf8");
+ writeFileSync(path.join(workspacePath, "sample.txt"), "TODO: review fixture\n", "utf8");
await runTests({
extensionDevelopmentPath,
extensionTestsPath,
- launchArgs: [workspacePath, "--disable-extensions"],
+ launchArgs: [
+ workspacePath,
+ "--disable-extensions",
+ "--disable-workspace-trust",
+ "--skip-welcome",
+ "--skip-release-notes",
+ ],
});
} catch (err) {
console.error("Failed to run tests", err);
- process.exit(1);
+ process.exitCode = 1;
+ } finally {
+ rmSync(workspacePath, { recursive: true, force: true });
}
}
diff --git a/extensions/vscode/src/test/suite/extension.test.ts b/extensions/vscode/src/test/suite/extension.test.ts
index f255f375..2fc0a207 100644
--- a/extensions/vscode/src/test/suite/extension.test.ts
+++ b/extensions/vscode/src/test/suite/extension.test.ts
@@ -1,120 +1,118 @@
import * as assert from "node:assert";
-import * as vscode from "vscode";
-import * as path from "node:path";
import * as fs from "node:fs";
+import * as path from "node:path";
+import * as vscode from "vscode";
+import type { WorkspaceSnapshot } from "../../services/ackitWorkspace.js";
suite("ACKit Extension Integration", () => {
- test("extension activates", async () => {
+ let root: string;
+ let snapshot: WorkspaceSnapshot;
+ suiteSetup(async () => {
+ const folder = vscode.workspace.workspaceFolders?.[0];
+ assert.ok(folder, "Disposable workspace missing");
+ root = folder.uri.fsPath;
const ext = vscode.extensions.getExtension("Cynrath.ackit-vscode");
assert.ok(ext, "Extension not found");
- if (!ext.isActive) await ext.activate();
+ await ext.activate();
assert.ok(ext.isActive, "Extension not active");
+ snapshot = await vscode.commands.executeCommand("ackit.refresh");
});
- test("ACKit activity container exists", async () => {
- // The activity bar container is registered via package.json; check that views are registered
- // We can't directly query activity bar, but we can check that tree views can be created
+ test("registers every advertised command and view", async () => {
const ext = vscode.extensions.getExtension("Cynrath.ackit-vscode");
- assert.ok(ext);
- // Check contributes.views
- const pkg = ext.packageJSON as { contributes?: { views?: Record> } };
- const views = pkg.contributes?.views?.ackit?.map((v) => v.id) ?? [];
- assert.ok(views.includes("ackit.readiness"), "ackit.readiness view missing");
- assert.ok(views.includes("ackit.findings"), "ackit.findings view missing");
- assert.ok(views.includes("ackit.graph"), "ackit.graph view missing");
- });
-
- test("Readiness tree has real data", async () => {
- // Trigger refresh and check that readiness provider returns data
- await vscode.commands.executeCommand("ackit.refresh");
- // Wait a bit for async refresh
- await new Promise((r) => setTimeout(r, 1500));
- // The tree view should have items; we can't easily query tree data, but we can check that diagnostics are not empty?
- // As a proxy, check that the extension's service has updated
- // For now, just assert that refresh command succeeded without throwing
- assert.ok(true);
- });
-
- test("Findings tree has real data", async () => {
- await vscode.commands.executeCommand("ackit.refresh");
- await new Promise((r) => setTimeout(r, 1000));
- assert.ok(true);
- });
-
- test("Problems diagnostics appear", async () => {
- // After refresh, diagnostics collection should have entries
- await vscode.commands.executeCommand("ackit.refresh");
- await new Promise((r) => setTimeout(r, 1200));
- const diags = vscode.languages.getDiagnostics();
- // At least one diagnostic may exist from fixture, or none if clean โ just ensure no crash
- assert.ok(Array.isArray(diags));
+ assert.ok(ext?.isActive);
+ const pkg = ext.packageJSON as {
+ contributes: { commands: { command: string }[]; views: { ackit: { id: string }[] } };
+ };
+ const commands = await vscode.commands.getCommands(true);
+ for (const command of pkg.contributes.commands)
+ assert.ok(commands.includes(command.command), command.command);
+ for (const view of ["ackit.readiness", "ackit.findings", "ackit.graph", "ackit.tasks"])
+ assert.ok(
+ pkg.contributes.views.ackit.some((item) => item.id === view),
+ view,
+ );
});
-
- test("Instructions-for-current-file works", async () => {
- // Create a test file and try to resolve instructions
- const ws = vscode.workspace.workspaceFolders?.[0];
- if (!ws) return;
- const testFile = path.join(ws.uri.fsPath, "src", "test-current.ts");
- fs.mkdirSync(path.dirname(testFile), { recursive: true });
- fs.writeFileSync(testFile, "console.log('test');", "utf8");
- const uri = vscode.Uri.file(testFile);
- const doc = await vscode.workspace.openTextDocument(uri);
- await vscode.window.showTextDocument(doc);
- // Execute the command; it should not throw
- try {
- await vscode.commands.executeCommand("ackit.instructionsForCurrentFile");
- } catch {
- // The command may be named differently; try again without Thenable.catch
- try {
- await vscode.commands.executeCommand("ackit.instructionsForCurrentFile");
- } catch {
- // ignore
- }
- }
- // Cleanup
- fs.unlinkSync(testFile);
- assert.ok(true);
+ test("service provides real scan, graph, readiness and optimization data", () => {
+ assert.ok(snapshot);
+ assert.strictEqual(snapshot.error, null);
+ assert.ok(
+ snapshot.scan?.findings.some(
+ (finding) => finding.relativePath === "sample.txt" && finding.ruleId === "ACKIT020",
+ ),
+ );
+ assert.ok(snapshot.graph?.nodes.some((node) => node.relativePath === "AGENTS.md"));
+ assert.ok(snapshot.readiness, "SDK identity/templates failed to load");
+ assert.ok(Number.isFinite(snapshot.readiness.overall));
+ assert.ok(Array.isArray(snapshot.optimize));
});
-
- test("graph command works", async () => {
- await vscode.commands.executeCommand("ackit.showGraph");
- assert.ok(true);
+ test("refresh publishes actual ACKit diagnostics for the fixture finding", async () => {
+ const snapshot = await vscode.commands.executeCommand("ackit.refresh");
+ assert.ok(snapshot?.readiness, "Packaged SDK identity/templates failed to load");
+ assert.ok(Number.isFinite(snapshot.readiness.overall));
+ const uri = vscode.Uri.file(path.join(root, "sample.txt"));
+ const diagnostics = vscode.languages
+ .getDiagnostics(uri)
+ .filter((item) => item.source === "ackit");
+ assert.ok(
+ diagnostics.some((item) => item.code === "ACKIT020"),
+ "Fixture diagnostic missing",
+ );
});
-
- test("optimize produces real findings", async () => {
- // Execute optimize command; it should show quick pick or message, not just terminal
- try {
- await vscode.commands.executeCommand("ackit.optimize");
- } catch {}
- assert.ok(true);
+ test("opens a contained finding and refuses traversal", async () => {
+ await vscode.commands.executeCommand("ackit.openFinding", {
+ relativePath: "sample.txt",
+ line: 1,
+ column: 1,
+ });
+ const editor = vscode.window.activeTextEditor;
+ assert.strictEqual(editor?.document.uri.fsPath, path.join(root, "sample.txt"));
+ await vscode.commands.executeCommand("ackit.openFinding", {
+ relativePath: "../outside.txt",
+ line: 1,
+ column: 1,
+ });
+ assert.strictEqual(
+ vscode.window.activeTextEditor?.document.uri.fsPath,
+ editor?.document.uri.fsPath,
+ );
});
-
- test("diagnostics command uses real diagnostics", async () => {
+ test("diagnostics command opens actual JSON output", async () => {
await vscode.commands.executeCommand("ackit.diagnostics");
- // Should open a document with JSON
- await new Promise((r) => setTimeout(r, 800));
- const editor = vscode.window.activeTextEditor;
- // If diagnostics opened a JSON doc, it will be active
- assert.ok(editor || true);
+ const document = vscode.window.activeTextEditor?.document;
+ assert.strictEqual(document?.languageId, "json");
+ const data = JSON.parse(document?.getText() ?? "null") as { config: unknown; tasks: unknown };
+ assert.strictEqual(data.config, "ok");
+ assert.strictEqual(data.tasks, "ok");
});
-
- test("refresh works after file create/change/delete", async () => {
- const ws = vscode.workspace.workspaceFolders?.[0];
- if (!ws) return;
- const tmpFile = path.join(ws.uri.fsPath, `tmp-${Date.now()}.md`);
- fs.writeFileSync(tmpFile, "# Test\n", "utf8");
- await vscode.commands.executeCommand("ackit.refresh");
- await new Promise((r) => setTimeout(r, 800));
- fs.writeFileSync(tmpFile, "# Test changed\n", "utf8");
- await new Promise((r) => setTimeout(r, 800));
- fs.unlinkSync(tmpFile);
- await new Promise((r) => setTimeout(r, 800));
- await vscode.commands.executeCommand("ackit.refresh");
- assert.ok(true);
+ test("service reflects a fixture create/change/delete lifecycle", async () => {
+ const file = path.join(root, "lifecycle.txt");
+ fs.writeFileSync(file, "TODO: lifecycle fixture\n", "utf8");
+ snapshot = await vscode.commands.executeCommand("ackit.refresh");
+ assert.ok(snapshot.scan?.findings.some((finding) => finding.relativePath === "lifecycle.txt"));
+ fs.writeFileSync(file, "Resolved lifecycle fixture\n", "utf8");
+ snapshot = await vscode.commands.executeCommand("ackit.refresh");
+ assert.ok(!snapshot.scan?.findings.some((finding) => finding.relativePath === "lifecycle.txt"));
+ fs.unlinkSync(file);
+ snapshot = await vscode.commands.executeCommand("ackit.refresh");
+ assert.strictEqual(snapshot.error, null);
});
-
- test("extension host does not crash", async () => {
- const ext = vscode.extensions.getExtension("Cynrath.ackit-vscode");
- assert.ok(ext?.isActive);
+ test("overlapping explicit refreshes each return a completed current scan", async () => {
+ const file = path.join(root, "overlap.txt");
+ fs.writeFileSync(file, "TODO: overlapping refresh fixture\n", "utf8");
+ try {
+ const inspect = () =>
+ vscode.commands
+ .executeCommand("ackit.refresh")
+ .then((value) =>
+ Boolean(
+ value?.scan?.findings.some((finding) => finding.relativePath === "overlap.txt"),
+ ),
+ );
+ assert.deepStrictEqual(await Promise.all([inspect(), inspect()]), [true, true]);
+ } finally {
+ fs.unlinkSync(file);
+ await vscode.commands.executeCommand("ackit.refresh");
+ }
});
});
diff --git a/extensions/vscode/src/test/suite/index.ts b/extensions/vscode/src/test/suite/index.ts
index 119ca048..ff2cd579 100644
--- a/extensions/vscode/src/test/suite/index.ts
+++ b/extensions/vscode/src/test/suite/index.ts
@@ -1,11 +1,12 @@
import * as path from "node:path";
-import Mocha from "mocha";
import { glob } from "glob";
+import Mocha from "mocha";
export async function run(): Promise {
const mocha = new Mocha({ ui: "tdd", color: true, timeout: 20000 });
const testsRoot = path.resolve(__dirname, ".");
- const files = await glob("**/*.test.js", { cwd: testsRoot });
+ const files = await glob("**/extension.test.js", { cwd: testsRoot });
+ if (files.length === 0) throw new Error("No Electron integration tests found");
for (const file of files) {
mocha.addFile(path.resolve(testsRoot, file));
}
diff --git a/extensions/vscode/src/test/suite/unit.test.ts b/extensions/vscode/src/test/suite/unit.test.ts
index 2a3de0ea..f799f256 100644
--- a/extensions/vscode/src/test/suite/unit.test.ts
+++ b/extensions/vscode/src/test/suite/unit.test.ts
@@ -1,57 +1,59 @@
import * as assert from "node:assert";
-import * as vscode from "vscode";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { diagnosticKind, resolveFindingPath } from "../../diagnostics.js";
-suite("ACKit Unit Tests", () => {
- test("severity mapping", () => {
- // Verify that findings severity maps to DiagnosticSeverity correctly
- // This is a pure logic test, no VS Code API needed beyond enum
- const map = (sev: string) => {
- if (sev === "critical" || sev === "high") return vscode.DiagnosticSeverity.Error;
- if (sev === "medium") return vscode.DiagnosticSeverity.Warning;
- if (sev === "low") return vscode.DiagnosticSeverity.Information;
- return vscode.DiagnosticSeverity.Hint;
- };
- assert.strictEqual(map("critical"), vscode.DiagnosticSeverity.Error);
- assert.strictEqual(map("high"), vscode.DiagnosticSeverity.Error);
- assert.strictEqual(map("medium"), vscode.DiagnosticSeverity.Warning);
- assert.strictEqual(map("low"), vscode.DiagnosticSeverity.Information);
- assert.strictEqual(map("info"), vscode.DiagnosticSeverity.Hint);
+suite("ACKit diagnostic boundaries (without a VS Code host)", () => {
+ for (const [severity, expected] of Object.entries({
+ critical: "Error",
+ high: "Error",
+ medium: "Warning",
+ low: "Information",
+ info: "Hint",
+ })) {
+ test(`maps ${severity} to ${expected}`, () =>
+ assert.strictEqual(diagnosticKind(severity), expected));
+ }
+ let fixture: string;
+ let root: string;
+ setup(() => {
+ fixture = mkdtempSync(path.join(tmpdir(), "ackit-vscode-unit-"));
+ root = path.join(fixture, "repo");
+ mkdirSync(path.join(root, "src"), { recursive: true });
+ mkdirSync(path.join(fixture, "repo-other"));
+ writeFileSync(path.join(root, "src", "app.ts"), "fixture\n");
+ writeFileSync(path.join(fixture, "repo-other", "outside.txt"), "outside\n");
});
-
- test("path handling โ safe Uri.joinPath", () => {
- const root = "/tmp/workspace";
- const rel = "src/app.ts";
- const uri = vscode.Uri.joinPath(vscode.Uri.file(root), rel);
- assert.ok(uri.fsPath.endsWith("src/app.ts") || uri.fsPath.includes("src"));
- // Ensure that absolute path outside root is not joined blindly
- const evil = "/etc/passwd";
- // Our code should check isInsideRoot before joining
- assert.ok(!evil.startsWith(root));
+ teardown(() => {
+ assert.strictEqual(path.dirname(fixture), path.resolve(tmpdir()));
+ assert.ok(path.basename(fixture).startsWith("ackit-vscode-unit-"));
+ rmSync(fixture, { recursive: true, force: true });
});
-
- test("multi-root selection", () => {
- // Simulate multi-root logic: active editor's folder should be preferred
- // This is a logic test, not requiring actual workspace
- const roots = ["/a", "/b", "/c"];
- const active = "/b/src/file.ts";
- const folder = roots.find((r) => active.startsWith(r));
- assert.strictEqual(folder, "/b");
+ test("resolves a real contained file with portable separators", () => {
+ const expected = realpathSync(path.join(root, "src", "app.ts"));
+ assert.strictEqual(resolveFindingPath(root, "src/app.ts"), expected);
+ assert.strictEqual(resolveFindingPath(root, "src\\app.ts"), expected);
});
-
- test("watch debounce", async () => {
- let count = 0;
- let timer: NodeJS.Timeout | undefined;
- const schedule = () => {
- if (timer) clearTimeout(timer);
- timer = setTimeout(() => count++, 100);
- };
- schedule(); schedule(); schedule();
- await new Promise((r) => setTimeout(r, 250));
- assert.strictEqual(count, 1);
+ test("rejects traversal, sibling-prefix, absolute, empty and NUL paths", () => {
+ for (const relative of [
+ "../repo-other/outside.txt",
+ "..\\repo-other\\outside.txt",
+ path.join(root, "src/app.ts"),
+ "C:\\outside.txt",
+ "",
+ "src\0app.ts",
+ "missing.ts",
+ ]) {
+ assert.strictEqual(resolveFindingPath(root, relative), null, relative);
+ }
});
-
- test("error states", () => {
- const snap = { error: "test error", scan: null } as unknown as { error: string | null; scan: unknown };
- assert.ok(snap.error);
+ test("rejects a directory junction/symlink escaping the workspace", () => {
+ symlinkSync(
+ path.join(fixture, "repo-other"),
+ path.join(root, "link"),
+ process.platform === "win32" ? "junction" : "dir",
+ );
+ assert.strictEqual(resolveFindingPath(root, "link/outside.txt"), null);
});
});
diff --git a/package.json b/package.json
index 6c146835..1037fc12 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@cynrath/agent-context-kit",
- "version": "0.5.4",
+ "version": "0.5.5",
"description": "Agent context and repository readiness toolkit for Codex, Claude Code, Cursor, Copilot, Gemini and MCP-based coding agents. Validates agent instructions, scans repositories, optimizes context and enforces evidence-backed workflows. Offline-first and deterministic.",
"keywords": [
"ackit",
@@ -79,15 +79,16 @@
"test": "vitest run",
"check:text-hygiene": "node scripts/check-text-hygiene.mjs --repo",
"smoke:cli": "node tests/e2e/cli-scaffold.smoke.mjs",
+ "smoke:action": "node scripts/action-consumer-smoke.mjs",
"smoke:package": "node scripts/package-smoke.mjs"
},
"dependencies": {
- "@modelcontextprotocol/sdk": "^1.30.0",
+ "@modelcontextprotocol/sdk": "^1.32.2",
"commander": "^15.0.0",
"ignore": "^7.0.6",
"picomatch": "^4.0.5",
"yaml": "^2.9.0",
- "zod": "^4.4.3"
+ "zod": "^4.6.7"
},
"devDependencies": {
"@biomejs/biome": "^2.5.10",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b7843836..308a0a72 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,8 +9,8 @@ importers:
.:
dependencies:
'@modelcontextprotocol/sdk':
- specifier: ^1.30.0
- version: 1.30.0(supports-color@7.2.0)(zod@4.4.3)
+ specifier: ^1.32.2
+ version: 1.32.2(supports-color@8.1.1)(zod@4.6.7)
commander:
specifier: ^15.0.0
version: 15.0.0
@@ -24,8 +24,8 @@ importers:
specifier: ^2.9.0
version: 2.9.0
zod:
- specifier: ^4.4.3
- version: 4.4.3
+ specifier: ^4.6.7
+ version: 4.6.7
devDependencies:
'@biomejs/biome':
specifier: ^2.5.10
@@ -301,11 +301,11 @@ packages:
cpu: [x64]
os: [win32]
- '@hono/node-server@2.1.1':
- resolution: {integrity: sha512-ELuehkj5VCBdgEw9zs+ivkKwyzzUCSQuE96YmiPvn1ECBoZCczbFXJLeEGMTYjphP6gydh4pHMqEYPVMYUVgQg==}
+ '@hono/node-server@2.1.8':
+ resolution: {integrity: sha512-jdf7FHh6A1lzjpHHQUgxsg2GeER2vMetnAOfeActzcoli6jamlK+NAwL6Dsr5Fl3BS3tYUQzCdtZjU8Qxv7bEA==}
engines: {node: '>=20'}
peerDependencies:
- hono: ^4
+ hono: ^4 || ^5.0.0-0
'@isaacs/cliui@8.0.2':
resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
@@ -321,8 +321,8 @@ packages:
'@jridgewell/trace-mapping@0.3.31':
resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
- '@modelcontextprotocol/sdk@1.30.0':
- resolution: {integrity: sha512-xKd8OIzlqNzcqcNumGAa6g+PW2kjD5vrpcKOnfldAUPP3j7lnqMPwlTXQm8gF+UwH72z0lqaRbjr9hqGz0eITA==}
+ '@modelcontextprotocol/sdk@1.32.2':
+ resolution: {integrity: sha512-SWsVtH/0vULSQStoZ6xxH2K09Li8fXYTMC64ZeogCdpZ3XSi1eCPOByV1OpuJxuI3OcmHhosDWYyii07tpPsLw==}
engines: {node: '>=18'}
peerDependencies:
'@cfworker/json-schema': ^4.1.1
@@ -686,8 +686,8 @@ packages:
resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==}
engines: {node: '>=8'}
- body-parser@2.3.0:
- resolution: {integrity: sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==}
+ body-parser@2.4.0:
+ resolution: {integrity: sha512-Ifk1KcLrxaGt1occQagQNFNNOqRt1LFuehEnHHzB8Z6cRgIxRU1TBaiIsUiCdA+gy5PL7Y1IX31DNKkRmxtXjQ==}
engines: {node: '>=18'}
brace-expansion@2.1.4:
@@ -754,8 +754,8 @@ packages:
resolution: {integrity: sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==}
engines: {node: '>=22.12.0'}
- content-disposition@1.1.0:
- resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
+ content-disposition@2.0.1:
+ resolution: {integrity: sha512-e+H0ZXHSWYrENhQzw1LPuP4oF5MzVKmDU6d3hxlvaPEYLLg62MxtQNPRx4SYSuYJSBUgnQIG4HIN2tEtNv7Dog==}
engines: {node: '>=18'}
content-type@1.0.5:
@@ -832,8 +832,8 @@ packages:
emoji-regex@9.2.2:
resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
- encodeurl@2.0.0:
- resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
+ encodeurl@2.0.3:
+ resolution: {integrity: sha512-mIteYONiEfc4xWf2F1WXovh1c8npzS00vNeiUPdwFF+QlVJni+gNvpQltLMQhob8rew/bWWc/bGTuUr0EUGt0w==}
engines: {node: '>= 0.8'}
es-define-property@1.0.1:
@@ -886,21 +886,21 @@ packages:
resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
engines: {node: '>=12.0.0'}
- express-rate-limit@8.6.2:
- resolution: {integrity: sha512-YH4ru+eOJxQABscKFfRCy9R7x9QFGdezclVMwwgFFndzS2Xnm0uo6B0ABZsLhcpeptGv2qvuJVWlQr9gQZoC3A==}
+ express-rate-limit@8.7.4:
+ resolution: {integrity: sha512-LKBXzX700wz3zAGNNmVnjRI5mEbYkLv7UbMI4+9Xa+JPcg2UZh6AgY/2CZh9RrJjFM5ttC/N1lD+KzyFoZITCw==}
engines: {node: '>= 16'}
peerDependencies:
express: '>= 4.11'
- express@5.2.1:
- resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
+ express@5.3.0:
+ resolution: {integrity: sha512-qCqy1xSoaugxOD4IVHb1ZWdkvCF2W3aE2okKouWj8VwJ+ztskSiXoBnCSJqfKT+cVPJhuJqe9YLbY425+Zh00g==}
engines: {node: '>= 18'}
fast-deep-equal@3.1.3:
resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
- fast-uri@3.1.5:
- resolution: {integrity: sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==}
+ fast-uri@3.1.9:
+ resolution: {integrity: sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==}
fdir@6.5.0:
resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
@@ -1000,8 +1000,8 @@ packages:
resolution: {integrity: sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==}
hasBin: true
- hono@4.13.3:
- resolution: {integrity: sha512-r8AO2mYHoLxSHkgafNeC/BXyb2vWRxD3jem4Ts+ptav8oTG5FIRifAjuJEmZI4bSvvc2ns0GxmIYiZnHqN3mMw==}
+ hono@4.13.18:
+ resolution: {integrity: sha512-H9q/E1XizaWstJxUW881dmLxEj+t/TrGGnyxINkm4+sK0qUwsMtFdo2BWI9Vs3cIS19MU6b6iCijoUoEf4f3DA==}
engines: {node: '>=16.9.0'}
html-escaper@2.0.2:
@@ -1037,8 +1037,8 @@ packages:
inherits@2.0.4:
resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
- ip-address@10.5.0:
- resolution: {integrity: sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g==}
+ ip-address@10.7.6:
+ resolution: {integrity: sha512-00LYkM6byILa9eQIx6qoaXCM40xTLd56AZ4vyaPW3YTyb49VZYPo5xsiAq4tuQ54GH4R7gVdYScJ1B7B77PuTg==}
engines: {node: '>= 12'}
ipaddr.js@1.9.1:
@@ -1109,8 +1109,8 @@ packages:
jackspeak@3.4.3:
resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
- jose@6.2.10:
- resolution: {integrity: sha512-iiW7J9qRFlGxvCOIBDBDxFePQSn7ZMAnrYGhrrOo6siO/MIqwfyilLR27pkfDgUk+raLuzADS8A3S/KLBisc0g==}
+ jose@6.2.17:
+ resolution: {integrity: sha512-wOuK9V1yujQFH5S0ZWmLcDZN7+IKh9bUCC2ZPCf2HDlol3WWHy+PPyNjEI75FXRLMp3vDKQcupP59xhVU95hcg==}
js-tokens@10.0.0:
resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
@@ -1299,8 +1299,8 @@ packages:
resolution: {integrity: sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==}
engines: {node: '>=12.20.0'}
- on-finished@2.4.1:
- resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
+ on-finished@2.4.2:
+ resolution: {integrity: sha512-ATWUv387i+nLD49EiDoOft5scf32Vsdz3ktrQJG9bi7jRFmaXTssvyvj1EmeKVVgvesbqUtvQQvaS2TpTukAZQ==}
engines: {node: '>= 0.8'}
once@1.4.0:
@@ -1372,12 +1372,12 @@ packages:
process-nextick-args@2.0.1:
resolution: {integrity: sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==}
- proxy-addr@2.0.7:
- resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
+ proxy-addr@2.0.8:
+ resolution: {integrity: sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==}
engines: {node: '>= 0.10'}
- qs@6.15.3:
- resolution: {integrity: sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==}
+ qs@6.17.1:
+ resolution: {integrity: sha512-jd3COkaKVgGUW+ZHyEHCG9bH7RoaaiWuMgzsIBjUMVjLAaWGWpoUAVwljVvBHxRu/2qEHnadLGZrkutYUBPQJA==}
engines: {node: '>=0.6'}
randombytes@2.1.0:
@@ -1726,8 +1726,8 @@ packages:
peerDependencies:
zod: ^3.25.28 || ^4
- zod@4.4.3:
- resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
+ zod@4.6.7:
+ resolution: {integrity: sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==}
snapshots:
@@ -1853,9 +1853,9 @@ snapshots:
'@esbuild/win32-x64@0.23.1':
optional: true
- '@hono/node-server@2.1.1(hono@4.13.3)':
+ '@hono/node-server@2.1.8(hono@4.13.18)':
dependencies:
- hono: 4.13.3
+ hono: 4.13.18
'@isaacs/cliui@8.0.2':
dependencies:
@@ -1875,9 +1875,9 @@ snapshots:
'@jridgewell/resolve-uri': 3.1.2
'@jridgewell/sourcemap-codec': 1.5.5
- '@modelcontextprotocol/sdk@1.30.0(supports-color@7.2.0)(zod@4.4.3)':
+ '@modelcontextprotocol/sdk@1.32.2(supports-color@8.1.1)(zod@4.6.7)':
dependencies:
- '@hono/node-server': 2.1.1(hono@4.13.3)
+ '@hono/node-server': 2.1.8(hono@4.13.18)
ajv: 8.20.0
ajv-formats: 3.0.1(ajv@8.20.0)
content-type: 1.0.5
@@ -1885,15 +1885,15 @@ snapshots:
cross-spawn: 7.0.6
eventsource: 3.0.7
eventsource-parser: 3.1.1
- express: 5.2.1(supports-color@8.1.1)
- express-rate-limit: 8.6.2(express@5.2.1(supports-color@8.1.1))(supports-color@7.2.0)
- hono: 4.13.3
- jose: 6.2.10
+ express: 5.3.0(supports-color@8.1.1)
+ express-rate-limit: 8.7.4(express@5.3.0(supports-color@8.1.1))(supports-color@8.1.1)
+ hono: 4.13.18
+ jose: 6.2.17
json-schema-typed: 8.0.2
pkce-challenge: 5.0.1
raw-body: 3.0.2
- zod: 4.4.3
- zod-to-json-schema: 3.25.2(zod@4.4.3)
+ zod: 4.6.7
+ zod-to-json-schema: 3.25.2(zod@4.6.7)
transitivePeerDependencies:
- supports-color
@@ -2113,7 +2113,7 @@ snapshots:
ajv@8.20.0:
dependencies:
fast-deep-equal: 3.1.3
- fast-uri: 3.1.5
+ fast-uri: 3.1.9
json-schema-traverse: 1.0.0
require-from-string: 2.0.2
@@ -2148,15 +2148,15 @@ snapshots:
binary-extensions@2.3.0: {}
- body-parser@2.3.0(supports-color@7.2.0):
+ body-parser@2.4.0(supports-color@8.1.1):
dependencies:
bytes: 3.1.2
content-type: 2.1.0
- debug: 4.4.3(supports-color@7.2.0)
+ debug: 4.4.3(supports-color@8.1.1)
http-errors: 2.0.1
iconv-lite: 0.7.3
- on-finished: 2.4.1
- qs: 6.15.3
+ on-finished: 2.4.2
+ qs: 6.17.1
raw-body: 3.0.2
type-is: 2.1.0
transitivePeerDependencies:
@@ -2227,7 +2227,7 @@ snapshots:
commander@15.0.0: {}
- content-disposition@1.1.0: {}
+ content-disposition@2.0.1: {}
content-type@1.0.5: {}
@@ -2252,12 +2252,6 @@ snapshots:
shebang-command: 2.0.0
which: 2.0.2
- debug@4.4.3(supports-color@7.2.0):
- dependencies:
- ms: 2.1.3
- optionalDependencies:
- supports-color: 7.2.0
-
debug@4.4.3(supports-color@8.1.1):
dependencies:
ms: 2.1.3
@@ -2288,7 +2282,7 @@ snapshots:
emoji-regex@9.2.2: {}
- encodeurl@2.0.0: {}
+ encodeurl@2.0.3: {}
es-define-property@1.0.1: {}
@@ -2347,40 +2341,40 @@ snapshots:
expect-type@1.4.0: {}
- express-rate-limit@8.6.2(express@5.2.1(supports-color@8.1.1))(supports-color@7.2.0):
+ express-rate-limit@8.7.4(express@5.3.0(supports-color@8.1.1))(supports-color@8.1.1):
dependencies:
- debug: 4.4.3(supports-color@7.2.0)
- express: 5.2.1(supports-color@8.1.1)
- ip-address: 10.5.0
+ debug: 4.4.3(supports-color@8.1.1)
+ express: 5.3.0(supports-color@8.1.1)
+ ip-address: 10.7.6
transitivePeerDependencies:
- supports-color
- express@5.2.1(supports-color@8.1.1):
+ express@5.3.0(supports-color@8.1.1):
dependencies:
accepts: 2.0.0
- body-parser: 2.3.0(supports-color@7.2.0)
- content-disposition: 1.1.0
- content-type: 1.0.5
+ body-parser: 2.4.0(supports-color@8.1.1)
+ content-disposition: 2.0.1
+ content-type: 2.1.0
cookie: 0.7.2
cookie-signature: 1.2.2
- debug: 4.4.3(supports-color@7.2.0)
+ debug: 4.4.3(supports-color@8.1.1)
depd: 2.0.0
- encodeurl: 2.0.0
+ encodeurl: 2.0.3
escape-html: 1.0.3
etag: 1.8.1
- finalhandler: 2.1.1(supports-color@7.2.0)
+ finalhandler: 2.1.1(supports-color@8.1.1)
fresh: 2.0.0
http-errors: 2.0.1
merge-descriptors: 2.0.0
mime-types: 3.0.2
- on-finished: 2.4.1
+ on-finished: 2.4.2
once: 1.4.0
parseurl: 1.3.3
- proxy-addr: 2.0.7
- qs: 6.15.3
+ proxy-addr: 2.0.8
+ qs: 6.17.1
range-parser: 1.3.0
- router: 2.2.0(supports-color@7.2.0)
- send: 1.2.1(supports-color@7.2.0)
+ router: 2.2.0(supports-color@8.1.1)
+ send: 1.2.1(supports-color@8.1.1)
serve-static: 2.2.1(supports-color@8.1.1)
statuses: 2.0.2
type-is: 2.1.0
@@ -2390,7 +2384,7 @@ snapshots:
fast-deep-equal@3.1.3: {}
- fast-uri@3.1.5: {}
+ fast-uri@3.1.9: {}
fdir@6.5.0(picomatch@4.0.5):
optionalDependencies:
@@ -2400,12 +2394,12 @@ snapshots:
dependencies:
to-regex-range: 5.0.1
- finalhandler@2.1.1(supports-color@7.2.0):
+ finalhandler@2.1.1(supports-color@8.1.1):
dependencies:
- debug: 4.4.3(supports-color@7.2.0)
- encodeurl: 2.0.0
+ debug: 4.4.3(supports-color@8.1.1)
+ encodeurl: 2.0.3
escape-html: 1.0.3
- on-finished: 2.4.1
+ on-finished: 2.4.2
parseurl: 1.3.3
statuses: 2.0.2
transitivePeerDependencies:
@@ -2489,7 +2483,7 @@ snapshots:
he@1.2.0: {}
- hono@4.13.3: {}
+ hono@4.13.18: {}
html-escaper@2.0.2: {}
@@ -2530,7 +2524,7 @@ snapshots:
inherits@2.0.4: {}
- ip-address@10.5.0: {}
+ ip-address@10.7.6: {}
ipaddr.js@1.9.1: {}
@@ -2583,7 +2577,7 @@ snapshots:
optionalDependencies:
'@pkgjs/parseargs': 0.11.0
- jose@6.2.10: {}
+ jose@6.2.17: {}
js-tokens@10.0.0: {}
@@ -2748,7 +2742,7 @@ snapshots:
obug@2.1.4: {}
- on-finished@2.4.1:
+ on-finished@2.4.2:
dependencies:
ee-first: 1.1.1
@@ -2815,12 +2809,12 @@ snapshots:
process-nextick-args@2.0.1: {}
- proxy-addr@2.0.7:
+ proxy-addr@2.0.8:
dependencies:
forwarded: 0.2.0
ipaddr.js: 1.9.1
- qs@6.15.3:
+ qs@6.17.1:
dependencies:
es-define-property: 1.0.1
side-channel: 1.1.1
@@ -2882,9 +2876,9 @@ snapshots:
'@rolldown/binding-win32-arm64-msvc': 1.2.5
'@rolldown/binding-win32-x64-msvc': 1.2.5
- router@2.2.0(supports-color@7.2.0):
+ router@2.2.0(supports-color@8.1.1):
dependencies:
- debug: 4.4.3(supports-color@7.2.0)
+ debug: 4.4.3(supports-color@8.1.1)
depd: 2.0.0
is-promise: 4.0.0
parseurl: 1.3.3
@@ -2900,33 +2894,17 @@ snapshots:
semver@7.8.5: {}
- send@1.2.1(supports-color@7.2.0):
- dependencies:
- debug: 4.4.3(supports-color@7.2.0)
- encodeurl: 2.0.0
- escape-html: 1.0.3
- etag: 1.8.1
- fresh: 2.0.0
- http-errors: 2.0.1
- mime-types: 3.0.2
- ms: 2.1.3
- on-finished: 2.4.1
- range-parser: 1.3.0
- statuses: 2.0.2
- transitivePeerDependencies:
- - supports-color
-
send@1.2.1(supports-color@8.1.1):
dependencies:
debug: 4.4.3(supports-color@8.1.1)
- encodeurl: 2.0.0
+ encodeurl: 2.0.3
escape-html: 1.0.3
etag: 1.8.1
fresh: 2.0.0
http-errors: 2.0.1
mime-types: 3.0.2
ms: 2.1.3
- on-finished: 2.4.1
+ on-finished: 2.4.2
range-parser: 1.3.0
statuses: 2.0.2
transitivePeerDependencies:
@@ -2938,7 +2916,7 @@ snapshots:
serve-static@2.2.1(supports-color@8.1.1):
dependencies:
- encodeurl: 2.0.0
+ encodeurl: 2.0.3
escape-html: 1.0.3
parseurl: 1.3.3
send: 1.2.1(supports-color@8.1.1)
@@ -3185,8 +3163,8 @@ snapshots:
yocto-queue@0.1.0: {}
- zod-to-json-schema@3.25.2(zod@4.4.3):
+ zod-to-json-schema@3.25.2(zod@4.6.7):
dependencies:
- zod: 4.4.3
+ zod: 4.6.7
- zod@4.4.3: {}
+ zod@4.6.7: {}
diff --git a/schemas/handoff.schema.json b/schemas/handoff.schema.json
index 00307cfa..2c346e32 100644
--- a/schemas/handoff.schema.json
+++ b/schemas/handoff.schema.json
@@ -364,13 +364,9 @@
"type": "boolean"
},
"problemCode": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
+ "type": [
+ "string",
+ "null"
]
},
"changed": {
@@ -395,13 +391,9 @@
]
},
"independenceCode": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
+ "type": [
+ "string",
+ "null"
]
}
},
diff --git a/schemas/instruction-graph.schema.json b/schemas/instruction-graph.schema.json
index b5b91e6e..c88225d9 100644
--- a/schemas/instruction-graph.schema.json
+++ b/schemas/instruction-graph.schema.json
@@ -203,24 +203,16 @@
},
"shadowedBy": {
"default": null,
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
+ "type": [
+ "string",
+ "null"
]
},
"duplicateOf": {
"default": null,
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
+ "type": [
+ "string",
+ "null"
]
}
},
diff --git a/schemas/task.schema.json b/schemas/task.schema.json
index 1716f3f0..98c108d1 100644
--- a/schemas/task.schema.json
+++ b/schemas/task.schema.json
@@ -37,13 +37,9 @@
},
"completedAt": {
"default": null,
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
+ "type": [
+ "string",
+ "null"
]
},
"intentRef": {
diff --git a/scripts/action-consumer-smoke.mjs b/scripts/action-consumer-smoke.mjs
new file mode 100644
index 00000000..86f33dcc
--- /dev/null
+++ b/scripts/action-consumer-smoke.mjs
@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// An independent consumer must work from exported source, without ignored dist.
+// Run through pnpm: pnpm run smoke:action [--ref vX.Y.Z]
+import { spawnSync } from "node:child_process";
+import {
+ copyFileSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runConsumerCommand } from "./consumer-command.mjs";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const work = mkdtempSync(path.join(tmpdir(), "ackit-action-consumer-"));
+// Validate the immutable recursive-cleanup target before any fixture work.
+if (
+ path.dirname(work) !== path.resolve(tmpdir()) ||
+ !path.basename(work).startsWith("ackit-action-consumer-")
+) {
+ throw new Error("Unsafe cleanup boundary");
+}
+const source = path.join(work, "action");
+const consumer = path.join(work, "consumer");
+const pnpmCli = process.env.npm_execpath;
+if (!pnpmCli || !existsSync(pnpmCli)) throw new Error("Run this smoke with pnpm run smoke:action");
+const paths = [
+ "src",
+ "templates",
+ "schemas",
+ "package.json",
+ "pnpm-lock.yaml",
+ "pnpm-workspace.yaml",
+ "tsconfig.json",
+ "tsconfig.build.json",
+ "extensions/vscode/package.json",
+ "action.yml",
+ "scripts/action-package-path.mjs",
+];
+
+function run(command, args, options = {}) {
+ return runConsumerCommand(command, args, { cwd: root, ...options }, [
+ [work, ""],
+ [root, ""],
+ ]);
+}
+
+try {
+ mkdirSync(source);
+ mkdirSync(consumer);
+ const refIndex = process.argv.indexOf("--ref");
+ if (refIndex !== -1) {
+ const ref = process.argv[refIndex + 1];
+ if (!ref || !/^v\d+\.\d+\.\d+$/.test(ref)) throw new Error("Expected exact release tag");
+ const archive = path.join(work, "action.tar");
+ run("git", ["archive", "--format=tar", `--output=${archive}`, ref, ...paths]);
+ run("tar", ["-xf", archive, "-C", source]);
+ } else {
+ const files = run("git", [
+ "ls-files",
+ "--cached",
+ "--others",
+ "--exclude-standard",
+ "-z",
+ "--",
+ ...paths,
+ ])
+ .split("\0")
+ .filter(Boolean);
+ for (const file of files) {
+ const destination = path.resolve(source, file);
+ if (!destination.startsWith(`${source}${path.sep}`)) throw new Error("Invalid export path");
+ mkdirSync(path.dirname(destination), { recursive: true });
+ copyFileSync(path.join(root, file), destination);
+ }
+ }
+ if (existsSync(path.join(source, "dist")) || existsSync(path.join(source, "node_modules")))
+ throw new Error("Export must start without runtime");
+ const manifestOutput = run(
+ process.execPath,
+ [path.join(source, "scripts/action-package-path.mjs")],
+ {
+ cwd: consumer,
+ env: { ...process.env, GITHUB_WORKSPACE: consumer, ACKIT_ACTION_PATH: source },
+ },
+ ).trim();
+ if (!manifestOutput.startsWith("path=")) throw new Error("Action manifest path output missing");
+ const pinnedManifest = JSON.parse(
+ readFileSync(path.join(consumer, manifestOutput.slice(5)), "utf8"),
+ );
+ if (
+ pinnedManifest.packageManager !==
+ JSON.parse(readFileSync(path.join(source, "package.json"), "utf8")).packageManager
+ )
+ throw new Error("Action manifest pin resolved to the consumer");
+ run(
+ process.execPath,
+ [
+ pnpmCli,
+ "install",
+ "--frozen-lockfile",
+ "--ignore-scripts",
+ "--filter",
+ "@cynrath/agent-context-kit",
+ ],
+ { cwd: source },
+ );
+ run(process.execPath, [pnpmCli, "build"], { cwd: source });
+ run("git", ["init", "-q"], { cwd: consumer });
+ writeFileSync(path.join(consumer, "AGENTS.md"), "# Consumer\nReview changes.\n");
+ writeFileSync(path.join(consumer, "sample.txt"), "TODO: review fixture\n");
+ const runAction = (threshold, args = "", expected = 0, command = "scan") => {
+ const outputs = mkdtempSync(path.join(work, "outputs-"));
+ const result = spawnSync(process.execPath, [path.join(source, "dist/action/index.js")], {
+ cwd: consumer,
+ encoding: "utf8",
+ timeout: 60_000,
+ windowsHide: true,
+ env: {
+ ...process.env,
+ INPUT_COMMAND: command,
+ INPUT_ARGS: args,
+ INPUT_FAIL_THRESHOLD: threshold,
+ INPUT_UPLOAD_SARIF: "true",
+ RUNNER_TEMP: outputs,
+ ACKIT_ROOT: consumer,
+ },
+ });
+ if (result.status !== expected)
+ throw new Error(`Action expected ${expected}, got ${result.status}: ${result.stderr}`);
+ return outputs;
+ };
+ const outputs = runAction("high");
+ const report = JSON.parse(readFileSync(path.join(outputs, "ackit-findings.json"), "utf8"));
+ if (!report.findings.some((finding) => finding.relativePath === "sample.txt"))
+ throw new Error("Action did not scan consumer");
+ const sarif = JSON.parse(readFileSync(path.join(outputs, "ackit.sarif"), "utf8"));
+ const version = JSON.parse(readFileSync(path.join(source, "package.json"), "utf8")).version;
+ if (sarif.version !== "2.1.0" || sarif.runs[0].tool.driver.version !== version)
+ throw new Error("SARIF identity mismatch");
+ runAction("low", "", 1);
+ runAction("high", "--unknown-option", 2);
+ const optimizeOutput = runAction("critical", "", 0, "optimize");
+ const optimize = JSON.parse(
+ readFileSync(path.join(optimizeOutput, "ackit-findings.json"), "utf8"),
+ );
+ if (optimize.suggestions.length === 0)
+ throw new Error("Optimize fixture produced no suggestions");
+ const optimizeSarif = JSON.parse(readFileSync(path.join(optimizeOutput, "ackit.sarif"), "utf8"));
+ if (optimizeSarif.runs[0].results.length !== optimize.suggestions.length)
+ throw new Error("Optimize SARIF projection missing suggestions");
+ const cliOptimizeSarif = JSON.parse(
+ run(
+ process.execPath,
+ [path.join(source, "dist/cli/index.js"), "optimize", "--format", "sarif"],
+ { cwd: consumer },
+ ),
+ );
+ if (JSON.stringify(cliOptimizeSarif) !== JSON.stringify(optimizeSarif))
+ throw new Error("CLI/Action optimize SARIF mismatch");
+ runAction("low", "", 1, "optimize");
+ runAction("critical", "--unknown-option", 2, "optimize");
+ runAction("critical", "check-active --ci", 0, "drift");
+ writeFileSync(path.join(consumer, ".gitignore"), ".ackit/\n");
+ run("git", ["config", "user.name", "fixture"], { cwd: consumer });
+ run("git", ["config", "user.email", "fixture@example.invalid"], { cwd: consumer });
+ run("git", ["add", "."], { cwd: consumer });
+ run("git", ["-c", "commit.gpgsign=false", "commit", "-qm", "test: fixture baseline"], {
+ cwd: consumer,
+ });
+ const task = JSON.parse(
+ run(
+ process.execPath,
+ [
+ path.join(source, "dist/cli/index.js"),
+ "--json",
+ "task",
+ "create",
+ "consumer drift fixture",
+ ],
+ { cwd: consumer },
+ ),
+ );
+ const taskFile = path.join(consumer, task.file);
+ const header = /^---\r?\n[\s\S]*?\r?\n---/.exec(readFileSync(taskFile, "utf8"))?.[0];
+ if (!header) throw new Error("Generated task header missing");
+ writeFileSync(
+ taskFile,
+ `${header}\n\n## Affected files\n\n- src/**\n\n## Acceptance criteria\n\n- [ ] fixture\n\n## Completion notes\n\nFixture remains pending.\n`,
+ );
+ writeFileSync(path.join(consumer, "UNPLANNED.md"), "# Fixture drift\n");
+ const driftOutput = runAction("critical", `check ${task.created}`, 0, "drift");
+ const drift = JSON.parse(readFileSync(path.join(driftOutput, "ackit-findings.json"), "utf8"));
+ if (drift.findings.length === 0) throw new Error("Drift fixture produced no findings");
+ runAction("low", `check ${task.created}`, 1, "drift");
+ runAction(
+ "critical",
+ `check ${task.created} --ci`,
+ drift.findings.some((finding) => finding.severity === "blocking") ? 1 : 0,
+ "drift",
+ );
+ if (existsSync(path.join(consumer, "node_modules")) || existsSync(path.join(consumer, "dist")))
+ throw new Error("Consumer must not supply runtime");
+ console.log(
+ `Action external-consumer PASS (${version}; clean source, scan/optimize/drift thresholds, CLI errors, SARIF)`,
+ );
+} finally {
+ rmSync(work, { recursive: true, force: true });
+}
diff --git a/scripts/action-package-path.mjs b/scripts/action-package-path.mjs
new file mode 100644
index 00000000..77e8e12a
--- /dev/null
+++ b/scripts/action-package-path.mjs
@@ -0,0 +1,19 @@
+import { readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// pnpm/action-setup resolves package_json_file with path.join(workspace, input).
+// Always target this Action's manifest, including when the consumer is elsewhere.
+const actionRoot = process.env.ACKIT_ACTION_PATH ?? fileURLToPath(new URL("../", import.meta.url));
+const workspace = realpathSync(process.env.GITHUB_WORKSPACE ?? process.cwd());
+const manifest = realpathSync(path.join(actionRoot, "package.json"));
+const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+if (
+ typeof pkg.packageManager !== "string" ||
+ !/^pnpm@\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+\S+)?$/.test(pkg.packageManager)
+)
+ throw new Error("Action packageManager must pin an exact pnpm version");
+const relative = path.relative(workspace, manifest);
+if (!relative || path.isAbsolute(relative))
+ throw new Error("Action manifest must be workspace-relative for pnpm setup");
+console.log(`path=${relative}`);
diff --git a/scripts/check-version-parity.mjs b/scripts/check-version-parity.mjs
index 3598d887..3b658565 100644
--- a/scripts/check-version-parity.mjs
+++ b/scripts/check-version-parity.mjs
@@ -379,11 +379,21 @@ export function checkParity(overrides = {}) {
failures.push(`ci workflow unreadable: ${error.message}`);
}
if (ci !== "") {
- if (!ci.includes(`'${source}'`)) {
- failures.push(`.github/workflows/ci.yml manifest contract does not assert '${source}'`);
+ if (
+ !ci.includes("node scripts/check-version-parity.mjs") ||
+ !ci.includes("pkg.version!==root.version")
+ ) {
+ failures.push(
+ ".github/workflows/ci.yml must enforce dynamic extension/root version parity",
+ );
}
- if (!ci.includes(`ackit-vscode-${source}.vsix`)) {
- failures.push(`.github/workflows/ci.yml VSIX filename does not track '${source}'`);
+ if (
+ !ci.includes("pkgver=$(node -p \"require('./extensions/vscode/package.json').version\")") ||
+ !ci.includes('vsix="ackit-vscode-' + "$" + '{pkgver}.vsix"')
+ ) {
+ failures.push(
+ ".github/workflows/ci.yml VSIX filename must derive from the extension manifest",
+ );
}
}
}
diff --git a/scripts/check-vsix.mjs b/scripts/check-vsix.mjs
new file mode 100644
index 00000000..c44009eb
--- /dev/null
+++ b/scripts/check-vsix.mjs
@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Inspect the actual VSIX portably, with bounded ZIP extraction and CRC checks.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { inflateRawSync } from "node:zlib";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const file = process.argv[2];
+if (!file) throw new Error("Usage: node scripts/check-vsix.mjs ");
+const zip = readFileSync(file);
+if (zip.length > 2_097_152) throw new Error("VSIX exceeds 2 MB");
+const eocd = zip.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+if (eocd < 0 || eocd < zip.length - 65_557 || eocd + 22 > zip.length)
+ throw new Error("Invalid ZIP directory");
+if (zip.readUInt16LE(eocd + 4) || zip.readUInt16LE(eocd + 6)) throw new Error("Split ZIP refused");
+const count = zip.readUInt16LE(eocd + 10);
+if (count > 3000) throw new Error("Too many VSIX entries");
+let offset = zip.readUInt32LE(eocd + 16);
+let total = 0;
+const entries = new Map();
+const crcTable = Array.from({ length: 256 }, (_, index) => {
+ let value = index;
+ for (let bit = 0; bit < 8; bit++) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+ return value >>> 0;
+});
+const crc32 = (bytes) => {
+ let crc = 0xffffffff;
+ for (const byte of bytes) crc = crcTable[(crc ^ byte) & 255] ^ (crc >>> 8);
+ return (crc ^ 0xffffffff) >>> 0;
+};
+
+for (let index = 0; index < count; index++) {
+ if (offset + 46 > eocd || zip.readUInt32LE(offset) !== 0x02014b50)
+ throw new Error("Invalid ZIP entry");
+ const flags = zip.readUInt16LE(offset + 8);
+ const method = zip.readUInt16LE(offset + 10);
+ const compressed = zip.readUInt32LE(offset + 20);
+ const size = zip.readUInt32LE(offset + 24);
+ const nameLength = zip.readUInt16LE(offset + 28);
+ const extraLength = zip.readUInt16LE(offset + 30);
+ const commentLength = zip.readUInt16LE(offset + 32);
+ const local = zip.readUInt32LE(offset + 42);
+ const end = offset + 46 + nameLength + extraLength + commentLength;
+ if (end > eocd) throw new Error("Truncated ZIP entry");
+ const name = zip
+ .subarray(offset + 46, offset + 46 + nameLength)
+ .toString("utf8")
+ .toLowerCase();
+ if (
+ !name ||
+ name.includes("\\") ||
+ name.startsWith("/") ||
+ name.split("/").some((part) => part === "." || part === "..") ||
+ entries.has(name)
+ )
+ throw new Error("Unsafe/duplicate VSIX path");
+ total += size;
+ if (flags & 1 || ![0, 8].includes(method) || size > 4_194_304 || total > 16_777_216)
+ throw new Error("Unsupported/oversized ZIP entry");
+ if (local + 30 > offset || zip.readUInt32LE(local) !== 0x04034b50)
+ throw new Error("Invalid ZIP local header");
+ const start = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+ if (start + compressed > offset) throw new Error("Invalid ZIP payload bounds");
+ const payload = zip.subarray(start, start + compressed);
+ const bytes =
+ method === 8 ? inflateRawSync(payload, { maxOutputLength: Math.max(1, size) }) : payload;
+ if (bytes.length !== size || crc32(bytes) !== zip.readUInt32LE(offset + 16))
+ throw new Error("VSIX CRC/size mismatch");
+ if (/(^|\/)(node_modules|src|out|scripts|test-fixture)(\/|$)|\.(map|vsix)$/.test(name))
+ throw new Error(`Unexpected packaged file: ${name}`);
+ entries.set(name, bytes);
+ offset = end;
+}
+
+function content(name) {
+ const bytes = entries.get(name);
+ if (!bytes) throw new Error(`Required VSIX file missing: ${name}`);
+ return bytes.toString("utf8");
+}
+const source = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+const extension = JSON.parse(
+ readFileSync(path.join(root, "extensions/vscode/package.json"), "utf8"),
+);
+const manifest = JSON.parse(content("extension/package.json"));
+const sdk = JSON.parse(content("extension/dist/package.json"));
+if (
+ extension.version !== source.version ||
+ manifest.version !== source.version ||
+ sdk.version !== source.version
+)
+ throw new Error("VSIX/source/SDK version mismatch");
+if (
+ manifest.publisher !== "Cynrath" ||
+ manifest.name !== "ackit-vscode" ||
+ manifest.main !== "./dist/extension.js" ||
+ sdk.name !== source.name ||
+ sdk.type
+)
+ throw new Error("VSIX identity/runtime mismatch");
+const xml = content("extension.vsixmanifest");
+const identity = /]+)>/.exec(xml)?.[1] ?? "";
+for (const [attribute, value] of Object.entries({
+ Version: source.version,
+ Publisher: "Cynrath",
+ Id: "ackit-vscode",
+})) {
+ if (new RegExp(`${attribute}="([^"]+)"`).exec(identity)?.[1] !== value)
+ throw new Error(`VSIX XML ${attribute} mismatch`);
+}
+const readme = content("extension/readme.md");
+if (
+ /\*\*Version:\*\* `([^`]+)`/.exec(readme)?.[1] !== source.version ||
+ /source checkouts build `([^`]+)`/.exec(readme)?.[1] !== source.version
+)
+ throw new Error("VSIX README version mismatch");
+for (const marker of ["ackit.status.v1", "verification freshness", "checkpoint freshness"])
+ if (!readme.toLowerCase().includes(marker)) throw new Error(`VSIX README missing ${marker}`);
+if (/^## \[([^\]]+)\]/m.exec(content("extension/changelog.md"))?.[1] !== source.version)
+ throw new Error("VSIX CHANGELOG version mismatch");
+content("extension/dist/extension.js");
+for (const profile of ["codex", "claude", "copilot", "gemini", "generic"])
+ content(`extension/dist/templates/profiles/${profile}.yml`);
+content("extension/dist/templates/roles/verifier.yaml");
+const icon = entries.get("extension/images/icon.png");
+if (
+ !icon ||
+ icon.length <= 1024 ||
+ icon.readUInt32BE(16) < 128 ||
+ icon.readUInt32BE(16) !== icon.readUInt32BE(20)
+)
+ throw new Error("Invalid VSIX icon");
+// A detector's header regex is not a key: require encoded material and footer.
+const secrets =
+ /AKIA[0-9A-Z]{16}|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----\s+[A-Za-z0-9+/=\s]{32,}-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|gh[pousr]_[A-Za-z0-9]{32,}|sk-proj-[A-Za-z0-9_-]{20,}/;
+for (const [name, bytes] of entries) {
+ if (/\.(js|json|md|yml|yaml|xml)$/.test(name) && secrets.test(bytes.toString("utf8")))
+ throw new Error(`Credential pattern in ${name}`);
+}
+console.log(
+ `VSIX integrity PASS (${source.version}; ${entries.size} entries; ${zip.length} bytes; SHA-256 ${createHash("sha256").update(zip).digest("hex")})`,
+);
diff --git a/scripts/consumer-command.mjs b/scripts/consumer-command.mjs
new file mode 100644
index 00000000..2936bb72
--- /dev/null
+++ b/scripts/consumer-command.mjs
@@ -0,0 +1,33 @@
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+
+/** Bounded consumer-tool process boundary; never expose caller paths in errors. */
+export function runConsumerCommand(command, args, options = {}, redactions = []) {
+ const result = spawnSync(command, args, {
+ encoding: "utf8",
+ timeout: 180_000,
+ windowsHide: true,
+ ...options,
+ });
+ if (result.status !== 0) {
+ let detail = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n");
+ const aliases = redactions
+ .flatMap(([value, label]) => {
+ try {
+ return [
+ [value, label],
+ [realpathSync(value), label],
+ ];
+ } catch {
+ return [[value, label]];
+ }
+ })
+ .sort(([left], [right]) => right.length - left.length);
+ for (const [value, label] of aliases) detail = detail.replaceAll(value, label);
+ detail = detail.replace(/[A-Za-z]:[\\/][^\s"'<>]+/g, "");
+ throw new Error(
+ `consumer command failed (exit ${result.status}): ${detail || "no command output"}`,
+ );
+ }
+ return result.stdout;
+}
diff --git a/src/action/index.ts b/src/action/index.ts
new file mode 100644
index 00000000..af3993f1
--- /dev/null
+++ b/src/action/index.ts
@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { runAction } from "./runtime.js";
+
+process.exitCode = runAction();
diff --git a/src/action/runtime.ts b/src/action/runtime.ts
new file mode 100644
index 00000000..d94023bb
--- /dev/null
+++ b/src/action/runtime.ts
@@ -0,0 +1,209 @@
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import {
+ projectOptimizeSuggestions,
+ renderSarif,
+ type SarifFinding,
+} from "../core/reporting/sarif.js";
+import { FindingSchema, SEVERITY_ORDER } from "../core/scanner/types.js";
+
+const SuggestionSchema = z.object({
+ id: z.string(),
+ category: z.string(),
+ severity: z.enum(["high", "medium", "low"]),
+ message: z.string(),
+ evidencePaths: z.array(z.string()),
+ evidence: z
+ .array(z.object({ relativePath: z.string(), line: z.number().int().positive().optional() }))
+ .optional(),
+});
+const DriftFindingSchema = z.object({
+ code: z.string(),
+ severity: z.enum(["blocking", "warning"]),
+ taskId: z.string(),
+ detail: z.string(),
+});
+
+function projectFindings(report: Record): SarifFinding[] {
+ if (report["schemaVersion"] === "ackit.drift-report.v1" && report["findings"] !== undefined) {
+ return DriftFindingSchema.array()
+ .parse(report["findings"])
+ .map((finding) => ({
+ ruleId: finding.code,
+ category: "task-docs-integrity",
+ severity: finding.severity === "blocking" ? "high" : "medium",
+ message: `${finding.taskId}: ${finding.detail}`,
+ evidence: "",
+ fingerprint: JSON.stringify([finding.code, finding.taskId, finding.detail]),
+ suppressed: false,
+ suppressionReason: null,
+ }));
+ }
+ if (report["findings"] !== undefined) return FindingSchema.array().parse(report["findings"]);
+ if (report["suggestions"] === undefined) return [];
+ return projectOptimizeSuggestions(SuggestionSchema.array().parse(report["suggestions"]));
+}
+
+interface CliResult {
+ status: number | null;
+ stdout: string;
+ error?: Error | undefined;
+ signal?: NodeJS.Signals | null | undefined;
+}
+
+interface ActionOptions {
+ env?: NodeJS.ProcessEnv;
+ /** Narrow process boundary for deterministic error/timeout regression tests. */
+ invoke?: (args: string[]) => CliResult;
+ log?: (line: string) => void;
+ error?: (line: string) => void;
+}
+
+/** Quoting groups argv only; no shell expansion or executable interpolation. */
+export function splitActionArgs(input: string): string[] {
+ const args: string[] = [];
+ let current = "";
+ let quote: '"' | "'" | undefined;
+ let started = false;
+ for (const char of input) {
+ if (char === quote) {
+ quote = undefined;
+ } else if (quote === undefined && (char === '"' || char === "'")) {
+ quote = char;
+ started = true;
+ } else if (quote === undefined && /\s/.test(char)) {
+ if (started) args.push(current);
+ current = "";
+ started = false;
+ } else {
+ current += char;
+ started = true;
+ }
+ }
+ if (quote !== undefined) throw new Error("Unclosed quote in Action args");
+ if (started) args.push(current);
+ return args;
+}
+
+function escapeCommand(value: string, property = false): string {
+ const escaped = value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+ return property ? escaped.replace(/:/g, "%3A").replace(/,/g, "%2C") : escaped;
+}
+
+function input(env: NodeJS.ProcessEnv, name: string): string {
+ return (
+ env[`INPUT_${name.toUpperCase().replaceAll("-", "_")}`] ??
+ env[`INPUT_${name.toUpperCase()}`] ??
+ ""
+ );
+}
+
+export function runAction(options: ActionOptions = {}): number {
+ const env = options.env ?? process.env;
+ const log = options.log ?? console.log;
+ const error = options.error ?? console.error;
+ let cliExit = 0;
+ try {
+ const command = input(env, "command") || "scan";
+ const threshold = input(env, "fail-threshold") || "high";
+ const rank = SEVERITY_ORDER.indexOf(threshold as (typeof SEVERITY_ORDER)[number]);
+ if (rank < 0) throw new Error("Invalid fail-threshold");
+ const sarifInput = input(env, "upload-sarif");
+ if (!["", "false", "true"].includes(sarifInput)) throw new Error("Invalid upload-sarif");
+ const args = splitActionArgs(input(env, "args"));
+ const cliPath = fileURLToPath(new URL("../cli/index.js", import.meta.url));
+ const invoke =
+ options.invoke ??
+ ((argv: string[]): CliResult =>
+ spawnSync(process.execPath, argv, {
+ encoding: "utf8",
+ env,
+ maxBuffer: 10 * 1024 * 1024,
+ timeout: 120_000,
+ windowsHide: true,
+ }));
+ const result = invoke([cliPath, command, ...args, "--json"]);
+ // A CLI error always wins; a successful process must never clear a threshold
+ // failure. Signals, timeouts and launch failures must fail closed as well.
+ cliExit = result.status ?? 1;
+ if (result.error || result.signal) {
+ error("::error::ACKit CLI did not complete (launch failure, signal or timeout)");
+ return cliExit || 1;
+ }
+ if (!result.stdout.trim()) {
+ // The managed pre-commit entry intentionally succeeds silently when no
+ // active workflow task exists. Other report-producing commands fail closed.
+ if (cliExit === 0 && command === "drift" && args.includes("check-active")) return 0;
+ error(`::error::ACKit CLI returned no JSON report (exit ${cliExit})`);
+ return cliExit || 1;
+ }
+ const report: unknown = JSON.parse(result.stdout);
+ if (report === null || typeof report !== "object" || Array.isArray(report)) {
+ throw new Error("Invalid CLI JSON report");
+ }
+ const payload = report as Record;
+ const requiredField =
+ command === "scan" || command === "drift"
+ ? "findings"
+ : command === "optimize"
+ ? "suggestions"
+ : undefined;
+ if (requiredField !== undefined && payload[requiredField] === undefined)
+ throw new Error("Missing command report findings");
+ const findings = projectFindings(payload);
+ const activeFindings = findings.filter((finding) => !finding.suppressed);
+ const runnerTemp = env["RUNNER_TEMP"] || tmpdir();
+ mkdirSync(runnerTemp, { recursive: true });
+ const jsonPath = path.join(runnerTemp, "ackit-findings.json");
+ const sarifPath = path.join(runnerTemp, "ackit.sarif");
+ writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+ if (sarifInput === "true") writeFileSync(sarifPath, renderSarif(findings), "utf8");
+
+ const outputPath = env["GITHUB_OUTPUT"];
+ if (outputPath) {
+ appendFileSync(outputPath, `findings-json=${jsonPath}\n`, "utf8");
+ if (sarifInput === "true") appendFileSync(outputPath, `sarif-path=${sarifPath}\n`, "utf8");
+ }
+ for (const finding of activeFindings.slice(0, 10)) {
+ const level =
+ finding.severity === "critical" || finding.severity === "high"
+ ? "error"
+ : finding.severity === "medium"
+ ? "warning"
+ : "notice";
+ const location = finding.relativePath
+ ? ` file=${escapeCommand(finding.relativePath, true)},line=${finding.line ?? 1}`
+ : "";
+ log(`::${level}${location}::${escapeCommand(`${finding.ruleId}: ${finding.message}`)}`);
+ }
+ const summaryPath = env["GITHUB_STEP_SUMMARY"];
+ if (summaryPath) {
+ const rows = [...SEVERITY_ORDER]
+ .reverse()
+ .map(
+ (severity) =>
+ `| ${severity} | ${activeFindings.filter((finding) => finding.severity === severity).length} |`,
+ );
+ appendFileSync(
+ summaryPath,
+ `## ACKit โ ${activeFindings.length} active finding(s)\n\n` +
+ `| Severity | Count |\n|---|---|\n${rows.join("\n")}\n`,
+ "utf8",
+ );
+ }
+ const exceeded = activeFindings.some(
+ (finding) => SEVERITY_ORDER.indexOf(finding.severity) >= rank,
+ );
+ if (exceeded) error(`::error::fail-threshold ${threshold} exceeded`);
+ return cliExit || (exceeded ? 1 : 0);
+ } catch {
+ // Never expose raw child errors or report contents (paths/credentials) here.
+ error("::error::ACKit Action input, report or output processing failed");
+ return cliExit || 1;
+ }
+}
diff --git a/src/api/scan-repository.ts b/src/api/scan-repository.ts
index b912e75e..ebff2573 100644
--- a/src/api/scan-repository.ts
+++ b/src/api/scan-repository.ts
@@ -1,12 +1,14 @@
import type { RepositoryRoot } from "../core/filesystem/root.js";
import { runScan, type ScanPipelineOptions } from "../core/scanner/pipeline.js";
+import { defaultRegistry } from "../core/scanner/registry.js";
import type { ScanResult } from "../core/scanner/types.js";
import { AckitError } from "./errors.js";
/**
* Scans a repository and returns the stable finding set (REQ-API-001).
- * Thin alias over the internal pipeline with an API-friendly name; behavior
- * is identical to `ackit scan` minus CLI concerns.
+ * Uses the same built-in catalog and pipeline as the CLI. Repository config
+ * and policy orchestration belong to the CLI/MCP layer; callers can supply
+ * explicit pipeline options and additional trusted rules here.
* REQ-V020-J-002: typed errors (AckitError) + AbortSignal cancellation.
*/
export async function scanRepository(
@@ -37,7 +39,7 @@ export async function scanRepository(
const scanPromise = runScan(root, {
...(rest as ScanPipelineOptions),
signal,
- rules: [...extraRules],
+ rules: [...defaultRegistry.getAll(), ...extraRules],
});
if (signal === undefined) return await scanPromise;
return await Promise.race([scanPromise, abortedPromise]);
diff --git a/src/cli/commands/optimize.ts b/src/cli/commands/optimize.ts
index 8c4935fd..e2816ddb 100644
--- a/src/cli/commands/optimize.ts
+++ b/src/cli/commands/optimize.ts
@@ -3,9 +3,9 @@ import process from "node:process";
import { loadAckitConfig } from "../../core/config/index.js";
import { analyzeOptimize, applyFixes } from "../../core/context/index.js";
import { resolveRepositoryRoot } from "../../core/filesystem/root.js";
+import { projectOptimizeSuggestions, renderSarif } from "../../core/reporting/sarif.js";
import { emitDiagnostic } from "../../shared/diagnostics.js";
import { EXIT_CODES, type ExitCodeValue } from "../../shared/exit-codes.js";
-import { getPackageIdentity } from "../../shared/version.js";
import type { InstructionsCommandOptions } from "../context.js";
import { reportConfigErrors } from "./config.js";
@@ -142,28 +142,7 @@ export async function runOptimizeCommand(
}
if (fmt === "sarif") {
- // Minimal SARIF 2.1.0 for optimize suggestions as results
- const sarif = {
- $schema: "https://json.schemastore.org/sarif-2.1.0.json",
- version: "2.1.0",
- runs: [
- {
- tool: { driver: { name: "ackit", version: getPackageIdentity().version, rules: [] } },
- results: suggestions.map((s) => ({
- ruleId: s.id,
- level: s.severity === "high" ? "error" : s.severity === "medium" ? "warning" : "note",
- message: { text: s.message },
- locations: (s.evidence ?? []).map((e) => ({
- physicalLocation: {
- artifactLocation: { uri: e.relativePath },
- region: e.line ? { startLine: e.line } : undefined,
- },
- })),
- })),
- },
- ],
- };
- process.stdout.write(`${JSON.stringify(sarif, null, 2)}\n`);
+ process.stdout.write(renderSarif(projectOptimizeSuggestions(suggestions)));
return EXIT_CODES.ok;
}
diff --git a/src/cli/program.ts b/src/cli/program.ts
index eca26412..69849cc5 100644
--- a/src/cli/program.ts
+++ b/src/cli/program.ts
@@ -373,8 +373,9 @@ function buildProgram(invocation: CliInvocation): Command {
.command("serve")
.description("serve the ACKit MCP server over stdio (protocol-pure stdout)")
.action(async () => {
- // Delegate to the dedicated entry so stdout carries only JSON-RPC.
- await import("../mcp/stdio.js");
+ // Bind the advertised startup root without reopening per-tool overrides.
+ const { serveAckitMcp } = await import("../mcp/stdio.js");
+ await serveAckitMcp((program.opts() as Partial).root);
// stdio entry keeps the process alive until the transport closes.
return new Promise((resolve) => {
process.on("exit", () => resolve());
diff --git a/src/core/reporting/sarif.ts b/src/core/reporting/sarif.ts
index a97a8463..2a781801 100644
--- a/src/core/reporting/sarif.ts
+++ b/src/core/reporting/sarif.ts
@@ -1,6 +1,43 @@
import { getPackageIdentity } from "../../shared/version.js";
+import type { OptimizeSuggestion } from "../context/optimize.js";
import type { Finding } from "../scanner/types.js";
+/** Shared SARIF projection; optimizer categories are also valid properties. */
+export type SarifFinding = Omit<
+ Finding,
+ "category" | "remediation" | "documentationKey" | "relativePath" | "line" | "column"
+> & {
+ category: string;
+ relativePath?: string;
+ line?: number;
+ column?: number;
+ remediation?: string;
+ documentationKey?: string;
+};
+
+type OptimizeSarifSource = Pick<
+ OptimizeSuggestion,
+ "id" | "severity" | "message" | "evidence" | "evidencePaths"
+> & { category: string };
+
+export function projectOptimizeSuggestions(
+ suggestions: readonly OptimizeSarifSource[],
+): SarifFinding[] {
+ return suggestions.map((suggestion) => ({
+ ruleId: suggestion.id,
+ category: suggestion.category,
+ severity: suggestion.severity,
+ message: suggestion.message,
+ relativePath: suggestion.evidence?.[0]?.relativePath ?? suggestion.evidencePaths[0],
+ line: suggestion.evidence?.[0]?.line ?? 1,
+ column: 1,
+ evidence: "",
+ fingerprint: suggestion.id,
+ suppressed: false,
+ suppressionReason: null,
+ }));
+}
+
const SEVERITY_LEVEL: Record = {
critical: "error",
high: "error",
@@ -14,7 +51,7 @@ const SEVERITY_LEVEL: Record = {
* secret can appear (REQ-GOV-005).
*/
export function renderSarif(
- findings: readonly Finding[],
+ findings: readonly SarifFinding[],
options: { policyDigest?: string | undefined } = {},
): string {
const identity = getPackageIdentity();
@@ -32,14 +69,25 @@ export function renderSarif(
message: {
text: `${finding.message}${finding.evidence.length > 0 ? ` [evidence: ${finding.evidence}]` : ""}`,
},
- locations: [
- {
- physicalLocation: {
- artifactLocation: { uri: finding.relativePath.split("\\").join("/") },
- region: { startLine: finding.line, startColumn: finding.column },
- },
- },
- ],
+ ...(finding.relativePath
+ ? {
+ locations: [
+ {
+ physicalLocation: {
+ artifactLocation: {
+ uri: finding.relativePath
+ .split("\\")
+ .join("/")
+ .split("/")
+ .map(encodeURIComponent)
+ .join("/"),
+ },
+ region: { startLine: finding.line ?? 1, startColumn: finding.column ?? 1 },
+ },
+ },
+ ],
+ }
+ : {}),
fingerprints: { "ackit/v1": finding.fingerprint },
properties: {
severity: finding.severity,
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index cbb6e1c7..456b3eff 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -75,7 +75,9 @@ export async function createAckitMcpServer(requestedRoot?: string | undefined):
signal: extra.signal,
});
const reportJson = renderScanJson(executed.result);
- return textResult(`${reportJson}\nexit_code_hint=${executed.exceededThreshold ? 1 : 0}`);
+ return textResult(
+ `${reportJson}\nexit_code_hint=${args.ci === true && executed.exceededThreshold ? 1 : 0}`,
+ );
} catch (error) {
if (error instanceof ScanContractError || error instanceof GitUnavailableError) {
return textResult(
diff --git a/src/mcp/stdio.ts b/src/mcp/stdio.ts
index 0f746787..52ef91af 100644
--- a/src/mcp/stdio.ts
+++ b/src/mcp/stdio.ts
@@ -1,11 +1,13 @@
#!/usr/bin/env node
+import { realpathSync } from "node:fs";
// ACKit MCP stdio entry point (official SDK transport only; ADR-0008).
import process from "node:process";
+import { fileURLToPath } from "node:url";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createAckitMcpServer } from "./server.js";
-async function main(): Promise {
- const { server } = await createAckitMcpServer();
+export async function serveAckitMcp(requestedRoot?: string): Promise {
+ const { server } = await createAckitMcpServer(requestedRoot);
const transport = new StdioServerTransport();
await server.connect(transport);
// Clean shutdown when stdio closes (REQ-MCP-004).
@@ -14,8 +16,18 @@ async function main(): Promise {
});
}
-void main().catch((error: unknown) => {
- // stdout must stay protocol-pure; diagnostics go to stderr only.
- process.stderr.write(`ackit mcp: fatal ${(error as Error).message}\n`);
- process.exitCode = 1;
-});
+const invokedDirectly = (() => {
+ try {
+ const entry = process.argv[1];
+ return entry !== undefined && realpathSync(entry) === fileURLToPath(import.meta.url);
+ } catch {
+ return false;
+ }
+})();
+
+if (invokedDirectly)
+ void serveAckitMcp().catch((error: unknown) => {
+ // stdout must stay protocol-pure; diagnostics go to stderr only.
+ process.stderr.write(`ackit mcp: fatal ${(error as Error).message}\n`);
+ process.exitCode = 1;
+ });
diff --git a/tests/contract/action-consumer-diagnostics.test.ts b/tests/contract/action-consumer-diagnostics.test.ts
new file mode 100644
index 00000000..84242107
--- /dev/null
+++ b/tests/contract/action-consumer-diagnostics.test.ts
@@ -0,0 +1,79 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, realpath, rm, symlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { expect, it } from "vitest";
+
+const execute = promisify(execFile);
+it("a failed consumer install exposes stdout/status and remains a hard failure", async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), "ackit-consumer-diagnostic-"));
+ try {
+ const childSource =
+ 'console.log("synthetic-install-cause " + process.cwd()); process.exitCode = 7;';
+ const harness = `
+ import { pathToFileURL } from "node:url";
+ const { runConsumerCommand } = await import(pathToFileURL(process.argv[1]).href);
+ try {
+ runConsumerCommand(process.execPath, ["-e", ${JSON.stringify(childSource)}],
+ { cwd: process.argv[2] }, [[process.argv[2], ""]]);
+ } catch (error) {
+ console.error(error.message);
+ process.exitCode = 1;
+ }
+ `;
+ const result = await execute(
+ process.execPath,
+ ["--input-type=module", "-e", harness, path.resolve("scripts/consumer-command.mjs"), dir],
+ {
+ timeout: 20_000,
+ windowsHide: true,
+ },
+ ).then(
+ () => ({ code: 0, stderr: "" }),
+ (error: { code: number; stderr: string }) => error,
+ );
+ expect(result.code).toBe(1);
+ expect(result.stderr).toContain("consumer command failed (exit 7)");
+ expect(result.stderr).toContain("synthetic-install-cause ");
+ expect(result.stderr).not.toContain(dir);
+ } finally {
+ expect(path.dirname(dir)).toBe(path.resolve(tmpdir()));
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
+it("redacts both declared and canonical directory aliases", async () => {
+ const base = await mkdtemp(path.join(tmpdir(), "ackit-consumer-alias-"));
+ try {
+ const target = path.join(base, "actual");
+ const alias = path.join(base, "alias");
+ await mkdir(target);
+ await symlink(target, alias, process.platform === "win32" ? "junction" : "dir");
+ const childSource =
+ 'console.log("synthetic-install-cause " + require("node:fs").realpathSync(process.cwd())); process.exitCode = 7;';
+ const harness = `
+ import { pathToFileURL } from "node:url";
+ const { runConsumerCommand } = await import(pathToFileURL(process.argv[1]).href);
+ try { runConsumerCommand(process.execPath, ["-e", ${JSON.stringify(childSource)}],
+ { cwd: process.argv[2] }, [[process.argv[2], ""]]); }
+ catch (error) { console.error(error.message); process.exitCode = 1; }
+ `;
+ const result = await execute(
+ process.execPath,
+ ["--input-type=module", "-e", harness, path.resolve("scripts/consumer-command.mjs"), alias],
+ { timeout: 20_000, windowsHide: true },
+ ).then(
+ () => ({ code: 0, stderr: "" }),
+ (error: { code: number; stderr: string }) => error,
+ );
+ expect(result.code).toBe(1);
+ expect(result.stderr).toContain("consumer command failed (exit 7)");
+ expect(result.stderr).toContain("synthetic-install-cause ");
+ expect(result.stderr).not.toContain(alias);
+ expect(result.stderr).not.toContain(await realpath(target));
+ } finally {
+ expect(path.dirname(base)).toBe(path.resolve(tmpdir()));
+ await rm(base, { recursive: true, force: true });
+ }
+});
diff --git a/tests/contract/action-distribution.test.ts b/tests/contract/action-distribution.test.ts
new file mode 100644
index 00000000..07344e47
--- /dev/null
+++ b/tests/contract/action-distribution.test.ts
@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+
+interface ActionStep {
+ id?: string;
+ uses?: string;
+ run?: string;
+ env?: Record;
+ with?: Record;
+}
+const raw = readFileSync("action.yml", "utf8");
+const expression = (value: string): string => `$${"{"}{ ${value} }}`;
+const action = parse(raw) as {
+ runs: { using: string; steps: ActionStep[] };
+ outputs: Record;
+};
+
+describe("clean-tag Action distribution", () => {
+ it("bootstraps exact source with pinned setup actions and a frozen install", () => {
+ expect(action.runs.using).toBe("composite");
+ for (const step of action.runs.steps.filter((step) => step.uses)) {
+ expect(step.uses).toMatch(/@[0-9a-f]{40}$/);
+ }
+ const setup = action.runs.steps.find((step) => step.uses?.startsWith("pnpm/action-setup@"));
+ expect(setup?.with?.["package_json_file"]).toBe(
+ expression("steps.action-package.outputs.path"),
+ );
+ expect(
+ action.runs.steps.find((step) => step.id === "action-package")?.env?.["ACKIT_ACTION_PATH"],
+ ).toBe(expression("github.action_path"));
+ expect(raw).toContain("pnpm install --frozen-lockfile --ignore-scripts");
+ expect(raw).toContain("pnpm build");
+ expect(raw.indexOf("pnpm build")).toBeLessThan(raw.indexOf("/dist/action/index.js"));
+ });
+ it("passes every untrusted input through env and maps real step outputs", () => {
+ for (const step of action.runs.steps) expect(step.run ?? "").not.toContain("${{ inputs.");
+ expect(action.runs.steps.at(-1)?.env?.["INPUT_ARGS"]).toBe(expression("inputs.args"));
+ expect(action.outputs["findings-json"]?.value).toBe(
+ expression("steps.ackit.outputs.findings-json"),
+ );
+ expect(action.outputs["sarif-path"]?.value).toBe(expression("steps.ackit.outputs.sarif-path"));
+ });
+ it("dogfood has no preparatory install/build that could hide missing runtime", () => {
+ const workflow = parse(readFileSync(".github/workflows/ackit-action-dogfood.yml", "utf8")) as {
+ jobs: { "action-smoke": { steps: ActionStep[] } };
+ };
+ const steps = workflow.jobs["action-smoke"].steps;
+ const index = steps.findIndex((step) => step.uses === "./");
+ expect(index).toBeGreaterThan(0);
+ for (const step of steps.slice(0, index)) {
+ expect(step.run ?? "").not.toMatch(/pnpm (?:install|build)/);
+ }
+ });
+});
diff --git a/tests/contract/action-package-path.test.ts b/tests/contract/action-package-path.test.ts
new file mode 100644
index 00000000..e2412957
--- /dev/null
+++ b/tests/contract/action-package-path.test.ts
@@ -0,0 +1,46 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { expect, it } from "vitest";
+
+const execute = promisify(execFile);
+it("pnpm setup resolves the Action's pinned manifest from an unrelated consumer", async () => {
+ const base = await mkdtemp(path.join(tmpdir(), "ackit-action-manifest-"));
+ try {
+ const actionRoot = path.join(base, "action checkout");
+ const workspace = path.join(base, "consumer workspace");
+ await mkdir(actionRoot);
+ await mkdir(workspace);
+ const pinned = JSON.parse(await readFile("package.json", "utf8")).packageManager as string;
+ await writeFile(
+ path.join(actionRoot, "package.json"),
+ JSON.stringify({ packageManager: pinned }),
+ );
+ await writeFile(
+ path.join(workspace, "package.json"),
+ JSON.stringify({ packageManager: "pnpm@1.0.0" }),
+ );
+ for (const consumer of [workspace, actionRoot]) {
+ const result = await execute(
+ process.execPath,
+ [path.resolve("scripts/action-package-path.mjs")],
+ {
+ cwd: consumer,
+ env: { ...process.env, ACKIT_ACTION_PATH: actionRoot, GITHUB_WORKSPACE: consumer },
+ timeout: 20_000,
+ windowsHide: true,
+ },
+ );
+ const relative = result.stdout.trim().slice("path=".length);
+ expect(path.isAbsolute(relative)).toBe(false);
+ const target = path.join(consumer, relative); // exact pinned setup resolution contract
+ expect(await realpath(target)).toBe(await realpath(path.join(actionRoot, "package.json")));
+ expect(JSON.parse(await readFile(target, "utf8")).packageManager).toBe(pinned);
+ }
+ } finally {
+ expect(path.dirname(base)).toBe(path.resolve(tmpdir()));
+ await rm(base, { recursive: true, force: true });
+ }
+});
diff --git a/tests/contract/ci-pinning.test.ts b/tests/contract/ci-pinning.test.ts
index 5cd04ae2..ba58b08d 100644
--- a/tests/contract/ci-pinning.test.ts
+++ b/tests/contract/ci-pinning.test.ts
@@ -62,6 +62,36 @@ describe("CI workflow hardening", () => {
expect(raw).toContain("scan --ci");
expect(raw).toContain("smoke:package");
});
+
+ it("enforces schema/CLI/version gates and real extension failures", () => {
+ const doc = parse(raw) as {
+ jobs: Record;
+ };
+ const runs = doc.jobs["verify"]?.steps.map((step) => step.run ?? "").join("\n") ?? "";
+ for (const marker of [
+ "pnpm gen:schemas",
+ "git diff --exit-code -- schemas",
+ "pnpm smoke:cli",
+ "node scripts/check-version-parity.mjs",
+ ])
+ expect(runs).toContain(marker);
+ const extension = doc.jobs["extension"]?.steps ?? [];
+ for (const step of extension) {
+ expect(step["continue-on-error"]).not.toBe(true);
+ expect(step.run ?? "").not.toMatch(/\|\|\s*(?:true|echo)|--diagnostic-level=warn/);
+ }
+ const commands = extension.map((step) => step.run ?? "").join("\n");
+ for (const marker of [
+ "run lint",
+ "run typecheck",
+ "run test:unit",
+ "xvfb-run -a pnpm --filter ackit-vscode test",
+ "node scripts/check-vsix.mjs",
+ "pkg.version!==root.version",
+ ])
+ expect(commands).toContain(marker);
+ expect(commands).not.toMatch(/ackit-vscode-\d+\.\d+\.\d+\.vsix/);
+ });
});
/** Controlled-release gate: release.yml must stay a tags-only, npm-OIDC +
@@ -317,4 +347,16 @@ describe("release workflow hardening", () => {
expect(raw).toContain("v" + "$" + "{RELEASE_VERSION}");
expect(raw).toContain("AgentContextKit v" + "$" + "{RELEASE_VERSION}" + " release");
});
+
+ it("bounds final Marketplace stale-read retries and still fails closed", () => {
+ const doc = parse(raw) as { jobs: { release: { steps: { name?: string; run?: string }[] } } };
+ const final = doc.jobs.release.steps.at(-1);
+ expect(final?.name).toContain("Final public-surface verification");
+ const run = final?.run ?? "";
+ expect(run).toMatch(/for attempt in \$\(seq 1 6\); do/);
+ expect(run).toContain('if [ "' + "$" + '{attempt}" -lt 6 ]; then sleep 10; fi');
+ expect(run).toContain('"' + "$" + '{MKT_FINAL}" = "' + "$" + '{RELEASE_VERSION}"');
+ expect(run).toContain("exit 91");
+ expect(run).not.toMatch(/\|\|\s*true|vsce.*publish/);
+ });
});
diff --git a/tests/contract/documentation-distribution.test.ts b/tests/contract/documentation-distribution.test.ts
new file mode 100644
index 00000000..8042296c
--- /dev/null
+++ b/tests/contract/documentation-distribution.test.ts
@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+describe("maintained documentation distribution", () => {
+ it("README local Markdown links resolve to maintained files or directories", () => {
+ const markdown = readFileSync("README.md", "utf8");
+ for (const match of markdown.matchAll(/\[[^\]]*\]\(([^\s)>]+)>?\)/g)) {
+ const target = (match[1] ?? "").split("#")[0] ?? "";
+ if (!target || /^[a-z]+:/i.test(target)) continue;
+ expect(existsSync(path.resolve(decodeURIComponent(target))), target).toBe(true);
+ }
+ });
+ it("every Docs7 navigation route has an actual page inside docs", () => {
+ const config = JSON.parse(readFileSync("docs/docs.json", "utf8")) as {
+ navigation: { groups: { pages: string[] }[] };
+ };
+ const root = path.resolve("docs");
+ const routes = config.navigation.groups.flatMap((group) => group.pages);
+ expect(routes.length).toBeGreaterThan(0);
+ expect(new Set(routes).size).toBe(routes.length);
+ for (const route of routes) {
+ const absolute = path.resolve(root, route);
+ expect(absolute.startsWith(`${root}${path.sep}`), route).toBe(true);
+ expect(
+ [".md", ".mdx"].some((suffix) => existsSync(absolute + suffix)),
+ route,
+ ).toBe(true);
+ }
+ });
+ it("Context7 indexing points to existing current documentation", () => {
+ const config = JSON.parse(readFileSync("context7.json", "utf8")) as {
+ projectTitle: string;
+ description: string;
+ folders: string[];
+ rules: string[];
+ excludeFolders: string[];
+ };
+ expect(config.projectTitle.length).toBeLessThanOrEqual(100);
+ expect(config.description.length).toBeLessThanOrEqual(500);
+ for (const rule of config.rules) expect(rule.length).toBeLessThanOrEqual(255);
+ for (const folder of config.folders) expect(existsSync(folder), folder).toBe(true);
+ expect(config.excludeFolders).toContain("docs/tasks");
+ expect(config.excludeFolders).toContain("docs/rebuild");
+ });
+});
diff --git a/tests/contract/mcp/tool-inputs.test.ts b/tests/contract/mcp/tool-inputs.test.ts
new file mode 100644
index 00000000..d96e088a
--- /dev/null
+++ b/tests/contract/mcp/tool-inputs.test.ts
@@ -0,0 +1,109 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { describe, expect, it } from "vitest";
+import { createAckitMcpServer } from "../../../src/mcp/server.js";
+
+async function session(options: { finding?: boolean; suppress?: boolean } = {}) {
+ const root = await mkdtemp(path.join(tmpdir(), "ackit-mcp-inputs-"));
+ await writeFile(path.join(root, "AGENTS.md"), "# Instructions\nReview repository checks.\n");
+ await writeFile(path.join(root, "README.md"), "# Fixture\n");
+ await writeFile(
+ path.join(root, "ackit.yml"),
+ "schemaVersion: 1\npolicy:\n extends: [ackit-policy.yml]\n",
+ );
+ await writeFile(
+ path.join(root, "ackit-policy.yml"),
+ "schemaVersion: 1\nthresholds:\n severity: low\n" +
+ (options.suppress
+ ? [
+ "suppressions:",
+ " - ruleId: ACKIT020",
+ " pathGlobs: [inside.txt]",
+ " reason: intentional fixture marker",
+ ' expiresAt: "2099-12-31"',
+ "",
+ ].join("\n")
+ : ""),
+ );
+ if (options.finding) await writeFile(path.join(root, "inside.txt"), "TODO: fixture\n");
+ const { server } = await createAckitMcpServer(root);
+ const client = new Client({ name: "input-contract", version: "0.0.1" });
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ return {
+ client,
+ close: async () => {
+ await client.close();
+ expect(path.dirname(root)).toBe(path.resolve(tmpdir()));
+ await rm(root, { recursive: true, force: true });
+ },
+ };
+}
+
+describe("MCP documented inputs and severity hints", () => {
+ it("the reference table matches all live tool schema properties", async () => {
+ const current = await session();
+ try {
+ const reference = await readFile("docs/reference/mcp.md", "utf8");
+ const rows = [...reference.matchAll(/^\| (ackit_[a-z_]+) \| ([^|]*) \|/gm)];
+ const documented = new Map(
+ rows.map((row) => [
+ row[1],
+ (row[2] ?? "").trim() === "โ"
+ ? []
+ : (row[2] ?? "")
+ .split(",")
+ .map((arg) => arg.trim().replace(/\?$/, ""))
+ .sort(),
+ ]),
+ );
+ const { tools } = await current.client.listTools();
+ expect([...documented.keys()].sort()).toEqual(tools.map((tool) => tool.name).sort());
+ for (const tool of tools) {
+ const properties = Object.keys(tool.inputSchema.properties ?? {}).sort();
+ expect(properties, tool.name).toEqual(documented.get(tool.name));
+ expect(properties).not.toContain("root");
+ expect(properties).not.toContain("includeGlobs");
+ }
+ } finally {
+ await current.close();
+ }
+ });
+ it.each([
+ { ci: undefined, finding: true, suppress: false, hint: 0 },
+ { ci: false, finding: true, suppress: false, hint: 0 },
+ { ci: true, finding: true, suppress: false, hint: 1 },
+ { ci: true, finding: false, suppress: false, hint: 0 },
+ { ci: true, finding: true, suppress: true, hint: 0 },
+ ])(
+ "ci=$ci finding=$finding suppress=$suppress hints $hint",
+ async ({ ci, finding, suppress, hint }) => {
+ const current = await session({ finding, suppress });
+ try {
+ const result = await current.client.callTool({
+ name: "ackit_scan",
+ arguments: ci === undefined ? {} : { ci },
+ });
+ expect(result.isError ?? false).toBe(false);
+ const text = (result.content as { type: string; text: string }[])
+ .map((item) => item.text)
+ .join("");
+ const [report, exitHint] = text.split("\nexit_code_hint=");
+ expect(exitHint).toBe(String(hint));
+ const findings = (
+ JSON.parse(report ?? "null") as { findings: { ruleId: string; suppressed: boolean }[] }
+ ).findings;
+ expect(findings.some((item) => item.ruleId === "ACKIT020")).toBe(finding);
+ if (suppress)
+ expect(findings.find((item) => item.ruleId === "ACKIT020")?.suppressed).toBe(true);
+ expect((await current.client.listTools()).tools.length).toBe(16);
+ } finally {
+ await current.close();
+ }
+ },
+ );
+});
diff --git a/tests/contract/version-parity.test.ts b/tests/contract/version-parity.test.ts
index 8f2f8d44..1b5c8300 100644
--- a/tests/contract/version-parity.test.ts
+++ b/tests/contract/version-parity.test.ts
@@ -216,7 +216,7 @@ describe("version-parity guard probes (TASK-0078 A-E)", () => {
const source = readSourceVersion();
const stable = readPublishedStable();
const extensionManifest = JSON.stringify({ version: source });
- const ci = `contract '${source}' and ackit-vscode-${source}.vsix`;
+ const ci = readTree()[".github/workflows/ci.yml"] ?? "";
const files: Record = {};
for (const file of CURRENT_FILES) {
if (MUST_SHOW_STABLE.includes(file)) {
@@ -295,6 +295,18 @@ describe("version-parity guard probes (TASK-0078 A-E)", () => {
`expected a CHANGELOG parity failure, got: ${failures.join("; ")}`,
).toBe(true);
});
+
+ it("rejects removed dynamic CI parity and literal VSIX filenames", () => {
+ const files = readTree();
+ files[".github/workflows/ci.yml"] = "legacy literal version check and ackit-vscode-0.5.4.vsix";
+ const { failures } = checkParity({ files });
+ expect(
+ failures.some((failure) => failure.includes("dynamic extension/root version parity")),
+ ).toBe(true);
+ expect(failures.some((failure) => failure.includes("derive from the extension manifest"))).toBe(
+ true,
+ );
+ });
});
describe("marketplace content parity helpers (TASK-0090)", () => {
diff --git a/tests/contract/vsix-integrity.test.ts b/tests/contract/vsix-integrity.test.ts
new file mode 100644
index 00000000..14544de0
--- /dev/null
+++ b/tests/contract/vsix-integrity.test.ts
@@ -0,0 +1,134 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const root = process.cwd();
+const source = JSON.parse(readFileSync("package.json", "utf8")) as {
+ name: string;
+ version: string;
+};
+const extension = readFileSync("extensions/vscode/package.json");
+const table = Array.from({ length: 256 }, (_, index) => {
+ let value = index;
+ for (let bit = 0; bit < 8; bit++) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+ return value >>> 0;
+});
+function crc32(bytes: Buffer): number {
+ let crc = 0xffffffff;
+ for (const byte of bytes) crc = (table[(crc ^ byte) & 255] ?? 0) ^ (crc >>> 8);
+ return (crc ^ 0xffffffff) >>> 0;
+}
+// A tiny stored-entry ZIP fixture writer, independent of the inspected reader.
+function archive(entries: Record): Buffer {
+ const payloads: Buffer[] = [];
+ const directory: Buffer[] = [];
+ let offset = 0;
+ for (const [name, value] of Object.entries(entries)) {
+ const filename = Buffer.from(name);
+ const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
+ const local = Buffer.alloc(30);
+ local.writeUInt32LE(0x04034b50, 0);
+ local.writeUInt16LE(20, 4);
+ local.writeUInt32LE(crc32(bytes), 14);
+ local.writeUInt32LE(bytes.length, 18);
+ local.writeUInt32LE(bytes.length, 22);
+ local.writeUInt16LE(filename.length, 26);
+ const central = Buffer.alloc(46);
+ central.writeUInt32LE(0x02014b50, 0);
+ central.writeUInt16LE(20, 4);
+ central.writeUInt16LE(20, 6);
+ central.writeUInt32LE(crc32(bytes), 16);
+ central.writeUInt32LE(bytes.length, 20);
+ central.writeUInt32LE(bytes.length, 24);
+ central.writeUInt16LE(filename.length, 28);
+ central.writeUInt32LE(offset, 42);
+ payloads.push(local, filename, bytes);
+ directory.push(central, filename);
+ offset += local.length + filename.length + bytes.length;
+ }
+ const end = Buffer.alloc(22);
+ end.writeUInt32LE(0x06054b50, 0);
+ end.writeUInt16LE(directory.length / 2, 8);
+ end.writeUInt16LE(directory.length / 2, 10);
+ end.writeUInt32LE(Buffer.concat(directory).length, 12);
+ end.writeUInt32LE(offset, 16);
+ return Buffer.concat([...payloads, ...directory, end]);
+}
+function fixture(): Record {
+ const entries: Record = {
+ "extension/package.json": extension,
+ "extension/dist/package.json": JSON.stringify({ name: source.name, version: source.version }),
+ "extension/dist/extension.js": "// bundled fixture\n",
+ "extension.vsixmanifest": ``,
+ "extension/readme.md": readFileSync("extensions/vscode/README.md"),
+ "extension/changelog.md": readFileSync("extensions/vscode/CHANGELOG.md"),
+ "extension/images/icon.png": readFileSync("extensions/vscode/images/icon.png"),
+ "extension/dist/templates/roles/verifier.yaml": readFileSync("templates/roles/verifier.yaml"),
+ };
+ for (const name of ["codex", "claude", "copilot", "gemini", "generic"]) {
+ entries[`extension/dist/templates/profiles/${name}.yml`] = readFileSync(
+ `templates/profiles/${name}.yml`,
+ );
+ }
+ return entries;
+}
+async function check(bytes: Buffer): Promise<{ code: number | null; output: string }> {
+ const dir = await mkdtemp(path.join(tmpdir(), "ackit-vsix-contract-"));
+ try {
+ const file = path.join(dir, "fixture.vsix");
+ await writeFile(file, bytes);
+ const result = spawnSync(process.execPath, ["scripts/check-vsix.mjs", file], {
+ cwd: root,
+ encoding: "utf8",
+ timeout: 10_000,
+ windowsHide: true,
+ });
+ return { code: result.status, output: result.stdout + result.stderr };
+ } finally {
+ expect(path.dirname(dir)).toBe(path.resolve(tmpdir()));
+ await rm(dir, { recursive: true, force: true });
+ }
+}
+
+describe("packaged VSIX fail-closed integrity gate", () => {
+ it("accepts version-coupled content and detector text without key material", async () => {
+ const entries = fixture();
+ entries["extension/dist/extension.js"] = `/${["-----BEGIN", "PRIVATE KEY-----"].join(" ")}/g;`;
+ expect((await check(archive(entries))).code).toBe(0);
+ });
+ it("rejects version drift and missing bundled resources", async () => {
+ const drift = fixture();
+ drift["extension/dist/package.json"] = JSON.stringify({ ...source, version: "0.0.0" });
+ expect((await check(archive(drift))).output).toContain("version mismatch");
+ const missing = fixture();
+ delete missing["extension/dist/templates/profiles/codex.yml"];
+ expect((await check(archive(missing))).output).toContain("profiles/codex.yml");
+ });
+ it.each([
+ "extension/node_modules/a.js",
+ "extension/dist/extension.js.map",
+ "extension/src/a.ts",
+ "../outside.txt",
+ ])("rejects unexpected path %s", async (file) => {
+ expect((await check(archive({ ...fixture(), [file]: "unexpected" }))).code).not.toBe(0);
+ });
+ it("rejects actual credential-shaped material and corrupted payloads", async () => {
+ const entries = fixture();
+ entries["extension/dist/extension.js"] = [
+ ["-----BEGIN", "PRIVATE KEY-----"].join(" "),
+ "A".repeat(64),
+ ["-----END", "PRIVATE KEY-----"].join(" "),
+ ].join("\n");
+ expect((await check(archive(entries))).output).toContain("Credential pattern");
+ entries["extension/dist/extension.js"] = ["gh", "p_"].join("") + "a".repeat(36);
+ expect((await check(archive(entries))).output).toContain("Credential pattern");
+ const corrupt = archive(fixture());
+ const index = corrupt.indexOf(extension);
+ expect(index).toBeGreaterThan(0);
+ corrupt[index] = (corrupt[index] ?? 0) ^ 1;
+ expect((await check(corrupt)).output).toContain("CRC/size mismatch");
+ });
+});
diff --git a/tests/integration/context/pack.test.ts b/tests/integration/context/pack.test.ts
index 5ca17d09..603ce5d2 100644
--- a/tests/integration/context/pack.test.ts
+++ b/tests/integration/context/pack.test.ts
@@ -7,7 +7,7 @@ import { buildContextPack, RANKING_WEIGHTS } from "../../../src/core/context/pac
let repo: { rootPath: string; cleanup(): Promise };
const SECRET_VALUE = "AKIAIOSFODNN7EXAMPLE";
-const WIN_ABS = "C:\\Users\\gizem\\AppData\\Local\\Temp\\cache";
+const WIN_ABS = "C:\\Users\\fixture-user\\AppData\\Local\\Temp\\cache";
beforeAll(async () => {
const rootPath = await mkdtemp(path.join(tmpdir(), "ackit-pack-"));
@@ -54,7 +54,7 @@ describe("context pack engine (REQ-CTX-001..004)", () => {
it("scrubs machine-local absolute paths out of emitted content (Windows-style)", async () => {
const result = await pack();
- expect(result.markdown).not.toContain("C:\\Users\\gizem");
+ expect(result.markdown).not.toContain("C:\\Users\\fixture-user");
expect(result.markdown).toContain("");
const scrubbedEntry = result.manifest.find((item) => item.relativePath === "notes.md");
expect(scrubbedEntry?.action).toBe("scrubbed");
diff --git a/tests/integration/mcp/startup-root.test.ts b/tests/integration/mcp/startup-root.test.ts
new file mode 100644
index 00000000..7fb80c4b
--- /dev/null
+++ b/tests/integration/mcp/startup-root.test.ts
@@ -0,0 +1,59 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { describe, expect, it } from "vitest";
+
+const cli = path.join(process.cwd(), "dist/cli/index.js");
+
+describe("CLI MCP startup root precedence", () => {
+ it.each(["flag", "environment", "cwd"])(
+ "uses the %s root without a per-call override",
+ async (mode) => {
+ const fixture = await mkdtemp(path.join(tmpdir(), "ackit-mcp-startup-"));
+ const selected = path.join(fixture, "selected repository");
+ const working = path.join(fixture, "working repository");
+ await mkdir(selected);
+ await mkdir(working);
+ for (const [root, name] of [
+ [selected, "selected.txt"],
+ [working, "working.txt"],
+ ] as const) {
+ await writeFile(path.join(root, "AGENTS.md"), "# Instructions\nReview checks.\n");
+ await writeFile(path.join(root, name), "TODO: fixture\n");
+ }
+ const env = Object.fromEntries(
+ ["PATH", "SystemRoot", "WINDIR", "TEMP", "TMP"].flatMap((key) => {
+ const value = process.env[key];
+ return value === undefined ? [] : [[key, value]];
+ }),
+ );
+ if (mode !== "cwd") env["ACKIT_ROOT"] = mode === "flag" ? working : selected;
+ const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [cli, ...(mode === "flag" ? ["--root", selected] : []), "mcp", "serve"],
+ cwd: working,
+ env,
+ stderr: "pipe",
+ });
+ const client = new Client({ name: "startup-root-test", version: "0.0.1" });
+ try {
+ await client.connect(transport);
+ const result = await client.callTool({ name: "ackit_scan", arguments: {} });
+ expect(result.isError ?? false).toBe(false);
+ const text = (result.content as { text: string }[]).map((item) => item.text).join("");
+ const report = JSON.parse(text.split("\nexit_code_hint=")[0] ?? "null") as {
+ findings: { relativePath: string }[];
+ };
+ const paths = report.findings.map((finding) => finding.relativePath);
+ expect(paths).toContain(mode === "cwd" ? "working.txt" : "selected.txt");
+ expect(paths).not.toContain(mode === "cwd" ? "selected.txt" : "working.txt");
+ } finally {
+ await client.close();
+ expect(path.dirname(fixture)).toBe(path.resolve(tmpdir()));
+ await rm(fixture, { recursive: true, force: true });
+ }
+ },
+ );
+});
diff --git a/tests/integration/sdk-example.test.ts b/tests/integration/sdk-example.test.ts
new file mode 100644
index 00000000..af4c3097
--- /dev/null
+++ b/tests/integration/sdk-example.test.ts
@@ -0,0 +1,24 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { expect, it } from "vitest";
+
+const execute = promisify(execFile);
+it("the documented SDK consumer runs against an unrelated repository fixture", async () => {
+ const root = await mkdtemp(path.join(tmpdir(), "ackit-sdk-example-"));
+ try {
+ await writeFile(path.join(root, "sample.txt"), "TODO: fixture\n");
+ const result = await execute(process.execPath, [path.resolve("examples/sdk-consumer.mjs")], {
+ cwd: root,
+ timeout: 20_000,
+ windowsHide: true,
+ });
+ expect(result.stdout).toContain("sdk-consumer: findings=1 filesScanned=1");
+ expect(result.stderr).toBe("");
+ } finally {
+ expect(path.dirname(root)).toBe(path.resolve(tmpdir()));
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/tests/integration/sdk-scan.test.ts b/tests/integration/sdk-scan.test.ts
new file mode 100644
index 00000000..8f273a08
--- /dev/null
+++ b/tests/integration/sdk-scan.test.ts
@@ -0,0 +1,44 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { ScanRule } from "../../src/core/scanner/types.js";
+import { scanRepository } from "../../src/index.js";
+
+describe("SDK scan built-in catalog contract", () => {
+ it("runs built-in rules by default and appends extra rules", async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), "ackit-sdk-catalog-"));
+ try {
+ await writeFile(path.join(dir, "sample.txt"), "TODO: review custom-marker\n");
+ const baseline = await scanRepository({ canonicalPath: dir });
+ expect(baseline.findings.some((finding) => finding.ruleId === "ACKIT020")).toBe(true);
+ const custom: ScanRule = {
+ id: "CUSTOM001",
+ severity: "low",
+ category: "hygiene",
+ documentationKey: "rules/CUSTOM001",
+ remediation: "Review custom marker",
+ appliesTo: (file) => file === "sample.txt",
+ evaluate: () => [
+ {
+ ruleId: "CUSTOM001",
+ severity: "low",
+ category: "hygiene",
+ message: "Custom rule ran",
+ offset: 0,
+ rawEvidence: "custom-marker",
+ remediation: "Review custom marker",
+ documentationKey: "rules/CUSTOM001",
+ },
+ ],
+ };
+ const extended = await scanRepository({ canonicalPath: dir }, { extraRules: [custom] });
+ expect(extended.findings.filter((finding) => finding.ruleId !== "CUSTOM001")).toEqual(
+ baseline.findings,
+ );
+ expect(extended.findings.some((finding) => finding.ruleId === "CUSTOM001")).toBe(true);
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/tests/security/secrets/secrets.test.ts b/tests/security/secrets/secrets.test.ts
index 9ef24eb2..c4470d9f 100644
--- a/tests/security/secrets/secrets.test.ts
+++ b/tests/security/secrets/secrets.test.ts
@@ -45,7 +45,7 @@ beforeAll(async () => {
// Absolute path leakage.
await writeFile(
path.join(r, "notes.md"),
- "Build cache lives at C:\\Users\\gizem\\AppData\\Local\\Temp\\build\n",
+ "Build cache lives at C:\\Users\\fixture-user\\AppData\\Local\\Temp\\build\n",
"utf8",
);
// Unpinned workflow action.
diff --git a/tests/unit/action/runtime.test.ts b/tests/unit/action/runtime.test.ts
new file mode 100644
index 00000000..1c452c3d
--- /dev/null
+++ b/tests/unit/action/runtime.test.ts
@@ -0,0 +1,255 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { runAction, splitActionArgs } from "../../../src/action/runtime.js";
+import type { Finding } from "../../../src/core/scanner/types.js";
+import { getPackageIdentity } from "../../../src/shared/version.js";
+
+const dirs: string[] = [];
+afterEach(async () => {
+ for (const dir of dirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+function finding(overrides: Partial = {}): Finding {
+ return {
+ ruleId: "ACKIT020",
+ severity: "low",
+ category: "hygiene",
+ message: "Review marker",
+ relativePath: "sample.txt",
+ line: 2,
+ column: 1,
+ fingerprint: "fixture",
+ evidence: "",
+ remediation: "Review",
+ documentationKey: "rules/ACKIT020",
+ suppressed: false,
+ suppressionReason: null,
+ ...overrides,
+ };
+}
+
+async function execute(
+ findings: Finding[],
+ options: {
+ status?: number | null;
+ threshold?: string;
+ error?: Error;
+ signal?: NodeJS.Signals;
+ stdout?: string;
+ sarif?: string;
+ args?: string;
+ command?: string;
+ } = {},
+) {
+ const dir = await mkdtemp(path.join(tmpdir(), "ackit-action-test-"));
+ dirs.push(dir);
+ const messages: string[] = [];
+ let argv: string[] = [];
+ const code = runAction({
+ env: {
+ RUNNER_TEMP: dir,
+ GITHUB_OUTPUT: path.join(dir, "outputs"),
+ GITHUB_STEP_SUMMARY: path.join(dir, "summary"),
+ INPUT_FAIL_THRESHOLD: options.threshold ?? "high",
+ INPUT_UPLOAD_SARIF: options.sarif ?? "true",
+ INPUT_ARGS: options.args ?? "",
+ INPUT_COMMAND: options.command ?? "scan",
+ },
+ invoke: (args) => {
+ argv = args;
+ return {
+ status: options.status === undefined ? 0 : options.status,
+ stdout: options.stdout ?? JSON.stringify({ findings }),
+ error: options.error,
+ signal: options.signal,
+ };
+ },
+ log: (message) => messages.push(message),
+ error: (message) => messages.push(message),
+ });
+ return { dir, code, messages, argv };
+}
+
+describe("Action threshold and process contract", () => {
+ it("applies thresholds to optimize suggestions and preserves their report", async () => {
+ const report = {
+ schemaVersion: "ackit.optimize.v0",
+ suggestions: [
+ {
+ id: "OPT-DUPLICATE",
+ category: "redundant-content",
+ severity: "high",
+ message: "Duplicate instructions",
+ evidencePaths: ["AGENTS.md"],
+ evidence: [{ relativePath: "AGENTS.md", line: 3 }],
+ remediation: "Deduplicate",
+ fixable: false,
+ },
+ ],
+ };
+ const result = await execute([], { command: "optimize", stdout: JSON.stringify(report) });
+ expect(result.code).toBe(1);
+ expect(
+ JSON.parse(await readFile(path.join(result.dir, "ackit-findings.json"), "utf8")),
+ ).toEqual(report);
+ const sarif = JSON.parse(await readFile(path.join(result.dir, "ackit.sarif"), "utf8"));
+ expect(sarif.runs[0].results[0].ruleId).toBe("OPT-DUPLICATE");
+ expect(sarif.runs[0].results[0].properties.category).toBe("redundant-content");
+ expect(sarif.runs[0].results[0].locations[0].physicalLocation).toEqual({
+ artifactLocation: { uri: "AGENTS.md" },
+ region: { startLine: 3, startColumn: 1 },
+ });
+ });
+ it("fails at the threshold even when the CLI returns zero", async () => {
+ expect((await execute([finding({ severity: "high" })])).code).toBe(1);
+ });
+ it.each([
+ { severity: "low", status: 0, expected: 0 },
+ { severity: "high", status: 0, expected: 1 },
+ { severity: "high", status: 4, expected: 4 },
+ ])(
+ "optimize severity=$severity CLI=$status exits $expected",
+ async ({ severity, status, expected }) => {
+ const report = {
+ suggestions: [
+ {
+ id: "OPT",
+ category: "missing-task-docs",
+ severity,
+ message: "Missing tasks",
+ evidencePaths: ["docs/tasks"],
+ },
+ ],
+ };
+ expect(
+ (await execute([], { command: "optimize", status, stdout: JSON.stringify(report) })).code,
+ ).toBe(expected);
+ },
+ );
+ it("encodes SARIF path segments without changing the original JSON path", async () => {
+ const relativePath = "docs/a #rรฉsumรฉ?.md";
+ const { dir } = await execute([finding({ relativePath })]);
+ const sarif = JSON.parse(await readFile(path.join(dir, "ackit.sarif"), "utf8"));
+ expect(sarif.runs[0].results[0].locations[0].physicalLocation.artifactLocation.uri).toBe(
+ "docs/a%20%23r%C3%A9sum%C3%A9%3F.md",
+ );
+ const report = JSON.parse(await readFile(path.join(dir, "ackit-findings.json"), "utf8"));
+ expect(report.findings[0].relativePath).toBe(relativePath);
+ });
+ it.each([
+ { severity: "warning", threshold: "high", status: 0, expected: 0 },
+ { severity: "blocking", threshold: "high", status: 0, expected: 1 },
+ { severity: "blocking", threshold: "critical", status: 1, expected: 1 },
+ ])(
+ "preserves drift $severity report and CLI=$status",
+ async ({ severity, threshold, status, expected }) => {
+ const report = {
+ schemaVersion: "ackit.drift-report.v1",
+ findings: [
+ {
+ code: "DRIFT-SCOPE",
+ severity,
+ taskId: "TASK-0001",
+ detail: "Fixture drift",
+ },
+ ],
+ };
+ const result = await execute([], {
+ command: "drift",
+ threshold,
+ status,
+ stdout: JSON.stringify(report),
+ });
+ expect(result.code).toBe(expected);
+ expect(
+ JSON.parse(await readFile(path.join(result.dir, "ackit-findings.json"), "utf8")),
+ ).toEqual(report);
+ const sarif = JSON.parse(await readFile(path.join(result.dir, "ackit.sarif"), "utf8"));
+ expect(sarif.runs[0].results[0].ruleId).toBe("DRIFT-SCOPE");
+ expect(sarif.runs[0].results[0].message.text).toContain("Fixture drift");
+ expect(sarif.runs[0].results[0]).not.toHaveProperty("locations");
+ },
+ );
+ it("passes below threshold and when no findings exist", async () => {
+ expect((await execute([finding()])).code).toBe(0);
+ expect((await execute([])).code).toBe(0);
+ });
+ it("honors policy suppression without hiding the report", async () => {
+ const result = await execute([finding({ severity: "critical", suppressed: true })]);
+ expect(result.code).toBe(0);
+ expect(result.messages).toEqual([]);
+ expect(
+ JSON.parse(await readFile(path.join(result.dir, "ackit-findings.json"), "utf8")).findings[0]
+ .suppressed,
+ ).toBe(true);
+ });
+ it.each([1, 2, 3, 4, 5])("preserves CLI code %i even with a parsed report", async (status) => {
+ expect((await execute([finding({ severity: "critical" })], { status })).code).toBe(status);
+ });
+ it("fails closed on launch error, timeout, signal, empty or malformed JSON", async () => {
+ for (const options of [
+ { status: null, error: new Error("synthetic timeout") },
+ { status: null, signal: "SIGTERM" as const },
+ { stdout: "" },
+ { stdout: "malformed" },
+ { stdout: "[]" },
+ ])
+ expect((await execute([], options)).code).not.toBe(0);
+ });
+ it("preserves drift check-active's successful empty legacy no-op", async () => {
+ const result = await execute([], { command: "drift", args: "check-active --ci", stdout: "" });
+ expect(result.code).toBe(0);
+ expect(result.messages).toEqual([]);
+ await expect(readFile(path.join(result.dir, "outputs"))).rejects.toMatchObject({
+ code: "ENOENT",
+ });
+ });
+ it.each(["scan", "optimize", "drift"])(
+ "fails closed if %s JSON omits its finding array",
+ async (command) => {
+ expect((await execute([], { command, stdout: "{}" })).code).not.toBe(0);
+ },
+ );
+ it("rejects invalid threshold, boolean and quoting before invoking CLI", async () => {
+ for (const options of [{ threshold: "hgh" }, { sarif: "yes" }, { args: '"unclosed' }]) {
+ const result = await execute([], options);
+ expect(result.code).not.toBe(0);
+ expect(result.argv).toEqual([]);
+ }
+ });
+ it("uses the canonical SARIF 2.1.0 writer and actual package identity", async () => {
+ const { dir } = await execute([finding({ relativePath: "src\\sample.ts" })]);
+ const sarif = JSON.parse(await readFile(path.join(dir, "ackit.sarif"), "utf8"));
+ expect(sarif.version).toBe("2.1.0");
+ expect(sarif.runs[0].tool.driver.version).toBe(getPackageIdentity().version);
+ expect(sarif.runs[0].results[0].locations[0].physicalLocation).toEqual({
+ artifactLocation: { uri: "src/sample.ts" },
+ region: { startLine: 2, startColumn: 1 },
+ });
+ expect(await readFile(path.join(dir, "outputs"), "utf8")).toContain("sarif-path=");
+ });
+ it("does not advertise a SARIF output when it was not produced", async () => {
+ const { dir } = await execute([], { sarif: "false" });
+ expect(await readFile(path.join(dir, "outputs"), "utf8")).not.toContain("sarif-path=");
+ await expect(readFile(path.join(dir, "ackit.sarif"))).rejects.toMatchObject({ code: "ENOENT" });
+ });
+ it("escapes annotation property delimiters and workflow command newlines", async () => {
+ const result = await execute([
+ finding({ relativePath: "a,b:c\nfile.txt", message: "first\n::error::fake" }),
+ ]);
+ expect(result.messages[0]).toContain("file=a%2Cb%3Ac%0Afile.txt");
+ expect(result.messages[0]).toContain("first%0A::error::fake");
+ expect(result.messages[0]).not.toContain("\n");
+ });
+ it("passes metacharacters as literal argv, without shell evaluation", async () => {
+ const result = await execute([], { args: '"$(echo unsafe)" "; echo unsafe"' });
+ expect(result.argv.slice(2, -1)).toEqual(["$(echo unsafe)", "; echo unsafe"]);
+ expect(splitActionArgs('--root "directory with spaces"\t--quiet')).toEqual([
+ "--root",
+ "directory with spaces",
+ "--quiet",
+ ]);
+ });
+});