diff --git a/ackit-spec-kit-bridge/architecture/index.html b/ackit-spec-kit-bridge/architecture/index.html new file mode 100644 index 0000000..ef0bf9f --- /dev/null +++ b/ackit-spec-kit-bridge/architecture/index.html @@ -0,0 +1,53 @@ + + + + + + + + + Architecture — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Architecture

GitHub Spec Kit (intent / specify / plan / tasks / implement / converge)
+    ↓ SpecKitAdapter (feature + artifact discovery)
+    ↓ Bridge lifecycle mapping (feature → ACKit task/ref)
+    ↓ AckitAdapter (task / evidence / verification subprocesses)
+    ↓ ACKit task / evidence / verification
+    ↓ State-bound verdict (subjectDigest + evidenceDigest)
+    ↓ Completion gate (FRESH PASS or refuse)
+    ↓ Checkpoint / handoff (deterministic resume)

Spec Kit owns intent, specify, plan, tasks, implement, converge. ACKit owns repository context, policy, evidence, verification and completion trust, status, checkpoint, handoff. The bridge coordinates; it replaces neither.

+ + + + diff --git a/ackit-spec-kit-bridge/cli/index.html b/ackit-spec-kit-bridge/cli/index.html new file mode 100644 index 0000000..f9d9662 --- /dev/null +++ b/ackit-spec-kit-bridge/cli/index.html @@ -0,0 +1,56 @@ + + + + + + + + + CLI Reference — Bridge 0.1.1 + + + + + + + + + + + + + + + +

CLI Reference

Every --json payload validates against the deterministic schemas shipped in schemas/.

ackit-speckit init [--dry-run]
+ackit-speckit doctor [--json]
+ackit-speckit sync [--dry-run]
+ackit-speckit status [--json]
+ackit-speckit verify --profile quick|standard|high-risk [--json]
+ackit-speckit gate [--json]
+ackit-speckit checkpoint [--json]
+ackit-speckit handoff [--format markdown|json]
+ackit-speckit complete [--json]
+ackit-speckit explain [--json]
+ackit-speckit version [--json]

Exit codes

0 success/pass, 1 gate/verification failed or stale, 2 usage/config error, 3 environment/dependency error, 4 security boundary violation, 5 internal error.

+ + + + diff --git a/ackit-spec-kit-bridge/compatibility/index.html b/ackit-spec-kit-bridge/compatibility/index.html new file mode 100644 index 0000000..629dbbe --- /dev/null +++ b/ackit-spec-kit-bridge/compatibility/index.html @@ -0,0 +1,46 @@ + + + + + + + + + Compatibility — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Compatibility

Bridge versioning is independent from ACKit and Spec Kit versions (semver). doctor reports live compatibility.

Node>= 22 (tested 24.13.0)
pnpm11.22.0
ACKit>= 0.5.0 (tested 0.5.4)
Spec Kit (specify)>= 1.0.0 (tested 1.0.13)
Windowssupported (PowerShell 7+)
Linux (Ubuntu)supported (CI)
macOSbest-effort

Bridge 0.1.1 was tested against ACKit 0.5.4 and Spec Kit specify 1.0.13.

+ + + + diff --git a/ackit-spec-kit-bridge/configuration/index.html b/ackit-spec-kit-bridge/configuration/index.html new file mode 100644 index 0000000..ac760d5 --- /dev/null +++ b/ackit-spec-kit-bridge/configuration/index.html @@ -0,0 +1,63 @@ + + + + + + + + + Configuration — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Configuration

Committed config .ackit-spec-kit/config.yml (schema version 1). No executable code, no shell snippets.

schemaVersion: 1
+ackit:
+  command: ackit
+  minVersion: 0.5.0
+specKit:
+  command: specify
+  minVersion: 1.0.0
+mapping:
+  mode: active-feature
+verification:
+  defaultProfile: standard
+  stalePolicy: fail
+profiles:
+  quick: {}
+  standard: {}
+  high-risk: {}
+evidence:
+  redact: true

State lives under .ackit-spec-kit/ (state/, verdicts/, bundles/, checkpoints/, handoffs/, evidence/, mapping.json).

+ + + + diff --git a/ackit-spec-kit-bridge/getting-started/index.html b/ackit-spec-kit-bridge/getting-started/index.html new file mode 100644 index 0000000..61b44f5 --- /dev/null +++ b/ackit-spec-kit-bridge/getting-started/index.html @@ -0,0 +1,55 @@ + + + + + + + + + Getting Started — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Getting Started

Requires Node.js 22+, the ACKit CLI, the Spec Kit specify CLI, and Git.

Install

npm install --global @cynrath/ackit-spec-kit-bridge@0.1.1
+ackit-speckit --version
+ackit-speckit --help

First pass

git init
+ackit init
+specify init --here --integration copilot
+ackit-speckit init
+ackit-speckit sync
+ackit-speckit status --json
+ackit-speckit verify --profile standard
+ackit-speckit gate

Then mutate a spec and watch freshness work: status → STALE, gate → FAIL, re-verify → PASS. Full walkthrough: Trust Flow.

Get StartedCLIGitHubnpmAgentContextKit

+ + + + diff --git a/ackit-spec-kit-bridge/index.html b/ackit-spec-kit-bridge/index.html new file mode 100644 index 0000000..53c2c76 --- /dev/null +++ b/ackit-spec-kit-bridge/index.html @@ -0,0 +1,61 @@ + + + + + + + + + ACKit Spec Kit Bridge — Bridge 0.1.1 + + + + + + + + + + + + + + + +

ACKit Spec Kit Bridge 0.1.1

GitHub Spec Kit intent → ACKit verification trust. The bridge connects Spec Kit's intent-driven workflow to ACKit's deterministic task, evidence, verification, freshness, completion-gate, checkpoint, and handoff system.

Community integration for ACKit and GitHub Spec Kit. Not an official GitHub integration.

Get StartedCLIGitHubnpmAgentContextKit

Install

npm install --global @cynrath/ackit-spec-kit-bridge@0.1.1
+ackit-speckit --version
+ackit-speckit --help

Workflow

Spec Kit
+spec → plan → tasks → implementation
+             ↓
+       ackit-speckit sync
+             ↓
+ACKit task / refs
+             ↓
+verification bundle
+             ↓
+fresh PASS verdict
+             ↓
+completion gate
+             ↓
+checkpoint / handoff

Capabilities

Trust flow

A verdict binds subjectDigest + evidenceDigest + profile + result. Editing any verified state flips the verdict to STALE and fails the gate until you re-verify. See Verification and Trust Flow.

Compatibility

Node>= 22 (tested 24.13.0)
pnpm11.22.0
ACKit>= 0.5.0 (tested 0.5.4)
Spec Kit (specify)>= 1.0.0 (tested 1.0.13)
Windowssupported (PowerShell 7+)
Linux (Ubuntu)supported (CI)
macOSbest-effort
+ + + + diff --git a/ackit-spec-kit-bridge/lifecycle/index.html b/ackit-spec-kit-bridge/lifecycle/index.html new file mode 100644 index 0000000..3b0afab --- /dev/null +++ b/ackit-spec-kit-bridge/lifecycle/index.html @@ -0,0 +1,46 @@ + + + + + + + + + Lifecycle — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Lifecycle

Derived deterministically; BLOCKED wins over everything except UNINITIALIZED; COMPLETE requires a fresh PASS plus a completed ACKit task.

status is read-only and never writes.

+ + + + diff --git a/ackit-spec-kit-bridge/llms-full.txt b/ackit-spec-kit-bridge/llms-full.txt new file mode 100644 index 0000000..cd65646 --- /dev/null +++ b/ackit-spec-kit-bridge/llms-full.txt @@ -0,0 +1,455 @@ +# ACKit Spec Kit Bridge 0.1.1 + +# ACKit Spec Kit Bridge + +

+ Connect GitHub Spec Kit's intent-driven development workflow to ACKit's deterministic task, evidence, verification, freshness, completion-gate, checkpoint, and handoff system. +

+ +

+ npm version + downloads + stars + CI +

+ +

+ release + license + node + offline-first + deterministic + community integration +

+ +> **Community integration for ACKit and GitHub Spec Kit. Not an official GitHub integration.** + +Spec Kit owns intent: `specify → plan → tasks → implement → converge`. +ACKit owns trust: repository context, policy, evidence, verification, completion trust, status, checkpoint, handoff. +The bridge coordinates the two — it replaces neither. + +## Demo (60 seconds) + +```powershell +npm install --global @cynrath/ackit-spec-kit-bridge +ackit-speckit doctor +ackit-speckit sync +ackit-speckit status +ackit-speckit verify --profile standard +ackit-speckit gate +``` + +Stale-state protection — the core guarantee: + +```powershell +ackit-speckit verify --profile standard # PASS (exit 0), binds subject + evidence digests +ackit-speckit gate # PASS (exit 0) +# ... edit specs/001-*/spec.md, plan.md, tasks.md, or mapped ACKit task/config ... +ackit-speckit status # STALE +ackit-speckit gate # FAIL (exit 1, VERDICT_STALE) +ackit-speckit verify --profile standard # PASS again (exit 0), fresh verdict +ackit-speckit gate # PASS (exit 0) +``` + +Exit codes: `0` success/pass · `1` gate/verification failed or stale · `2` usage/config error · `3` environment/dependency error · `4` security boundary violation · `5` internal error. + +## Why + +Without the bridge, Spec Kit and ACKit live in separate worlds: + +| Before | With Bridge | +|---|---| +| Spec Kit creates intent/spec/plan/tasks, but ACKit lifecycle, evidence, verdict, and completion state are separate | Spec Kit artifacts become explicit ACKit refs via `sync` | +| Verification (if any) floats free of the exact state it checked | Verification binds `subjectDigest + evidenceDigest + profile + result` | +| Editing a spec after "done" silently invalidates prior conclusions | Any subject change flips the verdict to `STALE` | +| Completion is a judgment call | Completion is refused until a fresh verification passes (`gate`) | +| Resuming later means re-reading everything | `checkpoint` / `handoff` export deterministic resume context | + +## Install + +```powershell +npm install --global @cynrath/ackit-spec-kit-bridge +ackit-speckit --version +ackit-speckit --help +``` + +Pinned install: + +```powershell +npm install --global @cynrath/ackit-spec-kit-bridge@0.1.1 +``` + +POSIX shells work identically (`ackit-speckit doctor`, etc.). + +## Prerequisites + +- Node.js >= 22, pnpm 11 +- ACKit CLI (`npm install -g @cynrath/agent-context-kit`, tested 0.5.4, min 0.5.0) +- Spec Kit `specify` CLI (tested 1.0.13, min 1.0.0; Python 3.11+ via `uv tool install specify-cli`) +- Git, PowerShell 7+ on Windows + +`ackit-speckit doctor` checks every prerequisite with stable check IDs and reports `ok`/`fail` per check. + +## Quickstart + +```powershell +git init +ackit init +specify init --here --integration copilot +ackit-speckit init +ackit-speckit sync +ackit-speckit status --json +ackit-speckit verify --profile standard +ackit-speckit gate +``` + +Full lifecycle: + +```powershell +ackit-speckit sync # TASKED +ackit-speckit status # canonical state (read-only, never writes) +ackit-speckit verify --profile standard # PASS, binds subject + evidence digests +ackit-speckit gate # PASS +ackit-speckit checkpoint # deterministic resume point +ackit-speckit handoff # human/agent handoff (markdown or JSON) +ackit-speckit complete # COMPLETE — only after a fresh PASS gate +``` + +Every `--json` payload validates against [`schemas/`](schemas/). + +## Features + +Only implemented, tested behavior is listed. + +| Area | Capability | +|---|---| +| Discovery | Active Spec Kit feature resolution (`specs/NNN-*` + active tracking) | +| Discovery | Spec Kit artifact discovery (spec.md, plan.md, tasks.md, checklists) | +| Sync | Spec Kit → ACKit task/ref synchronization (`sync`, idempotent re-runs) | +| Sync | Idempotent sync — same state in, same mapping out, no duplicates | +| Lifecycle | Canonical lifecycle status (`status`, read-only, never writes) | +| Verification | State-bound verification bundles (`verify`, per-profile checks) | +| Verification | Subject digest (spec/plan/tasks, ACKit task/config/policy, bridge config/profile/version, tool versions, Git HEAD/diffs) | +| Verification | Evidence digest (redacted per-check outputs, content-addressed refs) | +| Verification | Verdict freshness (`FRESH` / `STALE` / `NOT_VERIFIED`) | +| Verification | Stale detection on any subject change (`stalePolicy: fail`) | +| Verification | `quick` / `standard` / `high-risk` profiles (ranked; higher satisfies lower) | +| Gate | Completion gate (`gate`, read-only; STALE fails with exit 1) | +| Continuity | Deterministic checkpoints (`checkpoint`, resume context) | +| Continuity | Human/agent handoffs (`handoff --format markdown|json`) | +| Provenance | `explain` — lifecycle derivation + gate provenance | +| Doctor | `doctor` — environment + compatibility checks with stable check IDs | +| Contracts | Deterministic JSON schemas for config, status, bundles, verdicts, checkpoints, handoffs | +| Spec Kit | Native extension (`spec-kit/extension`, id `ackit`, 7 `speckit.ackit.*` commands + lifecycle hooks) | +| Spec Kit | Workflow package (`spec-kit/workflow`, `ackit-verified-sdd`) | +| Hooks | `after_specify` / `after_plan` / `after_tasks` → sync; `before_implement` → status preflight; `after_implement` → verify (never auto-completes) | +| Platform | Windows + Linux (CI); macOS best-effort | +| Runtime | Offline-first — no network calls, no telemetry, no LLM/API dependency | +| Safety | Subprocess argv arrays with `shell: false`; path containment; bounded reads/output; redacted evidence; atomic state writes | +| Quality | Package/CI smoke (`smoke:cli`, `smoke:extension`, `smoke:package`); ACKit dogfooding (`config check`, `scan --ci`, `policy check`) | + +## How it works + +```mermaid +flowchart TD + SK["GitHub Spec Kit
intent / specify / plan / tasks / implement / converge"] --> AD["SpecKitAdapter
feature + artifact discovery"] + AD --> LM["Bridge lifecycle mapping
feature → ACKit task/ref"] + LM --> AA["AckitAdapter
task / evidence / verification subprocesses"] + AA --> AK["ACKit task / evidence / verification
context / policy / evidence / status"] + AK --> V["State-bound verdict
subjectDigest + evidenceDigest"] + V --> G["Completion Gate
FRESH PASS or refuse"] + G --> CH["Checkpoint / Handoff
deterministic resume"] +``` + +Ownership is explicit: + +- **Spec Kit owns:** intent, `specify`, `plan`, `tasks`, `implement`, converge. +- **ACKit owns:** repository context, policy, evidence, verification trust, completion trust, status, checkpoint, handoff. +- **The bridge owns:** discovery, mapping, digest computation, bundle assembly, freshness comparison, gate evaluation, checkpoint/handoff rendering — coordination only. + +## CLI overview + +| Command | Purpose | +|---|---| +| `init [--dry-run]` | Verify repo/ACKit/Spec Kit, write config + state dirs + mapping | +| `doctor [--json]` | Environment + compatibility checks with stable check IDs | +| `sync [--dry-run]` | Map active Spec Kit feature → ACKit task (idempotent) | +| `status [--json]` | Read-only canonical lifecycle state (never writes) | +| `verify --profile quick\|standard\|high-risk [--json]` | State-bound bundle + verdict | +| `gate [--json]` | Read-only completion gate (STALE fails) | +| `checkpoint [--json]` | Deterministic resume checkpoint | +| `handoff [--format markdown\|json]` | Human/agent handoff | +| `complete [--json]` | Gate-checked ACKit task completion | +| `explain [--json]` | Lifecycle + gate provenance | +| `version [--json]` | Bridge + compat versions | + +
+Exit codes and JSON contracts + +Exit codes: `0` success/pass · `1` gate/verification failed or stale · `2` usage/config error · `3` environment/dependency error · `4` security boundary violation · `5` internal error. + +JSON schemas live in [`schemas/`](schemas/): config, status (`ackit.speckit.status.v1`), verification bundle, verdict (`ackit.verdict.v1/v2` family), checkpoint, handoff, error (`ackit.speckit.error.v1`). + +
+ +## Lifecycle states + +Derived deterministically (`deriveLifecycle`); `BLOCKED` wins over everything except `UNINITIALIZED`; `COMPLETE` requires a fresh `PASS` plus a completed ACKit task. + +| State | Meaning | +|---|---| +| `UNINITIALIZED` | ACKit or Spec Kit not initialized | +| `READY` | Initialized; no active feature (or spec missing) | +| `SPECIFIED` | Spec present, plan missing | +| `PLANNED` | Plan present, tasks/mapping missing | +| `TASKED` | Tasks + mapping present, no verdict yet | +| `IMPLEMENTING` | Verdict `FAIL` (work to do) | +| `VERIFYING` | (transient) verification running | +| `VERIFIED` | Fresh `PASS` verdict | +| `STALE` | Verdict exists but subject moved — re-verify | +| `BLOCKED` | Explicit block reason | +| `COMPLETE` | Task completed with a fresh `PASS` | + +Details: [`docs/architecture/lifecycle.md`](docs/architecture/lifecycle.md), [`docs/reference/lifecycle-status.md`](docs/reference/lifecycle-status.md). + +## Verification / freshness model + +A verdict binds `subjectDigest + evidenceDigest + profile + result`. + +- `subjectDigest` covers Spec Kit artifacts, the ACKit task/config/policy snapshot, bridge config/profile/version, tool versions, and Git HEAD/diffs. +- `evidenceDigest` covers the redacted per-check outputs. +- `status` / `gate` recompute the subject digest and compare it with the stored verdict: `FRESH`, `STALE`, or `NOT_VERIFIED`. +- `stalePolicy: fail` (the only mode) means `STALE` fails the gate with `VERDICT_STALE` and exit 1. + +Details: [`docs/architecture/state-digest.md`](docs/architecture/state-digest.md), [`docs/concepts/verification-freshness.md`](docs/concepts/verification-freshness.md). + +## Verification profiles + +Ranked `quick < standard < high-risk`; a higher-rank verdict satisfies a lower-rank gate (`profileSatisfies`). + +- `quick` — bridge config validation + ACKit config check (fast preflight). +- `standard` — quick plus Spec Kit artifact presence, mapping integrity, ACKit scan/policy surface (default; CI recommended). +- `high-risk` — standard plus extended evidence capture and strict completeness (release-grade changes). + +```powershell +ackit-speckit verify --profile quick +ackit-speckit verify --profile standard +ackit-speckit verify --profile high-risk +``` + +## Spec Kit extension + +Native extension (`spec-kit/extension`, id `ackit`): + +```powershell +specify extension add ackit --dev ./spec-kit/extension +specify extension list +specify artifact list --json +``` + +Commands: `speckit.ackit.sync|status|verify|gate|checkpoint|handoff|complete` (each delegates to `ackit-speckit`). +Hooks: `after_specify`, `after_plan`, `after_tasks` → sync; `before_implement` → status preflight; `after_implement` → verify (never auto-completes). + +See [`docs/guides/spec-kit-extension.md`](docs/guides/spec-kit-extension.md). + +## Spec Kit workflow + +Workflow package `spec-kit/workflow/workflow.yml` (`ackit-verified-sdd`): spec → plan → tasks → sync → implement → verify → gate → checkpoint/handoff → complete. Hooks enforce verification after implementation and refuse completion on stale verdicts. + +## Configuration + +`.ackit-spec-kit/config.yml` (schema version 1): + +```yaml +schemaVersion: 1 +ackit: + command: ackit + minVersion: 0.5.0 +specKit: + command: specify + minVersion: 1.0.0 +mapping: + mode: active-feature +verification: + defaultProfile: standard + stalePolicy: fail +profiles: + quick: {} + standard: {} + high-risk: {} +evidence: + redact: true +``` + +State lives under `.ackit-spec-kit/` (`state/`, `verdicts/`, `bundles/`, `checkpoints/`, `handoffs/`, `evidence/`, `mapping.json`) — never commit verdicts/bundles as source of truth; they are derived. + +See [`docs/reference/configuration.md`](docs/reference/configuration.md). + +## JSON schemas + +[`schemas/`](schemas/) holds deterministic contracts for config, status, verification bundles, verdicts, checkpoints, and handoffs. Every `--json` payload validates against them; CI re-validates fixtures on each run. + +See [`docs/reference/schemas.md`](docs/reference/schemas.md). + +## Security + +Offline-first runtime: no network calls, no telemetry, no uploads, no LLM/API dependency in product code. Subprocesses use argv arrays with `shell: false`. Path containment anchors all reads/writes to the repository root. Reads and outputs are size-bounded. Evidence is redacted at construction. State writes are atomic. + +See [`docs/architecture/security-model.md`](docs/architecture/security-model.md) and [`SECURITY.md`](SECURITY.md). + +## CI + +```yaml +- run: npx --yes @cynrath/ackit-spec-kit-bridge doctor +- run: ackit-speckit verify --profile standard +- run: ackit-speckit gate +``` + +Gate failures exit 1 and fail the pipeline. See [`docs/guides/ci.md`](docs/guides/ci.md). + +## Compatibility + +| Component | Supported / tested | +|---|---| +| Node | >= 22 (tested 24.13.0) | +| pnpm | 11.22.0 | +| ACKit | >= 0.5.0 (tested 0.5.4) | +| Spec Kit (`specify`) | >= 1.0.0 (tested 1.0.13) | +| Windows | supported (PowerShell 7+) | +| Linux (Ubuntu) | supported (CI) | +| macOS | best-effort (not tested in v0.1.1) | + +Bridge versioning is independent from ACKit and Spec Kit versions (semver). `doctor` reports live compatibility. See [`docs/reference/compatibility.md`](docs/reference/compatibility.md). + +## Hosted documentation + +- Bridge docs: +- ACKit docs: +- Cynrath home: + +## Development + +```powershell +pnpm install --frozen-lockfile +pnpm lint +pnpm format:check +pnpm typecheck +pnpm build +pnpm test +pnpm smoke:cli +pnpm smoke:extension +pnpm smoke:package +node dist/cli/index.js doctor +``` + +ACKit dogfooding: `ackit config check`, `ackit scan --ci`, `ackit policy check`, `ackit readiness`. + +## Release model + +Releases are tag-driven: push `vX.Y.Z` → GitHub Actions (`release.yml`) → OIDC Trusted Publishing (`npm publish --provenance`, no tokens) → registry/shasum/fresh-consumer verification → GitHub Release with the exact tarball, extension/workflow archives, and checksums. + +Normal releases require no manual npm approval. An optional staged mode (`npm stage publish` → manual security-key approval) exists for maximum-assurance publishes but is not the default. + +See [`docs/guides/release.md`](docs/guides/release.md). + +## Roadmap + +See [`ROADMAP.md`](ROADMAP.md). Direction: deeper Spec Kit lifecycle coverage, richer verification evidence, and tighter ACKit ecosystem links — without duplicating ACKit core or implying official GitHub status. + +## Links + +- Bridge repo: +- npm: +- Hosted docs: +- ACKit: +- ACKit npm: +- Spec Kit upstream: +- Cynrath: + +## License + +MIT — see [`LICENSE`](LICENSE). + + +--- + +# Changelog + +# Changelog + +All notable changes to `@cynrath/ackit-spec-kit-bridge` are documented here. +This project follows Semantic Versioning. + +## [0.1.1] - 2026-10-02 + +Public-surface and release-automation hardening. No behavior change to the +verified lifecycle, digest, gate, or CLI contract. + +### Added + +- Rewritten `README.md` to ACKit-quality presentation: badges, 60-second + demo, stale-verdict demo, Before/With-Bridge table, full feature + inventory, Mermaid architecture with Spec Kit/ACKit ownership, and + complete section coverage (Why through License). +- New guides: `docs/guides/trust-flow-demo.md` (verify → mutate → STALE → + re-verify walkthrough) and `docs/guides/release.md` (tag → OIDC publish + → verify → GitHub Release, plus one-time Trusted Publisher setup). +- New concepts: `docs/concepts/spec-kit-and-ackit.md` (ownership + boundaries) and `docs/concepts/verification-freshness.md` (subject + + evidence digests, freshness comparison, `stalePolicy: fail`). +- Hosted documentation surface at + `https://cynrath.github.io/ackit-spec-kit-bridge/` (generated from this + repo's `docs/`, `README.md`, and `package.json`). +- Hardened `release.yml`: exact `vX.Y.Z` tag validation, tag/package + parity, frozen install, lint/format/typecheck/build, unit tests, all + three smoke suites, ACKit gates, single exact-tarball audit, npm + version-absence gate, OIDC `npm publish --provenance` (no tokens), + registry/shasum/fresh-consumer verification, GitHub Release only after + npm verification. + +### Fixed + +- Removed stale "npm publication pending / install from tarball" note; + install is now the normal `npm install --global` + `@cynrath/ackit-spec-kit-bridge` (plus pinned variant). +- `package.json` `exports["."].types` now points to `./dist/index.d.ts` + (was `./dist/index.js`); `homepage` points to the hosted bridge docs. +- `spec-kit/extension/extension.yml` version parity (`0.1.1`) and homepage + points to the hosted bridge docs. + +### Compatibility + +- Tested against ACKit 0.5.4 and Spec Kit specify 1.0.13 on Windows + (Node 24.13.0, pnpm 11.22.0); Ubuntu in CI. + +## [0.1.0] - 2026-10-02 + +First public release: community integration for ACKit and GitHub Spec Kit. + +### Added + +- `ackit-speckit` CLI with `init`, `doctor`, `sync`, `status`, `verify`, + `gate`, `checkpoint`, `handoff`, `complete`, `explain`, `version`; + stable exit codes (0/1/2/3/4/5) and `--json` contracts. +- State-bound verification: canonical `subjectDigest` + `evidenceDigest`, + PASS/FAIL verdicts, STALE on any subject change, read-only gate, safe + completion via ACKit's own task lifecycle. +- Deterministic lifecycle: UNINITIALIZED → READY → SPECIFIED → PLANNED → + TASKED → IMPLEMENTING → VERIFIED → COMPLETE, plus STALE/BLOCKED. +- Native Spec Kit extension (`spec-kit/extension`, id `ackit`) with 7 + `speckit.ackit.*` commands and sync/status/verify hooks; `ackit-verified-sdd` + workflow package (`spec-kit/workflow`). +- JSON schemas for config, status, verification bundle, verdict, checkpoint, + handoff; redacted evidence; offline-first, no telemetry. +- Tests: unit, integration (real temp Git/ACKit/Spec Kit repos), freshness + mutation, security (traversal/injection/redaction/unicode/spaces), E2E, + package + extension smoke. +- Docs: architecture (overview/lifecycle/state-digest/security), guides, + CLI/config/schema/lifecycle/compatibility references, 3 ADRs. +- CI: `ci.yml` (Windows + Ubuntu), `security.yml`, `dependency-review.yml`, + `release.yml` with npm tarball + extension/workflow archives + SHA256SUMS. + +### Compatibility + +- Tested against ACKit 0.5.4 and Spec Kit specify 1.0.13 on Windows + (Node 24.13.0, pnpm 11.22.0); Ubuntu in CI. diff --git a/ackit-spec-kit-bridge/llms.txt b/ackit-spec-kit-bridge/llms.txt new file mode 100644 index 0000000..c40396f --- /dev/null +++ b/ackit-spec-kit-bridge/llms.txt @@ -0,0 +1,28 @@ +# ACKit Spec Kit Bridge + +> ACKit Spec Kit Bridge 0.1.1 connects GitHub Spec Kit's intent-driven workflow to ACKit's deterministic task, evidence, verification, freshness, completion-gate, checkpoint, and handoff system. Community integration — not an official GitHub integration. + +## Documentation + +- [ACKit Spec Kit Bridge](https://cynrath.github.io/ackit-spec-kit-bridge/): GitHub Spec Kit intent → ACKit verification trust. State-bound verification, completion gates, checkpoints and handoffs. Offline-first, deterministic. +- [Getting Started](https://cynrath.github.io/ackit-spec-kit-bridge/getting-started/): Install the bridge and run the first sync, verification and gate. +- [CLI Reference](https://cynrath.github.io/ackit-spec-kit-bridge/cli/): ackit-speckit commands, options, exit codes and JSON contracts. +- [Lifecycle](https://cynrath.github.io/ackit-spec-kit-bridge/lifecycle/): Canonical bridge lifecycle states and derivation. +- [Verification](https://cynrath.github.io/ackit-spec-kit-bridge/verification/): State-bound verification bundles, digests and freshness. +- [Verification Profiles](https://cynrath.github.io/ackit-spec-kit-bridge/profiles/): quick, standard and high-risk verification profiles. +- [Spec Kit Extension](https://cynrath.github.io/ackit-spec-kit-bridge/spec-kit-extension/): Native Spec Kit extension and workflow package. +- [Configuration](https://cynrath.github.io/ackit-spec-kit-bridge/configuration/): Bridge config file and state layout. +- [Security](https://cynrath.github.io/ackit-spec-kit-bridge/security/): Offline-first threat model and safety guarantees. +- [Compatibility](https://cynrath.github.io/ackit-spec-kit-bridge/compatibility/): Tested ACKit, Spec Kit, Node and OS ranges. +- [Architecture](https://cynrath.github.io/ackit-spec-kit-bridge/architecture/): Adapters, lifecycle mapping and ownership boundaries. +- [Trust Flow](https://cynrath.github.io/ackit-spec-kit-bridge/trust-flow/): Verify, mutate, stale, re-verify: the freshness guarantee. +- [Troubleshooting](https://cynrath.github.io/ackit-spec-kit-bridge/troubleshooting/): Diagnose init, sync, verify and gate failures. +- [Release Model](https://cynrath.github.io/ackit-spec-kit-bridge/release/): Tag-driven OIDC releases with no manual npm approval. + +## Source and package + +- [GitHub](https://github.com/Cynrath/ackit-spec-kit-bridge) +- [npm](https://www.npmjs.com/package/@cynrath/ackit-spec-kit-bridge) +- [AgentContextKit](https://github.com/Cynrath/agent-context-kit) +- [GitHub Spec Kit](https://github.com/github/spec-kit) +- [Cynrath](https://cynrath.github.io/) diff --git a/ackit-spec-kit-bridge/profiles/index.html b/ackit-spec-kit-bridge/profiles/index.html new file mode 100644 index 0000000..f68859e --- /dev/null +++ b/ackit-spec-kit-bridge/profiles/index.html @@ -0,0 +1,48 @@ + + + + + + + + + Verification Profiles — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Verification Profiles

Ranked quick < standard < high-risk; a higher-rank verdict satisfies a lower-rank gate.

  • quick — bridge + ACKit config validation (fast preflight).
  • standard — quick plus artifact presence, mapping integrity, ACKit scan/policy surface (default; CI recommended).
  • high-risk — standard plus extended evidence capture and strict completeness (release-grade changes).
ackit-speckit verify --profile quick
+ackit-speckit verify --profile standard
+ackit-speckit verify --profile high-risk
+
+ + + diff --git a/ackit-spec-kit-bridge/release/index.html b/ackit-spec-kit-bridge/release/index.html new file mode 100644 index 0000000..eadc8e9 --- /dev/null +++ b/ackit-spec-kit-bridge/release/index.html @@ -0,0 +1,46 @@ + + + + + + + + + Release Model — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Release Model

Push vX.Y.Z → GitHub Actions → OIDC Trusted Publishing (npm publish --provenance, no tokens) → registry/shasum/fresh-consumer verification → GitHub Release. Normal releases require no manual npm approval. Bridge 0.1.1 is the current release.

Upstream sources: GitHub, npm, AgentContextKit, GitHub Spec Kit.

+
+ + + diff --git a/ackit-spec-kit-bridge/security/index.html b/ackit-spec-kit-bridge/security/index.html new file mode 100644 index 0000000..f5f3fad --- /dev/null +++ b/ackit-spec-kit-bridge/security/index.html @@ -0,0 +1,46 @@ + + + + + + + + + Security — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Security

  • Offline-first: no network calls, no telemetry, no uploads, no LLM/API dependency in product code.
  • Subprocesses use argv arrays with shell: false; never interpolate untrusted values into shell strings.
  • Path containment anchors all reads/writes to the repository root.
  • Reads and outputs are size-bounded; evidence is redacted at construction.
  • State writes are atomic.

Community integration for ACKit and GitHub Spec Kit — not an official GitHub integration.

+
+ + + diff --git a/ackit-spec-kit-bridge/spec-kit-extension/index.html b/ackit-spec-kit-bridge/spec-kit-extension/index.html new file mode 100644 index 0000000..f7b574a --- /dev/null +++ b/ackit-spec-kit-bridge/spec-kit-extension/index.html @@ -0,0 +1,48 @@ + + + + + + + + + Spec Kit Extension — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Spec Kit Extension

Native extension (spec-kit/extension, id ackit) with 7 commands, each delegating to ackit-speckit:

specify extension add ackit --dev ./spec-kit/extension
+specify extension list
+specify artifact list --json

Commands: speckit.ackit.sync|status|verify|gate|checkpoint|handoff|complete. Hooks: after_specify, after_plan, after_tasks → sync; before_implement → status preflight; after_implement → verify (never auto-completes). Workflow package spec-kit/workflow/workflow.yml (ackit-verified-sdd) encodes the verified SDD cycle.

+
+ + + diff --git a/ackit-spec-kit-bridge/troubleshooting/index.html b/ackit-spec-kit-bridge/troubleshooting/index.html new file mode 100644 index 0000000..ecacd74 --- /dev/null +++ b/ackit-spec-kit-bridge/troubleshooting/index.html @@ -0,0 +1,46 @@ + + + + + + + + + Troubleshooting — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Troubleshooting

  • Run ackit-speckit doctor first: stable check IDs pinpoint missing Node/ACKit/Spec Kit/Git prerequisites.
  • NOT_VERIFIED gate: run verify before gate.
  • VERDICT_STALE gate: re-run verify; do not bypass — there is no accept-stale flag by design.
  • exit 2: usage/config error — validate .ackit-spec-kit/config.yml against schemas/config.schema.json.
  • exit 3: environment/dependency error — check doctor versions against Compatibility.
  • exit 4: security boundary violation — a path escaped the repository root.
+
+ + + diff --git a/ackit-spec-kit-bridge/trust-flow/index.html b/ackit-spec-kit-bridge/trust-flow/index.html new file mode 100644 index 0000000..d1dee21 --- /dev/null +++ b/ackit-spec-kit-bridge/trust-flow/index.html @@ -0,0 +1,54 @@ + + + + + + + + + Trust Flow — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Trust Flow

ackit-speckit verify --profile standard   # PASS (exit 0)
+ackit-speckit gate                        # PASS (exit 0)
+# ... edit specs/001-*/spec.md ...
+ackit-speckit status                      # STALE
+ackit-speckit gate                        # FAIL (exit 1, VERDICT_STALE)
+ackit-speckit verify --profile standard   # PASS again
+ackit-speckit checkpoint
+ackit-speckit handoff
+ackit-speckit complete                    # only after fresh PASS gate

"Verified" means "verified this exact state". Any subject change — spec, plan, tasks, mapped ACKit task, configs, Git diff — stales the verdict by construction.

+
+ + + diff --git a/ackit-spec-kit-bridge/verification/index.html b/ackit-spec-kit-bridge/verification/index.html new file mode 100644 index 0000000..1583ce2 --- /dev/null +++ b/ackit-spec-kit-bridge/verification/index.html @@ -0,0 +1,47 @@ + + + + + + + + + Verification — Bridge 0.1.1 + + + + + + + + + + + + + + + +

Verification

A verdict binds subjectDigest + evidenceDigest + profile + result. The subject digest covers Spec Kit artifacts, the ACKit task/config/policy snapshot, bridge config/profile/version, tool versions, and Git HEAD/diffs. The evidence digest covers redacted per-check outputs.

ackit-speckit verify --profile standard
+ackit-speckit gate

Freshness

status / gate recompute the subject digest: equal → FRESH, differ → STALE (gate fails, exit 1), missing → NOT_VERIFIED. stalePolicy: fail is the only supported policy.

+
+ + + diff --git a/agent-context-kit/llms-full.txt b/agent-context-kit/llms-full.txt index c43475f..a990004 100644 --- a/agent-context-kit/llms-full.txt +++ b/agent-context-kit/llms-full.txt @@ -404,10 +404,20 @@ 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) | +| 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) | | 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) | +| 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 | + +--- + +### 🔗 Ecosystem + +Community integration for ACKit and GitHub Spec Kit: [Spec Kit bridge](docs/guides/spec-kit-bridge.md) +([`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge)) connects +Spec Kit's intent-driven development artifacts to ACKit's deterministic repository context, task +lifecycle, evidence, verification, and completion gates. Offline-first, no telemetry. --- @@ -463,6 +473,21 @@ All notable changes to ACKit (`@cynrath/agent-context-kit`) are documented in th This project follows Semantic Versioning. +## [Unreleased] + +### Added + +- 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) + (bridge CLI + native Spec Kit extension + `ackit-verified-sdd` workflow). + No ACKit core behavior changed. +- Bridge 0.1.1 cross-links: ownership boundaries (Spec Kit owns intent, + ACKit owns trust, bridge coordinates), freshness-model summary, and + links to the hosted bridge docs + ([cynrath.github.io/ackit-spec-kit-bridge](https://cynrath.github.io/ackit-spec-kit-bridge/)), + npm, and the bridge repo with explicit community-integration wording. + ## [0.5.4] - 2026-09-22 Release-recovery patch (no runtime feature behavior beyond 0.5.3; no new diff --git a/ai-policy.txt b/ai-policy.txt index a4ea29f..b17c453 100644 --- a/ai-policy.txt +++ b/ai-policy.txt @@ -10,7 +10,7 @@ This is a publisher policy document. robots.txt remains the crawler-access contr - Crawl and index public pages in accordance with robots.txt. - Retrieve public content in response to a user request. - Summarize, quote short excerpts, and cite/link to the original page. -- Use public technical documentation to answer questions about Cynrath and AgentContextKit. +- Use public technical documentation to answer questions about Cynrath, AgentContextKit, and the ACKit Spec Kit Bridge. - Cache public content as reasonably necessary for search, retrieval, safety and citation systems. - Use public content for model improvement or training where the crawler/operator honors robots.txt and applicable law. @@ -19,6 +19,7 @@ This is a publisher policy document. robots.txt remains the crawler-access contr - Preserve source attribution when presenting factual claims derived from this site. - Prefer canonical URLs under https://cynrath.github.io/ and https://github.com/Cynrath/. - Treat https://github.com/Cynrath/agent-context-kit as the canonical product source for ACKit code and release state. +- Treat https://github.com/Cynrath/ackit-spec-kit-bridge as the canonical product source for bridge code and release state. - Do not represent generated summaries as statements endorsed by Cynrath. - Do not infer or expose private repositories, credentials, personal secrets, unpublished data or non-public account information. diff --git a/humans.txt b/humans.txt index a876dd3..b410cf9 100644 --- a/humans.txt +++ b/humans.txt @@ -7,6 +7,9 @@ GitHub: https://github.com/Cynrath Featured: AgentContextKit / ACKit Repository: https://github.com/Cynrath/agent-context-kit Documentation: https://cynrath.github.io/agent-context-kit/ +Integration: ACKit Spec Kit Bridge +Integration repository: https://github.com/Cynrath/ackit-spec-kit-bridge +Integration documentation: https://cynrath.github.io/ackit-spec-kit-bridge/ Stack: TypeScript, Node.js, .NET, C#, MSSQL, EF Core, Docker, Linux, Cloudflare /* SITE */ diff --git a/index.html b/index.html index 8423c4f..2ce81cd 100644 --- a/index.html +++ b/index.html @@ -1 +1 @@ -Cynrath — Developer tooling, web systems & infrastructure
Developer tooling · web systems · infrastructure

Developer tools.
Web systems.
Infrastructure.

TypeScript and .NET for CLI tooling, admin platforms, databases, automation, CI/CD and infrastructure.

TypeScript / Node.js.NET / C#Docker / LinuxCloudflare / CI
ackit / localv0.5.4
$ackit readiness
Readiness88/100██████████████████░░threshold 80 · pass✓ Instructions 90/100✓ Security 90/100✓ Context Efficiency 70/100
$
14stars
1fork
0open issues
Stack
TypeScriptNode.js.NET / C#MSSQL / EF CoreDocker / LinuxCloudflare
02 / AgentContextKit

Repository context you can inspect.

ACKit runs locally and turns repository instructions, context, tasks, policies, workflow state, evidence, verification, diagnostics and integrations into deterministic commands and stable outputs.

Installnpm install -g @cynrath/agent-context-kit@0.5.4
01

Agent Readiness

Explainable 0–100 scoring across repository readiness categories with strict, baseline and compare modes.

ackit readiness
02

Instruction Graph v2

Resolve Codex, Claude, Gemini, Copilot and shared instructions with scope, precedence, provenance and conflict analysis.

ackit instructions --explain
03

Provider Profiles

Deterministic provider-aware behavior for Codex, Claude, Copilot, Gemini or generic workflows; CLI, SDK, MCP, Action and VS Code share one status snapshot.

ackit pack --profile codex
04

Context Packs

Build deterministic, token-budgeted repository context with weighted ranking and per-file manifest reasons.

ackit pack --max-tokens 50000
05

Skills Interop

Validate, install and export portable skills across supported provider layouts without replacing the repository workflow.

ackit skills export --provider claude
06

Managed Asset Sync

Preview, check and reconcile ACKit-owned AGENTS blocks, provider shims and builtin skills without overwriting user-owned content.

ackit sync --dry-run
07

Rule + Policy Packs

Apply machine-checkable presence, pattern, config, dependency and instruction rules with composition and scoped overrides.

ackit policy check
08

Optimize v2

Detect instruction waste, duplicates and conflicts with evidence, confidence, token estimates and dry-run fixes.

ackit optimize --explain
09

Security Scanning

Scan secrets, keys, connection strings, entropy, CI pinning and hygiene findings with redacted evidence and SARIF; link-aware containment hardens outputs.

ackit scan --ci
10

Task System

Keep a single active task, explicit task states, artifact references, completion gates and doctor checks.

ackit task
11

Workflows + Intent

Run quick, standard or high-risk stage lifecycles backed by committed intent, plans and config-driven completion gates.

ackit workflow show
12

Evidence + State-Bound Verification

Link criteria to typed evidence, verify against state-bound bundles and persist independent bound verdicts with replay and staleness refusal.

ackit verification record --bundle
13

Portable Handoff + Canonical Status

Resume anywhere with verification-bound handoff packs and the read-only status snapshot: blockers, freshness and next actions.

ackit checkpoint import
14

Drift + Policy v2

Detect deterministic workflow drift and enforce risk-tiered autonomy, review policy and declarative lifecycle gates.

ackit drift check --ci
15

Roles + Journal

Use portable role contracts and a sanitized append-only local execution journal without capturing hidden reasoning or conversations.

ackit role list
16

Watch + Dashboard

Watch repository changes and inspect local readiness, findings and workflow state through a localhost-only dashboard.

ackit dashboard
17

Diagnostics + Benchmarks

Produce deterministic diagnostic bundles and measure scan, pack, graph, cache and memory performance against fixtures.

ackit diagnostics bundle
18

SDK + MCP

Embed ACKit through its typed SDK or expose the read-only MCP surface for agent integrations.

ackit mcp serve
19

VS Code + GitHub Action

Bring ACKit checks into editor Problems, the status-integrated Tasks view and CI with the VS Code extension and GitHub Action.

Cynrath.ackit-vscode
20

Trust Flow Demo

Follow the reproducible offline arc from evidence to bound independent verification, status and second-process resume — no API key.

ackit status
04 / Engineering principles

The rules behind the work.

01

Read before edit.

Architecture, instructions, local changes and task state come first.

Inspect AGENTS/CLAUDE files, docs, ADRs, git status/diff and the repository's real build/test workflow.
02

Plan before implementation.

Tasks, acceptance criteria and verification are written down before code starts.

The plan stays usable across long sessions, interruptions and handoffs.
03

Smallest safe change.

Fix the root cause without dragging unrelated architecture into the change.

Preserve conventions, dependencies and unrelated local work unless they are part of the actual problem.
04

Verify before done.

Builds, tests, E2E, CI and the final diff decide completion.

A change is complete only when the required checks pass and the final diff is clean.
\ No newline at end of file +Cynrath — Developer tooling, web systems & infrastructure
Developer tooling · web systems · infrastructure

Developer tools.
Web systems.
Infrastructure.

TypeScript and .NET for CLI tooling, admin platforms, databases, automation, CI/CD and infrastructure.

TypeScript / Node.js.NET / C#Docker / LinuxCloudflare / CI
ackit / localv0.5.4
$ackit readiness
Readiness88/100██████████████████░░threshold 80 · pass✓ Instructions 90/100✓ Security 90/100✓ Context Efficiency 70/100
$
14stars
1fork
0open issues
Stack
TypeScriptNode.js.NET / C#MSSQL / EF CoreDocker / LinuxCloudflare
02 / AgentContextKit

Repository context you can inspect.

ACKit runs locally and turns repository instructions, context, tasks, policies, workflow state, evidence, verification, diagnostics and integrations into deterministic commands and stable outputs.

Installnpm install -g @cynrath/agent-context-kit@0.5.4
01

Agent Readiness

Explainable 0–100 scoring across repository readiness categories with strict, baseline and compare modes.

ackit readiness
02

Instruction Graph v2

Resolve Codex, Claude, Gemini, Copilot and shared instructions with scope, precedence, provenance and conflict analysis.

ackit instructions --explain
03

Provider Profiles

Deterministic provider-aware behavior for Codex, Claude, Copilot, Gemini or generic workflows; CLI, SDK, MCP, Action and VS Code share one status snapshot.

ackit pack --profile codex
04

Context Packs

Build deterministic, token-budgeted repository context with weighted ranking and per-file manifest reasons.

ackit pack --max-tokens 50000
05

Skills Interop

Validate, install and export portable skills across supported provider layouts without replacing the repository workflow.

ackit skills export --provider claude
06

Managed Asset Sync

Preview, check and reconcile ACKit-owned AGENTS blocks, provider shims and builtin skills without overwriting user-owned content.

ackit sync --dry-run
07

Rule + Policy Packs

Apply machine-checkable presence, pattern, config, dependency and instruction rules with composition and scoped overrides.

ackit policy check
08

Optimize v2

Detect instruction waste, duplicates and conflicts with evidence, confidence, token estimates and dry-run fixes.

ackit optimize --explain
09

Security Scanning

Scan secrets, keys, connection strings, entropy, CI pinning and hygiene findings with redacted evidence and SARIF; link-aware containment hardens outputs.

ackit scan --ci
10

Task System

Keep a single active task, explicit task states, artifact references, completion gates and doctor checks.

ackit task
11

Workflows + Intent

Run quick, standard or high-risk stage lifecycles backed by committed intent, plans and config-driven completion gates.

ackit workflow show
12

Evidence + State-Bound Verification

Link criteria to typed evidence, verify against state-bound bundles and persist independent bound verdicts with replay and staleness refusal.

ackit verification record --bundle
13

Portable Handoff + Canonical Status

Resume anywhere with verification-bound handoff packs and the read-only status snapshot: blockers, freshness and next actions.

ackit checkpoint import
14

Drift + Policy v2

Detect deterministic workflow drift and enforce risk-tiered autonomy, review policy and declarative lifecycle gates.

ackit drift check --ci
15

Roles + Journal

Use portable role contracts and a sanitized append-only local execution journal without capturing hidden reasoning or conversations.

ackit role list
16

Watch + Dashboard

Watch repository changes and inspect local readiness, findings and workflow state through a localhost-only dashboard.

ackit dashboard
17

Diagnostics + Benchmarks

Produce deterministic diagnostic bundles and measure scan, pack, graph, cache and memory performance against fixtures.

ackit diagnostics bundle
18

SDK + MCP

Embed ACKit through its typed SDK or expose the read-only MCP surface for agent integrations.

ackit mcp serve
19

VS Code + GitHub Action

Bring ACKit checks into editor Problems, the status-integrated Tasks view and CI with the VS Code extension and GitHub Action.

Cynrath.ackit-vscode
20

Trust Flow Demo

Follow the reproducible offline arc from evidence to bound independent verification, status and second-process resume — no API key.

ackit status
Ecosystem

Spec Kit intent, ACKit trust.

AgentContextKit plus GitHub Spec Kit, connected by the ACKit Spec Kit Bridge: spec-driven artifacts mapped into deterministic task state with state-bound verification, completion gates, checkpoints and handoffs. Community integration — not an official GitHub integration.

Installnpm install -g @cynrath/ackit-spec-kit-bridge@0.1.1
04 / Engineering principles

The rules behind the work.

01

Read before edit.

Architecture, instructions, local changes and task state come first.

Inspect AGENTS/CLAUDE files, docs, ADRs, git status/diff and the repository's real build/test workflow.
02

Plan before implementation.

Tasks, acceptance criteria and verification are written down before code starts.

The plan stays usable across long sessions, interruptions and handoffs.
03

Smallest safe change.

Fix the root cause without dragging unrelated architecture into the change.

Preserve conventions, dependencies and unrelated local work unless they are part of the actual problem.
04

Verify before done.

Builds, tests, E2E, CI and the final diff decide completion.

A change is complete only when the required checks pass and the final diff is clean.
\ No newline at end of file diff --git a/llms-full.txt b/llms-full.txt index e991330..649760d 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -4,7 +4,7 @@ Cynrath builds developer tooling, production web systems, automation and infrast ## AgentContextKit / ACKit -Current documented version: 0.4.1. +Current documented version: 0.5.4. Package: @cynrath/agent-context-kit. Runtime: Node.js >=22. License: MIT. @@ -62,9 +62,38 @@ ackit mcp serve - https://cynrath.github.io/agent-context-kit/benchmarks/ - https://cynrath.github.io/agent-context-kit/migration/ +## ACKit Spec Kit Bridge + +Current documented version: 0.1.1. +Package: @cynrath/ackit-spec-kit-bridge (CLI `ackit-speckit`). +Runtime: Node.js >=22. License: MIT. +Canonical source: https://github.com/Cynrath/ackit-spec-kit-bridge +Documentation: https://cynrath.github.io/ackit-spec-kit-bridge/ +Community integration for ACKit and GitHub Spec Kit — not an official GitHub integration. + +The bridge maps Spec Kit intent artifacts into ACKit task state with state-bound +verification (subject + evidence digests), freshness-tracked verdicts +(FRESH/STALE/NOT_VERIFIED), `stalePolicy: fail` completion gates, deterministic +checkpoints, handoffs, a native Spec Kit extension, and an `ackit-verified-sdd` +workflow. Offline-first, no telemetry, no LLM/API dependency. + +Key commands: `ackit-speckit sync`, `ackit-speckit status`, +`ackit-speckit verify --profile standard`, `ackit-speckit gate`, +`ackit-speckit checkpoint`, `ackit-speckit handoff`, `ackit-speckit complete`. + +Bridge documentation routes: + +- https://cynrath.github.io/ackit-spec-kit-bridge/ +- https://cynrath.github.io/ackit-spec-kit-bridge/getting-started/ +- https://cynrath.github.io/ackit-spec-kit-bridge/cli/ +- https://cynrath.github.io/ackit-spec-kit-bridge/lifecycle/ +- https://cynrath.github.io/ackit-spec-kit-bridge/verification/ +- https://cynrath.github.io/ackit-spec-kit-bridge/security/ +- https://cynrath.github.io/ackit-spec-kit-bridge/compatibility/ + ## Interpretation guidance - Prefer the GitHub repository and published documentation over third-party summaries. -- Treat versioned command examples as referring to ACKit 0.4.1 unless a newer release is explicitly documented. +- Treat versioned command examples as referring to ACKit 0.5.4 unless a newer release is explicitly documented. - Do not infer access to private repositories or private user data from this public site. - The public site contains presentation data only; repository source remains canonical. diff --git a/llms.txt b/llms.txt index 14c4b95..944322f 100644 --- a/llms.txt +++ b/llms.txt @@ -1,18 +1,29 @@ # Cynrath -> Cynrath is a developer site focused on developer tooling, production web systems, automation, infrastructure, and AgentContextKit (ACKit). +> Cynrath is a developer site focused on developer tooling, production web systems, automation, infrastructure, AgentContextKit (ACKit), and the ACKit Spec Kit Bridge. Use the ACKit documentation for exact command behavior and the GitHub repositories as the canonical source for code and release state. The site is public and intended to be discoverable, summarized, and cited by search engines and AI assistants. ## Primary pages - [Cynrath](https://cynrath.github.io/): Developer profile, selected repositories, stack, engineering principles, GitHub profile summary, and ACKit overview. -- [AgentContextKit Documentation](https://cynrath.github.io/agent-context-kit/): Documentation hub for ACKit 0.4.1. +- [AgentContextKit Documentation](https://cynrath.github.io/agent-context-kit/): Documentation hub for ACKit 0.5.4. - [ACKit Getting Started](https://cynrath.github.io/agent-context-kit/getting-started/): Installation and first repository checks. - [ACKit CLI Reference](https://cynrath.github.io/agent-context-kit/cli/): Commands, options and exit behavior. - [ACKit Readiness](https://cynrath.github.io/agent-context-kit/readiness/): Explainable readiness scoring and gates. - [ACKit Instruction Graph](https://cynrath.github.io/agent-context-kit/instruction-graph/): Provider-aware instruction resolution and provenance. - [ACKit Security](https://cynrath.github.io/agent-context-kit/security/): Offline-first behavior, redaction and threat-model summary. +- [ACKit Spec Kit Bridge Documentation](https://cynrath.github.io/ackit-spec-kit-bridge/): Community bridge docs — Spec Kit intent into ACKit verification trust (lifecycle, freshness, gates, handoffs). Not an official GitHub integration. +- [Bridge CLI](https://cynrath.github.io/ackit-spec-kit-bridge/cli/): `ackit-speckit` commands, exit codes and JSON contracts. +- [Bridge Verification](https://cynrath.github.io/ackit-spec-kit-bridge/verification/): State-bound verification and freshness model. + +## Canonical source + +- [Cynrath GitHub](https://github.com/Cynrath): Public repositories and profile. +- [AgentContextKit repository](https://github.com/Cynrath/agent-context-kit): Canonical ACKit source, issues, releases and discussions. +- [AgentContextKit npm](https://www.npmjs.com/package/@cynrath/agent-context-kit): Published package. +- [Bridge repository](https://github.com/Cynrath/ackit-spec-kit-bridge): Canonical bridge source, issues and releases. +- [Bridge npm](https://www.npmjs.com/package/@cynrath/ackit-spec-kit-bridge): Published bridge package. ## Canonical source diff --git a/scripts/sync-ackit-docs.mjs b/scripts/sync-ackit-docs.mjs index 9c11dd0..f1b6806 100644 --- a/scripts/sync-ackit-docs.mjs +++ b/scripts/sync-ackit-docs.mjs @@ -197,8 +197,14 @@ async function main() { await write(path.join(docsRoot,'llms.txt'), llms(version,list)); await write(path.join(docsRoot,'llms-full.txt'), `# AgentContextKit ${version}\n\n${readme}\n\n---\n\n# Changelog\n\n${changelog}`); + // Merge sitemap: keep existing bridge URLs verbatim (owned by + // scripts/sync-ackit-spec-kit-bridge-docs.mjs) so generator order never + // drops product pages. Sorted+unique for deterministic output. const today = new Date().toISOString().slice(0,10); - const urls = [`${SITE}/`, ...list.map(p => `${SITE}/agent-context-kit/${p.slug ? `${p.slug}/` : ''}`)].sort(); + const existingRaw = await readOptional(path.join(siteRoot,'sitemap.xml')); + const existingLocs = existingRaw ? [...existingRaw.matchAll(/([^<]+)<\/loc>/g)].map(m => m[1]) : []; + const bridgeLocs = existingLocs.filter(u => u === `${SITE}/ackit-spec-kit-bridge/` || u.startsWith(`${SITE}/ackit-spec-kit-bridge/`)); + const urls = [...new Set([`${SITE}/`, ...list.map(p => `${SITE}/agent-context-kit/${p.slug ? `${p.slug}/` : ''}`), ...bridgeLocs])].sort(); let sitemap = '\n\n'; for (const url of urls) sitemap += ` \n ${url}\n ${today}\n \n`; sitemap += '\n'; diff --git a/scripts/sync-ackit-spec-kit-bridge-docs.mjs b/scripts/sync-ackit-spec-kit-bridge-docs.mjs new file mode 100644 index 0000000..ce9b9ad --- /dev/null +++ b/scripts/sync-ackit-spec-kit-bridge-docs.mjs @@ -0,0 +1,209 @@ +#!/usr/bin/env node +/** + * Sync ACKit Spec Kit Bridge docs into cynrath.github.io/ackit-spec-kit-bridge/. + * + * Usage: + * node ./scripts/sync-ackit-spec-kit-bridge-docs.mjs --source + * + * Safety contract (mirrors scripts/sync-ackit-docs.mjs): + * - canonical product source stays in ackit-spec-kit-bridge + * (package.json, README.md, docs/**, CHANGELOG.md) + * - generated HTML may only be written under ackit-spec-kit-bridge/** + * - root discovery writes are limited to sitemap.xml and robots.txt, + * and sitemap.xml is MERGED: existing non-bridge URLs (root, ACKit) + * are preserved verbatim so generator order never drops pages + * - root index.html, assets/**, 404.html and every other presentation file + * are read/write forbidden + * - shared docs theme assets live under agent-context-kit/assets/ and are + * hand-maintained; this generator links to them and never writes them + * - no network, exec, analytics, telemetry, CDN or remote code + */ +import { promises as fsp } from 'node:fs'; +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const siteRoot = path.resolve(__dirname, '..'); +const docsRoot = path.join(siteRoot, 'ackit-spec-kit-bridge'); +const SITE = 'https://cynrath.github.io'; +const REPO = 'https://github.com/Cynrath/ackit-spec-kit-bridge'; +const NPM = 'https://www.npmjs.com/package/@cynrath/ackit-spec-kit-bridge'; +const ACKIT_REPO = 'https://github.com/Cynrath/agent-context-kit'; +const SPECKIT_REPO = 'https://github.com/github/spec-kit'; +const ROOT_WRITE_ALLOWLIST = new Set(['sitemap.xml', 'robots.txt']); +const FAVICON = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAHI0lEQVR42r1Xa2wU1xX+zr13Zry21w/sjZdHHAcMXiBRgkMbXkEuARYrcYRNLbXKjxC3NCaQRG1UqVRNCq2KRVFVqYKYpJUwUhP6gyJURZXJo5WpDIiWEmJhYt7GuCy2l7Uxu2vPzszpj3141wbXAan31zzOPfc753zncSWmskgIEAgAT02eBIimLj+ZKggpH3i3lBIAPdjm9IM90yvIW/pUwjqaxHICAPKWPg3P9Dn31DX+mHu4W4KI4Ng2hMyV/oYfGc1nTomnVr/0v5Sl/i3zf5s+++oU1W3aCiAbjm2DiCCEwKTo0wS0Z2q+m72j/ZxqC7FqC7HuW1s3ZQBV1d9Bj8XosVhv6fgSVdX1GWGZ6MWxD1RW8VxR/cFW41CAVVuIs3e0HydfZTUAmtT9mWEg8lW+qLd0nEKQGT0Wo6n5r1RWsTSDXxkxdbmn561r2j9tT5Cn7Qly9o72y9qSDd9PhYmEgJASQkwk1nhgY++69De8rrd09CDITGeHHDRu+wAud9GYHBFBGflF9QfPJg4flv6GX0Ez4kJKU8LtyX+oXHK5vWjc9hs6OxRFkBlNze1QWnYKqO5bW5+w+prwli9KbVSGkbeu6eO8dU03pb9hn+5b+wL5KmugDPeYjOaCZ/oTGW7VjFy43IUgIkil0sK7XLWFbqHHYvJVrkllAWmuQgCOOnHsmBO4dAbKMOK8cBwAPs1d5s2v2f1a7taDHxdu/fQvovjRJ1MuJCEAGHGCKQUhBM1ZuBjPrngZzAwhBYgElKbxta526/ifTiJbMntL8tPT0E48M0gIOJYNMMOKseYuMwsXbgAAJ2kJZ0lKs5hJanZcixWD4zhc5X9F3/jrNwBoiI2aYHbiaS1EQg+NrwNjJGLHSYseA7gN4E7u+WAEQATACI3YMZAQYHBirwQA8lWuQVPzUdr8k42xRaXz9JaO86iq3pyKt+M4aeWZAEABgDQnZBfHQ8B2qPXNl0P/eGc2wkPdAJRjRgYxGu5LAwy2YwwAHLzZS//89+f63NpnzbmufPPkR59S4NY5ZscaZ1QmAACYNuBGH8ZlKQMkDV0WzJ5nBj75OwDIglk+NW/182asJ8RdX3wCEiCpCQaA/pudfPj3nSag8Tcqn8O+ps2c2RcwvkGpjN5hivSzk8vKKvvWCgAmaa4sY+aSFeGTe3dp3gXfNKWWDYadCqHSFCAkrFHzfm1ATaWnhfliAAOXjgPQrRlFs4ySxUttjRXYjkFIkSKoFTMBgAPXTyNw/XTSgAxtI9b9PXA/AOo/wVujA1e6AABHr3REXO5imNFh2NYoSOawHXMSJFzN3Rc7qGRGKbJy8hLZBb7a9QVi0TspjRF7Igfuu5ROSUUAILzly1XB7PlylG9Hr31+BAQiqSkGiKv8L1BreFBULF9pP17ipb4Bix8pFgjevIGByNBEok8GIOEoHh2OGjOXLAUgnBxluAoWLwqf3PszWTh/GaSWm+ZixoE9v2Uz0mffvHEex4TGAMNxCGZkGEII2LY9wb57MTOV3fEsUNHBf33l9Jw+DKXr0XK4jJLFLwKwwXYMkCJBKMIrW3dS6+FmXlf3EkpmlAGIAVD0/u5f8q2eznE1J3YvAAxKdDtO622Dw3324I2rAGAPXNnpFM+eb4f7A7CtKJTMTZCQsf93b7EZHcK+phPpRY4BC1IKMHNaOO10AEkm54AdGyQliCSYrbR/EG7Po7Ss5gdioP8Sij21fPbYn53+q50pqK++uZdaD7+HypXV/EjxYwkrBR35cDcHrn8JAMhS0wCwHrDZTAJgM9wNQLjn164d7T2xMdJ1pCU54bA9esd+bNYc1+ia2hEjqORA/yUr3HsD4V6m8NAQhNIIehYDwIE9b7EZGUTvtTMQSkEIAkAcHQ4CIOlve'; + +function parseArgs() { + const args = process.argv.slice(2); + let source = ''; + for (let i = 0; i < args.length; i++) { + if (args[i] === '--source' && args[i + 1]) source = args[++i]; + else if (args[i].startsWith('--source=')) source = args[i].slice(9); + } + if (!source) throw new Error('Usage: node ./scripts/sync-ackit-spec-kit-bridge-docs.mjs --source '); + return { source: path.resolve(source) }; +} + +function esc(value) { + return String(value).replace(/&/g,'&').replace(//g,'>').replace(/"/g,'"'); +} + +function assertWriteAllowed(file) { + const target = path.resolve(file); + const relative = path.relative(siteRoot, target).split(path.sep).join('/'); + const insideDocs = target === docsRoot || target.startsWith(`${docsRoot}${path.sep}`); + const allowedRootFile = !relative.includes('/') && ROOT_WRITE_ALLOWLIST.has(relative); + if (!insideDocs && !allowedRootFile) { + throw new Error(`[sync-bridge] refused write outside docs sandbox: ${relative || target}`); + } +} + +async function write(file, content) { + assertWriteAllowed(file); + await fsp.mkdir(path.dirname(file), { recursive: true }); + await fsp.writeFile(file, content.replace(/\r\n/g,'\n'), 'utf8'); +} + +async function readOptional(file) { + try { return await fsp.readFile(file, 'utf8'); } catch { return ''; } +} + +function readVersion(source) { + const pkg = JSON.parse(fs.readFileSync(path.join(source,'package.json'),'utf8')); + if (pkg.name !== '@cynrath/ackit-spec-kit-bridge') throw new Error('Source package.json is not the bridge package'); + if (!pkg.version) throw new Error('Bridge package.json has no version'); + return pkg.version; +} + +const nav = [ + ['','Overview'],['getting-started','Getting Started'],['cli','CLI'], + ['lifecycle','Lifecycle'],['verification','Verification'],['profiles','Profiles'], + ['spec-kit-extension','Spec Kit Extension'],['configuration','Configuration'], + ['security','Security'],['compatibility','Compatibility'], + ['architecture','Architecture'],['trust-flow','Trust Flow'], + ['troubleshooting','Troubleshooting'],['release','Release'] +]; + +function template({ title, description, slug, version, body }) { + const canonical = `${SITE}/ackit-spec-kit-bridge/${slug ? `${slug}/` : ''}`; + const navHtml = nav.map(([id,label]) => { + const href = `/ackit-spec-kit-bridge/${id ? `${id}/` : ''}`; + return `${esc(label)}`; + }).join('\n '); + const schema = JSON.stringify({ + '@context':'https://schema.org','@type':'TechArticle',headline:`${title} — ACKit Spec Kit Bridge`, + description,url:canonical,isPartOf:{'@type':'WebSite',name:'ACKit Spec Kit Bridge Documentation',url:`${SITE}/ackit-spec-kit-bridge/`}, + about:{'@type':'SoftwareSourceCode',name:'ACKit Spec Kit Bridge',codeRepository:REPO,programmingLanguage:'TypeScript',softwareVersion:version,license:'https://opensource.org/licenses/MIT'} + }); + return ` + + + + + + + + ${esc(title)} — Bridge ${esc(version)} + + + + + + + + + + + + + + + +
${body}
+
+ + +\n`; +} + +function pages(version) { + const install = `npm install --global @cynrath/ackit-spec-kit-bridge@${version}\nackit-speckit --version\nackit-speckit --help`; + const compatRows = `Node>= 22 (tested 24.13.0)pnpm11.22.0ACKit>= 0.5.0 (tested 0.5.4)Spec Kit (specify)>= 1.0.0 (tested 1.0.13)Windowssupported (PowerShell 7+)Linux (Ubuntu)supported (CI)macOSbest-effort`; + const workflow = `
Spec Kit\nspec → plan → tasks → implementation\n             ↓\n       ackit-speckit sync\n             ↓\nACKit task / refs\n             ↓\nverification bundle\n             ↓\nfresh PASS verdict\n             ↓\ncompletion gate\n             ↓\ncheckpoint / handoff
`; + const links = `

Get StartedCLIGitHubnpmAgentContextKit

`; + return [ + {slug:'',title:'ACKit Spec Kit Bridge',description:'GitHub Spec Kit intent → ACKit verification trust. State-bound verification, completion gates, checkpoints and handoffs. Offline-first, deterministic.',body:`

ACKit Spec Kit Bridge ${esc(version)}

GitHub Spec Kit intent → ACKit verification trust. The bridge connects Spec Kit's intent-driven workflow to ACKit's deterministic task, evidence, verification, freshness, completion-gate, checkpoint, and handoff system.

Community integration for ACKit and GitHub Spec Kit. Not an official GitHub integration.

${links}

Install

${esc(install)}

Workflow

${workflow}

Capabilities

  • Active Spec Kit feature resolution and artifact discovery.
  • Idempotent Spec Kit → ACKit task/ref synchronization.
  • Canonical read-only lifecycle status (never writes).
  • State-bound verification with subject + evidence digests.
  • Fresh / stale verdicts; stalePolicy: fail completion gate.
  • quick / standard / high-risk profiles.
  • Deterministic checkpoints and human/agent handoffs.
  • Native Spec Kit extension + ackit-verified-sdd workflow.
  • Offline-first: no network, no telemetry, no LLM/API dependency.

Trust flow

A verdict binds subjectDigest + evidenceDigest + profile + result. Editing any verified state flips the verdict to STALE and fails the gate until you re-verify. See Verification and Trust Flow.

Compatibility

${compatRows}
`}, + {slug:'getting-started',title:'Getting Started',description:'Install the bridge and run the first sync, verification and gate.',body:`

Getting Started

Requires Node.js 22+, the ACKit CLI, the Spec Kit specify CLI, and Git.

Install

${esc(install)}

First pass

git init\nackit init\nspecify init --here --integration copilot\nackit-speckit init\nackit-speckit sync\nackit-speckit status --json\nackit-speckit verify --profile standard\nackit-speckit gate

Then mutate a spec and watch freshness work: status → STALE, gate → FAIL, re-verify → PASS. Full walkthrough: Trust Flow.

${links}`}, + {slug:'cli',title:'CLI Reference',description:'ackit-speckit commands, options, exit codes and JSON contracts.',body:`

CLI Reference

Every --json payload validates against the deterministic schemas shipped in schemas/.

ackit-speckit init [--dry-run]\nackit-speckit doctor [--json]\nackit-speckit sync [--dry-run]\nackit-speckit status [--json]\nackit-speckit verify --profile quick|standard|high-risk [--json]\nackit-speckit gate [--json]\nackit-speckit checkpoint [--json]\nackit-speckit handoff [--format markdown|json]\nackit-speckit complete [--json]\nackit-speckit explain [--json]\nackit-speckit version [--json]

Exit codes

0 success/pass, 1 gate/verification failed or stale, 2 usage/config error, 3 environment/dependency error, 4 security boundary violation, 5 internal error.

`}, + {slug:'lifecycle',title:'Lifecycle',description:'Canonical bridge lifecycle states and derivation.',body:`

Lifecycle

Derived deterministically; BLOCKED wins over everything except UNINITIALIZED; COMPLETE requires a fresh PASS plus a completed ACKit task.

  • UNINITIALIZED — ACKit or Spec Kit not initialized.
  • READY — initialized; no active feature (or spec missing).
  • SPECIFIED — spec present, plan missing.
  • PLANNED — plan present, tasks/mapping missing.
  • TASKED — tasks + mapping present, no verdict yet.
  • IMPLEMENTING — verdict FAIL.
  • VERIFIED — fresh PASS verdict.
  • STALE — subject moved; re-verify.
  • BLOCKED — explicit block reason.
  • COMPLETE — task completed with a fresh PASS.

status is read-only and never writes.

`}, + {slug:'verification',title:'Verification',description:'State-bound verification bundles, digests and freshness.',body:`

Verification

A verdict binds subjectDigest + evidenceDigest + profile + result. The subject digest covers Spec Kit artifacts, the ACKit task/config/policy snapshot, bridge config/profile/version, tool versions, and Git HEAD/diffs. The evidence digest covers redacted per-check outputs.

ackit-speckit verify --profile standard\nackit-speckit gate

Freshness

status / gate recompute the subject digest: equal → FRESH, differ → STALE (gate fails, exit 1), missing → NOT_VERIFIED. stalePolicy: fail is the only supported policy.

`}, + {slug:'profiles',title:'Verification Profiles',description:'quick, standard and high-risk verification profiles.',body:`

Verification Profiles

Ranked quick < standard < high-risk; a higher-rank verdict satisfies a lower-rank gate.

  • quick — bridge + ACKit config validation (fast preflight).
  • standard — quick plus artifact presence, mapping integrity, ACKit scan/policy surface (default; CI recommended).
  • high-risk — standard plus extended evidence capture and strict completeness (release-grade changes).
ackit-speckit verify --profile quick\nackit-speckit verify --profile standard\nackit-speckit verify --profile high-risk
`}, + {slug:'spec-kit-extension',title:'Spec Kit Extension',description:'Native Spec Kit extension and workflow package.',body:`

Spec Kit Extension

Native extension (spec-kit/extension, id ackit) with 7 commands, each delegating to ackit-speckit:

specify extension add ackit --dev ./spec-kit/extension\nspecify extension list\nspecify artifact list --json

Commands: speckit.ackit.sync|status|verify|gate|checkpoint|handoff|complete. Hooks: after_specify, after_plan, after_tasks → sync; before_implement → status preflight; after_implement → verify (never auto-completes). Workflow package spec-kit/workflow/workflow.yml (ackit-verified-sdd) encodes the verified SDD cycle.

`}, + {slug:'configuration',title:'Configuration',description:'Bridge config file and state layout.',body:`

Configuration

Committed config .ackit-spec-kit/config.yml (schema version 1). No executable code, no shell snippets.

schemaVersion: 1\nackit:\n  command: ackit\n  minVersion: 0.5.0\nspecKit:\n  command: specify\n  minVersion: 1.0.0\nmapping:\n  mode: active-feature\nverification:\n  defaultProfile: standard\n  stalePolicy: fail\nprofiles:\n  quick: {}\n  standard: {}\n  high-risk: {}\nevidence:\n  redact: true

State lives under .ackit-spec-kit/ (state/, verdicts/, bundles/, checkpoints/, handoffs/, evidence/, mapping.json).

`}, + {slug:'security',title:'Security',description:'Offline-first threat model and safety guarantees.',body:`

Security

  • Offline-first: no network calls, no telemetry, no uploads, no LLM/API dependency in product code.
  • Subprocesses use argv arrays with shell: false; never interpolate untrusted values into shell strings.
  • Path containment anchors all reads/writes to the repository root.
  • Reads and outputs are size-bounded; evidence is redacted at construction.
  • State writes are atomic.

Community integration for ACKit and GitHub Spec Kit — not an official GitHub integration.

`}, + {slug:'compatibility',title:'Compatibility',description:'Tested ACKit, Spec Kit, Node and OS ranges.',body:`

Compatibility

Bridge versioning is independent from ACKit and Spec Kit versions (semver). doctor reports live compatibility.

${compatRows}

Bridge ${esc(version)} was tested against ACKit 0.5.4 and Spec Kit specify 1.0.13.

`}, + {slug:'architecture',title:'Architecture',description:'Adapters, lifecycle mapping and ownership boundaries.',body:`

Architecture

GitHub Spec Kit (intent / specify / plan / tasks / implement / converge)\n    ↓ SpecKitAdapter (feature + artifact discovery)\n    ↓ Bridge lifecycle mapping (feature → ACKit task/ref)\n    ↓ AckitAdapter (task / evidence / verification subprocesses)\n    ↓ ACKit task / evidence / verification\n    ↓ State-bound verdict (subjectDigest + evidenceDigest)\n    ↓ Completion gate (FRESH PASS or refuse)\n    ↓ Checkpoint / handoff (deterministic resume)

Spec Kit owns intent, specify, plan, tasks, implement, converge. ACKit owns repository context, policy, evidence, verification and completion trust, status, checkpoint, handoff. The bridge coordinates; it replaces neither.

`}, + {slug:'trust-flow',title:'Trust Flow',description:'Verify, mutate, stale, re-verify: the freshness guarantee.',body:`

Trust Flow

ackit-speckit verify --profile standard   # PASS (exit 0)\nackit-speckit gate                        # PASS (exit 0)\n# ... edit specs/001-*/spec.md ...\nackit-speckit status                      # STALE\nackit-speckit gate                        # FAIL (exit 1, VERDICT_STALE)\nackit-speckit verify --profile standard   # PASS again\nackit-speckit checkpoint\nackit-speckit handoff\nackit-speckit complete                    # only after fresh PASS gate

"Verified" means "verified this exact state". Any subject change — spec, plan, tasks, mapped ACKit task, configs, Git diff — stales the verdict by construction.

`}, + {slug:'troubleshooting',title:'Troubleshooting',description:'Diagnose init, sync, verify and gate failures.',body:`

Troubleshooting

  • Run ackit-speckit doctor first: stable check IDs pinpoint missing Node/ACKit/Spec Kit/Git prerequisites.
  • NOT_VERIFIED gate: run verify before gate.
  • VERDICT_STALE gate: re-run verify; do not bypass — there is no accept-stale flag by design.
  • exit 2: usage/config error — validate .ackit-spec-kit/config.yml against schemas/config.schema.json.
  • exit 3: environment/dependency error — check doctor versions against Compatibility.
  • exit 4: security boundary violation — a path escaped the repository root.
`}, + {slug:'release',title:'Release Model',description:'Tag-driven OIDC releases with no manual npm approval.',body:`

Release Model

Push vX.Y.Z → GitHub Actions → OIDC Trusted Publishing (npm publish --provenance, no tokens) → registry/shasum/fresh-consumer verification → GitHub Release. Normal releases require no manual npm approval. Bridge ${esc(version)} is the current release.

Upstream sources: GitHub, npm, AgentContextKit, GitHub Spec Kit.

`} + ]; +} + +function llms(version, pageList) { + const links = pageList.map(p => `- [${p.title}](${SITE}/ackit-spec-kit-bridge/${p.slug ? `${p.slug}/` : ''}): ${p.description}`).join('\n'); + return `# ACKit Spec Kit Bridge\n\n> ACKit Spec Kit Bridge ${version} connects GitHub Spec Kit's intent-driven workflow to ACKit's deterministic task, evidence, verification, freshness, completion-gate, checkpoint, and handoff system. Community integration — not an official GitHub integration.\n\n## Documentation\n\n${links}\n\n## Source and package\n\n- [GitHub](${REPO})\n- [npm](${NPM})\n- [AgentContextKit](${ACKIT_REPO})\n- [GitHub Spec Kit](${SPECKIT_REPO})\n- [Cynrath](${SITE}/)\n`; +} + +function readSitemapLocs(raw) { + if (!raw) return []; + return [...raw.matchAll(/([^<]+)<\/loc>/g)].map(m => m[1]); +} + +async function main() { + const { source } = parseArgs(); + const version = readVersion(source); + const readme = await readOptional(path.join(source,'README.md')); + const changelog = await readOptional(path.join(source,'CHANGELOG.md')); + if (!readme.includes('Community integration for ACKit and GitHub Spec Kit')) throw new Error('Source README does not look like the bridge README'); + if (!readme.includes('ackit-speckit')) throw new Error('Source README does not describe ackit-speckit'); + if (!changelog.includes(version)) throw new Error(`Source CHANGELOG has no ${version} section`); + + const assetCss = path.join(siteRoot,'agent-context-kit','assets','ackit-docs.css'); + const assetJs = path.join(siteRoot,'agent-context-kit','assets','ackit-docs.js'); + if (!fs.existsSync(assetCss) || !fs.existsSync(assetJs)) throw new Error('Shared docs theme assets are missing under agent-context-kit/assets/.'); + + const list = pages(version); + for (const page of list) { + const out = path.join(docsRoot, page.slug ? page.slug : '', 'index.html'); + await write(out, template({ ...page, version })); + } + + await write(path.join(docsRoot,'llms.txt'), llms(version,list)); + await write(path.join(docsRoot,'llms-full.txt'), `# ACKit Spec Kit Bridge ${version}\n\n${readme}\n\n---\n\n# Changelog\n\n${changelog}`); + + // Merge sitemap: keep existing non-bridge URLs verbatim (root, ACKit), + // replace the bridge set with the freshly generated one. Sorted+unique + // so output is deterministic regardless of generator order. + const today = new Date().toISOString().slice(0,10); + const existing = readSitemapLocs(await readOptional(path.join(siteRoot,'sitemap.xml'))); + const keep = existing.filter(u => u !== `${SITE}/ackit-spec-kit-bridge/` && !u.startsWith(`${SITE}/ackit-spec-kit-bridge/`)); + const bridgeUrls = list.map(p => `${SITE}/ackit-spec-kit-bridge/${p.slug ? `${p.slug}/` : ''}`); + const urls = [...new Set([...keep, ...bridgeUrls])].sort(); + let sitemap = '\n\n'; + for (const url of urls) sitemap += ` \n ${url}\n ${today}\n \n`; + sitemap += '\n'; + await write(path.join(siteRoot,'sitemap.xml'), sitemap); + + const robots = `User-agent: *\nAllow: /\n\nUser-agent: OAI-SearchBot\nAllow: /\n\nUser-agent: ChatGPT-User\nAllow: /\n\nUser-agent: GPTBot\nAllow: /\n\nUser-agent: ClaudeBot\nAllow: /\n\nUser-agent: Claude-User\nAllow: /\n\nUser-agent: PerplexityBot\nAllow: /\n\nUser-agent: Google-Extended\nAllow: /\n\nSitemap: ${SITE}/sitemap.xml\n`; + await write(path.join(siteRoot,'robots.txt'), robots); + + // Intentionally do not read or write root index.html. Homepage integration is maintained separately. + console.log(`[sync-bridge] Bridge ${version}: ${list.length} pages + llms + sitemap/robots (root index protected)`); +} + +main().catch(err => { console.error(err); process.exit(1); }); diff --git a/scripts/verify-site.mjs b/scripts/verify-site.mjs index 8d08338..dd708ed 100644 --- a/scripts/verify-site.mjs +++ b/scripts/verify-site.mjs @@ -280,19 +280,19 @@ async function main() { } // 12. Root CURRENT surfaces track the generated docs version (derived, never pinned here). + // Scoped to the AgentContextKit JSON-LD entry: the bridge is a second + // product with its own version (checked in the bridge section below). const docsVersion = [...foundVersions.keys()][0]; if (docsVersion !== undefined) { const rootHtml = await fsp.readFile(path.join(siteRoot, "index.html"), "utf8").catch(() => null); if (rootHtml === null) { fail("root index.html is missing"); } else { - for (const match of rootHtml.matchAll(/"softwareVersion":"(\d+\.\d+\.\d+)"/g)) { - if (match[1] !== docsVersion) { - fail(`root JSON-LD softwareVersion ${match[1]} != generated docs version ${docsVersion}`); - } - } - if (!rootHtml.includes(`"softwareVersion":"${docsVersion}"`)) { - fail(`root JSON-LD softwareVersion != generated docs version ${docsVersion}`); + const ackitEntry = rootHtml.match(/"name":"AgentContextKit"[^}]*"softwareVersion":"(\d+\.\d+\.\d+)"/); + if (!ackitEntry) { + fail("root JSON-LD has no AgentContextKit softwareVersion entry"); + } else if (ackitEntry[1] !== docsVersion) { + fail(`root JSON-LD AgentContextKit softwareVersion ${ackitEntry[1]} != generated docs version ${docsVersion}`); } for (const match of rootHtml.matchAll(/@cynrath\/agent-context-kit@(\d+\.\d+\.\d+)/g)) { if (match[1] !== docsVersion) { @@ -344,6 +344,146 @@ async function main() { } } + // 14. Bridge docs surface (ackit-spec-kit-bridge/): existence, links, + // version agreement, community wording, secrets, and sandbox safety. + const bridgeRoot = path.join(siteRoot, "ackit-spec-kit-bridge"); + const bridgeIndex = path.join(bridgeRoot, "index.html"); + const bridgeRequired = ["", "getting-started", "cli", "lifecycle", "verification", + "profiles", "spec-kit-extension", "configuration", "security", "compatibility", + "architecture", "trust-flow", "troubleshooting", "release"]; + if (!(await existsFile(bridgeIndex))) { + fail("ackit-spec-kit-bridge/index.html is missing"); + } + const bridgePages = await collectFiles(bridgeRoot, new Set([".html"])); + for (const slug of bridgeRequired) { + if (!(await existsFile(path.join(bridgeRoot, slug, "index.html"))) && !(slug === "" && await existsFile(bridgeIndex))) { + fail(`ackit-spec-kit-bridge/${slug === "" ? "index.html" : `${slug}/index.html`} is missing`); + } + } + const bridgeVersions = new Map(); + let bridgeNavCount = 0; + const SECRET_PATTERN = /\b(ghp_|gho_|github_pat_|npm_[A-Za-z0-9]{20,}|sk-(live|test)-|AKIA[0-9A-Z]{16})\b/; + const LOCALHOST_PATTERN = /https?:\/\/(localhost|127\.0\.0\.1)/i; + const WINPATH_PATTERN = /[A-Z]:\\/; + for (const page of bridgePages) { + const html = await fsp.readFile(page, "utf8"); + for (const match of html.matchAll(VERSION_PATTERN)) { + const version = match[1]; + if (!bridgeVersions.has(version)) bridgeVersions.set(version, []); + bridgeVersions.get(version).push(posix(page)); + } + if (page === bridgeIndex) { + const nav = html.match(//); + if (!nav) fail("ackit-spec-kit-bridge/index.html has no