diff --git a/CHANGELOG.md b/CHANGELOG.md index 81f7372..42b9af3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,11 @@ This project follows Semantic Versioning. 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 diff --git a/docs/guides/spec-kit-bridge.md b/docs/guides/spec-kit-bridge.md index eeaff99..fc4ccbb 100644 --- a/docs/guides/spec-kit-bridge.md +++ b/docs/guides/spec-kit-bridge.md @@ -1,17 +1,30 @@ # Spec Kit bridge -[GitHub Spec Kit](https://github.com/github/spec-kit) owns intent, -specification, planning, and task decomposition. ACKit owns deterministic -execution context, task state, evidence, verification, and completion trust. -The community bridge connects the two without forking either side: +Community integration for ACKit and GitHub Spec Kit — not an official +GitHub integration. -- **Bridge:** [`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge) - (CLI `ackit-speckit`) — community integration, MIT licensed. +- **Bridge repo:** [Cynrath/ackit-spec-kit-bridge](https://github.com/Cynrath/ackit-spec-kit-bridge) + (CLI `ackit-speckit`, MIT licensed) +- **npm:** [`@cynrath/ackit-spec-kit-bridge`](https://www.npmjs.com/package/@cynrath/ackit-spec-kit-bridge) +- **Hosted docs:** [cynrath.github.io/ackit-spec-kit-bridge](https://cynrath.github.io/ackit-spec-kit-bridge/) - **Positioning:** ACKit Spec Kit Bridge connects GitHub Spec Kit's intent-driven development artifacts to ACKit's deterministic repository context, task lifecycle, evidence, verification, and completion gates. - **Runtime:** offline-first, no cloud APIs, no LLM API, no telemetry. +## What each side owns + +- **Spec Kit owns:** intent, `specify` / `plan` / `tasks` / `implement`, + converge — artifacts under `specs/NNN-name/`. +- **ACKit owns:** deterministic execution context, task state, evidence, + verification, completion trust, status, checkpoints, handoffs. +- **The bridge does:** discover the active Spec Kit feature, synchronize it + into an ACKit task with explicit refs (`sync`, idempotent), run + state-bound verification (`verify`), refuse completion on stale state + (`gate`), and export deterministic resume context (`checkpoint`, + `handoff`). It replaces neither side and introduces no ACKit-core + dependency on the bridge. + ## Lifecycle ```text @@ -35,15 +48,23 @@ ackit-speckit verify --profile standard ackit-speckit gate ``` -A verdict binds the exact verified state: editing the spec, plan, tasks, the -mapped ACKit task, configs, or the Git diff makes it `STALE` and fails the -gate until you re-verify. The bridge also ships a native Spec Kit extension -(`speckit.ackit.*` commands + hooks) and an `ackit-verified-sdd` workflow; -see the [bridge README](https://github.com/Cynrath/ackit-spec-kit-bridge#readme) -and its `docs/` for the full contract. +## Freshness model + +A verdict binds `subjectDigest + evidenceDigest + profile + result`. The +subject digest covers Spec Kit artifacts, the mapped ACKit task/config/ +policy, bridge config/profile/version, tool versions, and Git HEAD/diffs. +Editing any of them makes the verdict `STALE` and fails the gate +(`stalePolicy: fail`, exit 1) until you re-verify. Profiles rank +`quick < standard < high-risk`; higher satisfies lower. ## Which ACKit surfaces the bridge uses `config check`, `scan --ci`, `readiness`, `instructions`, `optimize`, `pack`, `skills validate`, `task`, `policy check`, `diagnostics` — composed as subprocess checks with redacted evidence, never reimplemented. + +The bridge also ships a native Spec Kit extension (`speckit.ackit.*` +commands + hooks) and an `ackit-verified-sdd` workflow; see the +[bridge README](https://github.com/Cynrath/ackit-spec-kit-bridge#readme), +the [hosted bridge docs](https://cynrath.github.io/ackit-spec-kit-bridge/), +and the bridge `docs/` for the full contract. diff --git a/docs/tasks/active/TASK-0096-bridge-0-1-1-ecosystem-cross-links.md b/docs/tasks/active/TASK-0096-bridge-0-1-1-ecosystem-cross-links.md new file mode 100644 index 0000000..b6969bc --- /dev/null +++ b/docs/tasks/active/TASK-0096-bridge-0-1-1-ecosystem-cross-links.md @@ -0,0 +1,63 @@ +--- +id: "TASK-0096" +title: "Bridge 0.1.1 ecosystem cross-links" +status: active +schemaVersion: 2 +dependencies: [] +createdAt: "2026-10-02" +completedAt: null +--- + +## Purpose + +Point ACKit docs at the bridge 0.1.1 public surface (hosted docs, npm, +repo) with explicit ownership boundaries and community wording. No ACKit +core dependency on the bridge. + +## Scope + +- docs/guides/spec-kit-bridge.md: ownership section, freshness model, + hosted-docs/npm/repo links, explicit non-official-GitHub wording. +- CHANGELOG.md Unreleased: cross-link entry. + +## Out of scope + +- ACKit runtime, CLI, schemas, or release automation changes. +- Duplicating bridge CLI docs inside ACKit. + +## Affected files + +- docs/guides/spec-kit-bridge.md +- CHANGELOG.md + +## Required tests + +- node scripts/check-text-hygiene.mjs (changed docs) +- git diff --check +- ackit task/scan surface as applicable (docs-only) + +## Acceptance criteria + +- [x] Guide states what Spec Kit / ACKit / bridge each own. +- [x] Guide links hosted bridge docs, npm, repo; community wording explicit. +- [x] No bridge core dependency introduced. +- [x] Hygiene + diff-check clean. +- [ ] PR merged with green CI. + +## Test steps + +1. `node scripts/check-text-hygiene.mjs docs/guides/spec-kit-bridge.md` — clean. +2. `git diff --check` — clean. + +## Risks + +- Hosted bridge docs URL not live until Pages task lands; link is + forward-correct and verified post-deploy. + +## Rollback plan + +Focused commit revert. + +## Completion notes + +Implementation done; pending PR/CI/merge.