@afokapu/atdd-bun 0.2.0 → 0.3.1

package/README.md

@@ -5,8 +5,8 @@ that keep their plan, acceptance evidence, tests, and implementation in the
 same Git history. It gives developers and coding agents fast local feedback,
 then runs the same checks in GitHub Actions.
 
-It does not require Python, the `atdd` executable, an ATdd state store, a
-global installation, or network access while enforcing a repository.
+It runs entirely on Bun from the repository's own `node_modules`: no global
+installation and no network access while enforcing a repository.
 
 ## What it protects
 
@@ -42,13 +42,25 @@ not the only thing standing between an invalid branch and `main`.
 
 ## Install and first use
 
-When the package is published to the configured package registry, add it as a
-development dependency:
+Add the package from npm as a development dependency, then bootstrap the
+repository once:
 
 ```sh
 bun add -d @afokapu/atdd-bun
+bun run atdd-bun init
 ```
 
+`init` installs the local surfaces described below: Git
+[hooks](#hooks-fast-feedback-not-merge-authority), the
+[CI workflow](#ci-the-merge-gate), the
+[agent skill](#agent-skill-the-lifecycle-in-the-agents-context), and the
+[integrity test](#integrity-files-agents-must-not-change). Commit what it
+generates (`.githooks/`, `.github/workflows/atdd-bun.yml`, `.agents/`, `.claude/`,
+`AGENTS.md`, `atdd-bun.integrity.test.ts`) so every clone and every agent session
+gets them. To keep the
+package and the skill current automatically, see
+[Staying up to date](#staying-up-to-date).
+
 Run the complete installed policy from the repository root:
 
 ```sh
@@ -163,15 +175,17 @@ bun run atdd-bun init
 It creates `.githooks/` dispatchers, sets a worktree-local `core.hooksPath`,
 generates `.github/workflows/atdd-bun.yml`, and installs the coding-agent skill
 when they are absent. It never overwrites another hook path, an existing
-generated workflow, or an existing skill unless you explicitly pass `--replace`. Installing the dependency alone deliberately does
-neither: package installation must not mutate a repository through postinstall.
+generated workflow, or an existing skill unless you explicitly pass `--replace`.
+The package itself has no install script: adding the dependency never changes
+the repository until you run `init`.
 
-Use `hooks install`, `ci init`, or `agent init` when only one surface is wanted:
+Use `hooks install`, `ci init`, `agent init`, or `integrity init` when only one surface is wanted:
 
 ```sh
 bun run atdd-bun hooks install
 bun run atdd-bun ci init
 bun run atdd-bun agent init
+bun run atdd-bun integrity init
 ```
 
 The hooks enforce protected-branch blocking, micro-commit limits, mass-delete
@@ -227,8 +241,34 @@ The skill names the lifecycle PLAN → RED → GREEN → SMOKE → REFACTOR →
 conventions each stage follows, and the `atdd-bun` profile that gates it. It
 points at the conventions shipped in this package instead of restating them, so
 it stays correct as they change; after upgrading, refresh it with
-`bun run atdd-bun agent init --replace`. The skill steers the agent; the
-profiles, hooks, and CI remain the enforcement.
+`bun run atdd-bun agent init --replace`, or let the repository's own
+`postinstall` do it (see [Staying up to date](#staying-up-to-date)). The skill
+steers the agent; the profiles, hooks, and CI remain the enforcement.
+
+## Integrity: files agents must not change
+
+Coding agents can edit anything on the machine they run on, including
+`node_modules/@afokapu/atdd-bun`, the files this package generates, and
+`atdd-bun.yaml`. `init` therefore writes `atdd-bun.integrity.test.ts` (into the
+`[test] root` from `bunfig.toml`, if one is set), and the generated CI workflow
+runs `bun run atdd-bun integrity` before enforcement. Both run the same check:
+
+| Checked | Canonical source | Restore |
+|---|---|---|
+| Every file of the installed package | `integrity.json`, the hashes published with the package | `bun install --force` |
+| The dependency is an npm version range, locked to the registry with an integrity hash | npm | `bun add -d @afokapu/atdd-bun` |
+| The CI workflow, both skills, the `AGENTS.md` block, and the integrity test | what the installed version generates (its version stamp is ignored) | `bun run atdd-bun init --replace` |
+| `atdd-bun.yaml` is not looser than on the branch being merged into | the merge base; for a push to the base branch, the previous commit | `git checkout <base> -- atdd-bun.yaml` |
+
+A failure is addressed to the agent: it lists every changed file with its
+restore command and tells it to stop and ask a human instead of working around
+the check. Locally, this is a reminder an agent can still ignore, because
+anything on its machine can be edited. In CI the check runs on a clean install,
+so its verdict cannot be faked. Loosening the policy remains possible, as a
+separate change a human approves.
+
+After upgrading to a version that changes generated files, run
+`bun run atdd-bun init --replace` and commit the result.
 
 ## CI: the merge gate
 
@@ -248,6 +288,47 @@ After generating it, configure the GitHub branch ruleset to require the workflow
 job before merging. `merge_group` is included so the same protection works with
 GitHub Merge Queue.
 
+## Staying up to date
+
+Every change merged into this package's `main` is published to npm
+automatically as the next patch version, with provenance, and tagged `vX.Y.Z`.
+
+The hooks and the CI workflow run the package installed in `node_modules`, so
+conventions, validators, and hook policy change as soon as a repository
+upgrades the dependency; nothing needs reinstalling. The generated files are
+copies: when an upgrade changes them, the integrity check reports them until you
+run `bun run atdd-bun init --replace` and commit the result. The agent skill is
+the one refreshed automatically. To refresh it on every install, add a script to the
+repository's own `package.json` (Bun runs a project's own lifecycle scripts, not
+a dependency's):
+
+```json
+"scripts": {
+  "postinstall": "atdd-bun agent init --replace"
+}
+```
+
+To receive each release as a pull request, add `.github/dependabot.yml` on the
+default branch:
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "bun"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    allow:
+      - dependency-name: "@afokapu/atdd-bun"
+```
+
+Merging that pull request installs the new version and, through `postinstall`,
+rewrites the skill. Without Dependabot, upgrade with
+`bun update @afokapu/atdd-bun`. The lockfile pins the installed version, so
+nothing changes until one of these runs. While the package is `0.x`, a `^0.1.x`
+range accepts only `0.1.*`; move to a new minor with
+`bun add -d @afokapu/atdd-bun@latest`.
+
 ## Linked worktrees for agent work
 
 An optional policy reserves one primary checkout for `main` and requires feature
@@ -314,12 +395,6 @@ publish using its own credentials and registry configuration.
 
 `bun test` runs the package’s real-Git fixtures and detector clean/dirty corpora.
 The suite proves that every declared convention output has a matching convention
-and a deliberate failing case; it also covers hook isolation, CI generation,
-planner scope, release validation, and linked-worktree policy.
-
-## Boundaries
-
-This package intentionally excludes ATdd’s Python runtime orchestration,
-registry/state reconciliation, GitHub API integration, cluster access, and
-deployment execution. Those capabilities may be configured around the package,
-but repository enforcement remains deterministic and locally runnable.
+and a deliberate failing case; it also covers hook isolation, the declarative
+registry policy, CI generation, agent-skill installation, planner scope, release
+validation, and linked-worktree policy.