@afokapu/atdd-bun 0.6.1 → 0.7.0

package/README.md

@@ -1,537 +1,142 @@
 # `@afokapu/atdd-bun`
 
-`@afokapu/atdd-bun` is a Bun-native ATDD enforcement package for repositories
-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 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
-
-The package is an enforcer, not a planner or deployment platform. It checks the
-relationships that a plan makes explicit:
+Bun-native ATDD enforcement for repositories that keep their plan, acceptances, tests and
+implementation in one Git history. It checks the links a plan makes explicit:
 
 ```text
 plan / WMBT → acceptance → Bun test → implementation
 ```
 
-Depending on the selected profile, it also checks the Bun code/test convention
-corpus, documentation policy, plan integrity, scoped planner validation, and
-interlocking rules.
-
-It deliberately does **not** claim that static links prove a test is
-semantically adequate. Where the package can establish only a structural link,
-its report says so. Deployment execution, cloud credentials, and release
-publishing remain repository-owned.
-
-## How a repository uses it
-
-A repository normally uses the package in three places:
-
-1. A local Bun test or command gives immediate feedback while work is underway.
-2. Git hooks prevent clearly invalid commits and pushes; they are convenience,
-   not merge authority.
-3. GitHub Actions runs the full policy. Protect the resulting required check in
-   the repository’s GitHub branch ruleset.
+It runs on Bun from the repository's own `node_modules`, with no global install and no network
+access. The same checks run as local tests, as Git hooks for fast feedback, and in GitHub Actions,
+which is the merge gate. Every finding fails: there is no advisory mode and no ratchet baseline.
 
-The practical result is that an agent cannot quietly add production code without
-the plan/test links the repository has chosen to require, and a local hook is
-not the only thing standing between an invalid branch and `main`.
-
-## Install and first use
-
-Add the package from npm as a development dependency, then bootstrap the
-repository once:
+## Install
 
 ```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).
+`init` installs the Git hooks (`.githooks/`), the CI workflow (`.github/workflows/atdd-bun.yml`),
+the agent skill (`.agents/skills/atdd/`, `.claude/skills/atdd/`), a managed block in `AGENTS.md`
+and `CLAUDE.md`, and `atdd-bun.integrity.test.ts`. Commit all of them. Nothing is overwritten
+without `--replace`, and adding the dependency changes nothing until you run `init`.
 
-Run the complete installed policy from the repository root:
+Then require the workflow's job in the GitHub branch ruleset, so it gates merges.
 
-```sh
-bun run atdd-bun all
-```
+## Commands
 
-`all` runs every enabled packaged detector. It is the command that CI uses for
-the local enforcement portion of its check. Run a focused profile directly—for
-example, `bun run atdd-bun planner` or `bun run atdd-bun traceability`—without
-an extra `profile` verb. `--profile <name>` remains available for compatibility.
-
-For a focused local test, register only the policy that matters to that test:
+| Command | What it does |
+|---|---|
+| `atdd-bun [profile ...] [--root <path>]` | Enforce the named profiles; `all` (the default) runs every activated one |
+| `atdd-bun init [--replace]` | Install hooks, CI, agent files and the integrity test |
+| `atdd-bun hooks <install\|uninstall\|status>` | Manage only the Git hooks |
+| `atdd-bun ci <init\|status>` | Manage only the CI workflow |
+| `atdd-bun agent <init\|status>` | Manage only the skills and the `AGENTS.md`/`CLAUDE.md` block |
+| `atdd-bun integrity [init\|status]` | Check that the toolkit and its generated files are unmodified |
+| `atdd-bun docs journeys [--check]` | Generate (or verify) the journey, interlocking and train views |
+| `atdd-bun worktree <start\|finish\|status>` | Optional linked-worktree policy for agent work |
+| `atdd-bun release check` | Read-only SemVer and release-intent check |
+| `atdd-bun help [--json]` | Every command and profile, human- or agent-readable |
+
+Run them with `bun run atdd-bun …`. To make a single Bun test fail on broken closure:
 
 ```ts
 import { registerEnforcementTest } from "@afokapu/atdd-bun/register";
-
-registerEnforcementTest({
-  root: import.meta.dir + "/..",
-  profiles: ["traceability"],
-});
+registerEnforcementTest({ root: import.meta.dir + "/..", profiles: ["traceability"] });
 ```
 
-This makes a Bun test fail when plan → acceptance → test → implementation
-closure is broken, without enabling unrelated code-quality profiles.
+## Profiles
 
-## Choose the enforcement scope
+| Profile | Checks |
+|---|---|
+| `traceability` | acceptance → Bun test → source closure: every acceptance tested, every binding and `Tested-By` resolving |
+| `topology` | feature decomposition and the plan, source, test and E2E locations |
+| `planner` | schemas for every plan artifact, graph integrity, the scoped planner rules |
+| `telemetry` | the telemetry tracking plan: item shape, path-mirrored identity and versioning under `telemetry/`, wagon ownership of logical artifacts, the per-acceptance telemetry decision, metric label cardinality, source `Telemetry:` references, raw-string and forbidden-property emission, the vendor-SDK boundary around the TelemetryPort, and telemetry tests that bind the acceptance and item, assert the exact identity on a captured sink, cover every required item, and exercise declared timing semantics |
+| `docs` | the documentation capability, including the generated journey view |
+| `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions |
+| `interlocking` | train/interlocking binding, infrastructure and route coverage |
+| `htmx` | htmx source/test conventions and Playwright browser specs (`*.e2e.ts`) |
+| `design` | design-system layering, token-only styling and responsiveness |
+| `all` | every activated profile; what the hooks and CI run |
 
-Run `bun run atdd-bun help` to see the complete command list, or
-`bun run atdd-bun help --json` for an agent-readable command/profile inventory.
+`planner-nodes/ENFORCEMENT_SCOPE.yaml` says which canonical planner rules have a Bun realization.
 
-Profiles describe *what is being checked*, rather than a technical detector
-name.
+## Greenfield and brownfield
 
-| Profile | Use it when you need to check |
-|---|---|
-| `traceability` | plan acceptance, Bun test, and implementation closure |
-| `topology` | feature decomposition and canonical plan, source, test, and E2E locations |
-| `planner` | plan parsing/graph integrity plus the explicitly scoped planner rules |
-| `docs` | the optional documentation capability and its declared artifacts, including the generated journey view |
-| `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions for that concern |
-| `interlocking` | declared train/interlocking binding, infrastructure, and coverage |
-| `htmx` | htmx-specific source and test conventions, including browser specs |
-| `design` | the design system (tokens ← primitives ← components ← templates, token-only colors, spacing, radii, motion) and responsiveness (also part of `coder`) |
-| `all` | the complete package policy, normally used by CI |
-
-The package ships the canonical planner-node corpus as planning reference, but
-does not pretend that every node is executable. The
-[planner enforcement scope](planner-nodes/ENFORCEMENT_SCOPE.yaml) identifies
-which rules have a Bun realization, which predicates are only partial, and which
-nodes are reference-only.
-
-The planner profile first validates recognized plan artifacts against the
-package-shipped JSON Schemas—wagon, feature, WMBT (including embedded
-acceptances), train, train interlocking, and journey topology. It then runs
-cross-artifact validators such as registry coherence, traceability, and
-cross-interlocking continuation closure. A journey starts at one interlocking;
-each reachable route must either terminate explicitly or continue, through an
-artifact produced by that route's selected train, to another interlocking. Exposed journeys also
-carry Station Master actions; the Bun interlocking family checks those actions resolve through
-`JOURNEY_MAP` to `JourneyRunner`, while internal journeys carry no public reachability obligation.
-Hooks, direct CLI use, and CI invoke this same profile and therefore share the
-same schema source.
-
-### Repository topology
-
-The topology gate makes a feature a required plan artifact instead of an
-optional label on a WMBT. Its default layout is:
+A greenfield repository enforces every profile from the start: that is the default. A brownfield
+(legacy) repository can adopt enforcement gradually. The operator lists the profiles it is ready
+for, and adds more as the code catches up:
 
-```text
-plan/<wagon>/{_<wagon>,<feature>,<WMBT>}.yaml
-src/wagons/<wagon>/features/<feature>/{domain,application,infrastructure,presentation}/
-tests/wagons/<wagon>/features/<feature>/{unit,contract,integration}/
-e2e/interlockings/<interlocking>/<route>.routes.test.ts
-e2e/journeys/<journey>.journey.test.ts
+```yaml
+# atdd-bun.yaml
+profiles: [traceability, planner]
 ```
 
-Each feature must be declared by exactly one wagon and each WMBT by exactly one
-feature. Source and test headers must name the feature in their path; tests bind
-with `Acceptance:`, while exposed journey E2E tests bind with `Train:`. The
-component-URN `integration` layer maps to the `infrastructure/` directory.
+`all`, the hooks and the generated CI then run only those profiles. Any profile can still be run
+by name (`bun run atdd-bun coder`) to see what remains. An unknown name or an empty list is an
+error, never a silent run of nothing. Removing a profile loosens `atdd-bun.yaml`, so the integrity
+check reports it against the base branch until a human approves the change.
+
+## Configuration
 
-Change the four roots for an existing repository in `atdd-bun.yaml`; the same
-validation then follows the configured locations:
+Everything is set in `atdd-bun.yaml`. The main keys:
 
 ```yaml
-topology:
+profiles: [traceability, planner, topology]   # default: every profile
+topology:                                     # default layout; point it at existing roots
   plan_root: plan
   source_root: src/wagons
   test_root: tests/wagons
   e2e_root: e2e
-```
-
-### Design system
-
-The `design` profile (also part of `coder`) is the Bun realization of the core
-`coder.design.*` obligations. It recognizes a design system by its directory:
-a folder named `design`, `design_system`, or `design-system`, whose first
-subfolder names the layer:
-
-```text
-design/
-  tokens/ or foundations/   values only: palette, spacing, radii, motion
-  primitives/               Button, Text, Stack … built from tokens
-  components/               composed from primitives
-  templates/                page structure composed from components
-```
-
-Imports flow downward only, and the design system never imports app code.
-Outside the tokens layer, `.tsx`, `.html`, and `.css` files take colors,
-spacing, radii, and durations from tokens (`var(--…)`); app components render
-controls through primitives and import at least one design-system element; and
-every exported component has a consumer. Defining a custom property
-(`--accent: #0ea5e9`) is defining a token and is allowed anywhere. A repository
-without a design directory is not judged by these rules.
-
-### Journey documentation
-
-A plan describes behaviour on three levels. A journey (`plan/_journeys/`) enters
-at one interlocking and continues, through an artifact the selected train
-produces, into the next one. An interlocking chooses one route by its guards.
-A route runs one train, a linear sequence of handovers. Generate the view of all
-three from `plan/`:
-
-```sh
-bun run atdd-bun docs journeys          # writes docs/purpose/journeys/
-bun run atdd-bun docs journeys --check  # fails when the committed view differs from plan/
-```
-
-It writes `docs/purpose/journeys/index.adoc` and one SVG for each of:
-
-- **journey map:** the entry action, each interlocking, the routes it chooses
-  and their guards, the trains they run, continuations (labelled with the
-  artifact that carries control) and terminal outcomes;
-- **nominal path, end to end:** the journey's trains across all its
-  interlockings, joined into one sequence diagram;
-- **train:** each routed train as its own sequence diagram, under its
-  interlocking's route table.
-
-The page also tables every path with how it ends, and every **gap**: unreached
-interlockings, routes with no continuation or outcome, unrouted trains,
-unresolved guards. Participants are coloured by what they are (wagon, person,
-outside system) and arrows by the boundary they cross. Diagrams are inlined
-(`opts=inline`) and coloured with `var(--atdd-*, fallback)`, so a doc site can
-theme them by defining `--atdd-ink`, `--atdd-paper`, `--atdd-wagon`,
-`--atdd-person`, `--atdd-system`, `--atdd-nominal`, `--atdd-alternate`,
-`--atdd-error`, `--atdd-exception`, and the like. The output carries no
-timestamp and no package version, so it changes only when the plan does.
-
-The planner requires the journey level itself: `planner.journey.interlocking-composed`
-fails when a plan declares interlockings and no journey, or when an interlocking
-is neither a journey's entrypoint nor reached by one of its continuations.
-`planner.journey.continuation-closure` then checks each declared journey closes.
-
-**Required.** In a repository with `docs/` whose plan has journeys or
-interlockings, the `docs` profile's `planner.docs.journey-view-current` rule
-fails when any generated file is missing, stale, hand-edited, or extra. The
-generator refuses to overwrite a hand-written `index.adoc` unless you pass
-`--force`; use `--out <dir>` to preview elsewhere.
-
-### Every enforced rule is strict
-
-atdd-bun fails on every finding: it has no advisory mode and no ratchet
-baseline. Every convention with a validator is therefore `strict` (or `block`),
-and `tests/dispositions.test.ts` fails on any that promises otherwise. For the
-canonical planner nodes, which ship verbatim, the package states its own
-`disposition: strict` in `planner-nodes/ENFORCEMENT_SCOPE.yaml`.
-
-### Browser specs (Playwright)
-
-The `tester` and `htmx` profiles judge browser specs against the plan. A browser
-spec is a `*.e2e.ts` file run by Playwright, never `*.spec.ts`, which `bun test`
-would try to run itself. It binds to one plan subject and declares its layer
-and test URN:
-
-```ts
-import { expect, test } from "@playwright/test";
-
-// Train: train:orders:place-order        (or // Journey: journey:buy)
-// Layer: assembly
-// URN: test:train:orders:place-order:E2E-001-places-an-order
-```
-
-The harness code in the URN (`E2E`, `SMOKE`, `A11Y`, `VIS`, `RESP`) says what
-the spec must do: an `A11Y` spec runs `@axe-core/playwright` and asserts on its
-violations, a `VIS` spec compares a screenshot, a `RESP` spec renders at every
-declared viewport and asserts on `scrollWidth`. Coverage is read from `plan/`:
-every train has a spec, every covered train is routed by an interlocking, every
-exposed journey has an E2E or SMOKE spec and a RESP spec, and every presentation
-component has a SMOKE spec naming its wagon. Route and Station Master coverage
-remain `tester.bun` rules; browser specs count toward them.
-
-### Responsiveness
-
-The `coder` and `design` profiles check the structural causes of screens that
-break on small devices: every HTML document declares
-`<meta name="viewport" content="width=device-width, initial-scale=1">` and
-never blocks zoom; no `width`/`min-width` is wider than the smallest viewport;
-and every `@media` width is a declared breakpoint (media queries cannot read
-CSS variables, so breakpoints are declared once). The browser proof is the
-`RESP` spec above. Both read the same settings:
-
-```yaml
-# atdd-bun.yaml
+  telemetry_root: telemetry                    # tracking-plan registry; inert until the tree or a decision exists
 frontend:
-  viewports: [375, 768, 1280]          # default; RESP specs render at each, the smallest bounds fixed widths
-  breakpoints: [480, 768, 1024, 1280]  # default; the only widths @media may use
-```
-
-### Theme and contract registry
-
-Theme vocabulary belongs to the repository, not the package. When a plan uses
-themes, declare them in `plan/_themes.yaml`; only index `0: commons` is
-reserved. Every other index and kebab-case name is repository-defined.
-
-```yaml
-themes:
-  "0": commons
-  "1": orders
-  "2": inventory
+  viewports: [375, 768, 1280]
+  breakpoints: [480, 768, 1024, 1280]
+registry_paths: ["plan/_*.yaml", "contracts/_*.yaml"]   # exempt from micro-commit size caps only
+max_registry_removed_lines: 350                        # larger removals need [mass-delete-approved]
+worktrees: { enabled: false }
+release: { enabled: false }
 ```
 
-Every contract is recorded in `contracts/_contracts.yaml` with its identity,
-path, theme, producers, and consumers. The planner profile checks that contract
-references resolve, registry paths exist, a contract identity begins with its
-declared theme, and cross-wagon artifacts have contract evidence.
-
-## Hooks: fast feedback, not merge authority
-
-Run the explicit repository bootstrap once in each worktree where you work:
-
-```sh
-bun run atdd-bun init
-```
+The hooks enforce protected-branch blocking, micro-commit limits, mass-delete approval and
+validation of the affected area. Git can bypass them, so CI is the authority.
 
-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`.
-The package itself has no install script: adding the dependency never changes
-the repository until you run `init`.
+## Agents and integrity
 
-Use `hooks install`, `ci init`, `agent init`, or `integrity init` when only one surface is wanted:
+The skill gives every coding agent the lifecycle PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE and
+the profile that gates each stage. The block in `AGENTS.md` and `CLAUDE.md` adds the rules: never
+modify the toolkit itself, only the configuration it offers, and enable capabilities through
+`profiles`.
 
-```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
-```
+`atdd-bun integrity`, run by the generated test and first in CI on a clean install, fails when:
 
-The hooks enforce protected-branch blocking, micro-commit limits, mass-delete
-approval, affected-area validation, and configured traceability. To inspect or
-remove that installation, use:
+- the installed package differs from its published hashes;
+- the dependency is not an npm registry version;
+- a generated file (workflow, skills, instruction block, integrity test) was edited;
+- `atdd-bun.yaml` is looser than on the base branch.
 
-```sh
-bun run atdd-bun hooks status
-bun run atdd-bun hooks uninstall
-```
-
-Hooks can be bypassed by Git and therefore are never the merge gate. The CI
-workflow and GitHub branch ruleset are the authority for merging.
-
-### Declarative registries
-
-Micro-commit limits (`max_staged_files`, `max_staged_changed_lines`, default
-350) exist to keep imperative code changes small. They do not apply to
-declarative registries, which can legitimately be hundreds or thousands of lines
-and must not be split into invalid intermediate states. Registries are matched by
-`registry_paths` (default `plan/_*.yaml`, `plan/_*.yml`, `contracts/_*.yaml`,
-`contracts/_*.yml`).
-
-A staged registry is exempt from the size caps only. It is still:
-
-- validated by the `planner` and `traceability` profiles on every commit that
-  touches it, even when `require_traceability` is `false`;
-- subject to removal approval: a net removal above `max_registry_removed_lines`
-  (default 350) needs `[mass-delete-approved]` in the commit message. Rewriting
-  or reordering entries in place is not a removal.
-
-```yaml
-# atdd-bun.yaml
-registry_paths: ["plan/_*.yaml", "contracts/_*.yaml", "telemetry/_*.yaml"]
-max_registry_removed_lines: 200
-```
-
-Duplicate, stale, and ownership checks come from the planner rules, and
-independent review comes from the CI workflow and branch ruleset.
-
-## Agent skill: the lifecycle in the agent's context
-
-`agent init` gives every coding agent the same short ATDD skill:
-
-- `.agents/skills/atdd/SKILL.md`: the vendor-neutral Agent Skills path (Codex,
-  GitHub Copilot, Cursor, Gemini CLI, and others);
-- `.claude/skills/atdd/SKILL.md`: Claude Code;
-- a managed `<!-- atdd-bun:start -->` block in `AGENTS.md` pointing at the skill,
-  for agents that read `AGENTS.md` but not skills. The rest of `AGENTS.md` is
-  never touched.
-
-The skill names the lifecycle PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, the
-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`, 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
-
-Generate the repository-owned workflow with:
-
-```sh
-bun run atdd-bun ci init
-```
-
-This writes `.github/workflows/atdd-bun.yml`. It refuses to overwrite an
-existing workflow unless `--replace` is supplied. The generated workflow runs
-on pull requests, merge-queue merge groups, and pushes to `main`/`master`; it
-installs with `bun install --frozen-lockfile`, runs the locally installed package
-without `bunx`, runs `bun test`, and uploads reports when present.
-
-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.
+Each finding names its restore command.
 
 ## 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):
+Every merge to this package's `main` is published to npm with provenance as the next patch and
+tagged `vX.Y.Z`. Rules and hooks change as soon as a repository upgrades the dependency. To refresh
+the skills and instruction blocks on every install, add this to the repository's own
+`package.json`:
 
 ```json
-"scripts": {
-  "postinstall": "atdd-bun agent init --replace"
-}
+"scripts": { "postinstall": "atdd-bun agent init --replace" }
 ```
 
-To receive each release as a pull request, add `.github/dependabot.yml` on the
-default branch:
+Upgrade with `bun update @afokapu/atdd-bun`, or let Dependabot (`package-ecosystem: "bun"`) open a
+pull request per release. For a new `0.x` minor, run `bun add -d @afokapu/atdd-bun@latest`. If an
+upgrade changes the workflow or integrity test, run `bun run atdd-bun init --replace` and commit.
 
-```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
-commits to happen in sibling linked worktrees:
-
-```text
-my-repo/
-  main/                    # primary checkout, on branch main
-  worktrees/feature-x/     # linked checkout, on branch feature/x
-```
-
-Enable the policy in `main/atdd-bun.yaml`:
-
-```yaml
-worktrees:
-  enabled: true
-  root: ../worktrees
-  primary_directory: main
-  primary_branch: main
-  require_linked_worktree: true
-```
-
-An agent starts one worktree per work item—not per commit:
-
-```sh
-# Run from my-repo/main/ while it is on main.
-bun run atdd-bun worktree start feature/x
-```
-
-That command creates `worktrees/feature-x`, creates the `feature/x` branch, and
-installs the package hooks there. Subsequent commits happen normally from that
-linked checkout. The hook rejects commits from the primary checkout, protected
-branches, detached heads, and linked checkouts outside the configured root.
-
-When the branch is merged into local `main`, inspect or safely retire it with:
-
-```sh
-bun run atdd-bun worktree status
-bun run atdd-bun worktree finish --delete-branch
-```
-
-`finish` refuses a dirty or unmerged worktree. It never removes a worktree just
-because a hook ran.
-
-Git stores linked-worktree metadata in `main/.git/worktrees/`; the linked
-checkouts themselves belong beside `main`, not inside `.git` or inside the
-primary repository working tree.
-
-## Release policy
-
-If a repository enables `release` in `atdd-bun.yaml`, this read-only command
-checks SemVer, a single release decision, release intent, and that the proposed
-version is greater than the latest reachable matching local Git tag:
-
-```sh
-bun run atdd-bun release check
-```
+## Developing this package
 
-It creates no tag, makes no network request, and does not publish anything.
-The separate optional release workflow is where a repository may create a tag or
-publish using its own credentials and registry configuration.
-
-## Convention relationships
-
-`relationships.yaml` relates every convention the package ships (`planner-nodes/`
-and `conventions/`) to at least one other, as
-`planner.relationship.no-orphan-nodes` requires. Edges that touch a shipped
-convention are imported from the upstream ATDD graphs with their `origin`; the
-package adds its own for the conventions it introduces. A test fails when any
-shipped convention has no edge, when the node list drifts from the shipped
-conventions, or when an edge breaks `relationship.schema.json`, so a new
-convention cannot land without its relationships.
-
-## Verification of this package
-
-`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, and runs the frontend chain end to end: a Bun app
-built from a plan, its browser specs accepted by the detectors and passing in
-Chromium, and broken variants of the page failing both the static rules and the
-browser (Chromium must be installed: `bunx playwright install chromium`); it also covers hook isolation, the declarative
-registry policy, CI generation, agent-skill installation, planner scope, release
-validation, and linked-worktree policy.
+`bun test` runs the detectors' clean and dirty corpora, real-Git hook fixtures, and the frontend
+chain in Chromium (`bunx playwright install chromium`). Guard tests require every emitted rule to
+have a strict convention, a failing fixture and an edge in `relationships.yaml`.