@afokapu/atdd-bun 0.10.31 → 0.10.33

package/README.md

@@ -19,8 +19,8 @@ bun run atdd-bun init
 ```
 
 `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
+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`.
 
 Then require the workflow's job in the GitHub branch ruleset, so it gates merges.
@@ -33,7 +33,8 @@ Then require the workflow's job in the GitHub branch ruleset, so it gates merges
 | `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 agent <init\|status>` | Manage the `AGENTS.md`/`CLAUDE.md` instruction block |
+| `atdd-bun profiles registry [--check]` | Generate (or verify) deterministic profile-scoped convention registries |
 | `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 |
@@ -55,7 +56,6 @@ registerEnforcementTest({ root: import.meta.dir + "/..", profiles: ["traceabilit
 | `topology` | feature decomposition and the plan, source, test and E2E locations. Missing source, tests and E2E suites are reported only when a run also selects `coder` or `tester`, so a repository in the PLAN stage can enforce `planner` and `topology` before RED |
 | `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 |
-| `delivery` | the review record of each tranche under `docs/delivery/tranches/`: allowed writer and reviewer models with recorded fallbacks, reviewer independence, every finding fixed, withdrawn after one dispute or ruled on by a human, every configured stage approved, and, at the gate, no change without a record and a merged head that contains exactly the approved commit. Inert until adopted |
 | `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 |
@@ -85,7 +85,7 @@ the adoption that establishes the governed set, so a brownfield repository can d
 `profiles: [docs]` in an ordinary pull request. From then on, the integrity check reports, against
 the base branch, removing a profile from the list and removing the list itself. The second closes
 the two-step bypass `[docs, security]` → no list → `[docs]`. `init` writes a new `atdd-bun.yaml`
-with every profile listed except the opt-in `delivery`, so a greenfield repository is governed from its first commit; trim the
+with every profile listed, so a greenfield repository is governed from its first commit; trim the
 list before that commit to adopt gradually.
 
 ## Configuration
@@ -105,117 +105,11 @@ frontend:
   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 }
+worktrees: { enabled: false }                 # enabled defaults to ~/Github/worktrees/<repo>/...
 release: { enabled: false }
 ```
 
-### Delivery
-
-For programs delivered as tranches by a coordinator and persistent drivers, with headless writers
-and independent reviewers. Adopt it by naming `delivery` in `profiles:` (or, with no list, by adding
-a `delivery:` block); `agent init` then installs the delivery skill. The adopting pull request is
-itself governed: the skill and workflow it brings are outside the delivery root, so it carries its
-own tranche record, reviewed and `ready` like any other. A later change to `atdd-bun.yaml` alone
-needs no record: the integrity check reports any loosening for a human to approve.
-
-The policy names, for each lifecycle stage (plan, red, green, refactor, final), who may write it and
-who reviews it; either may be absent. By default two stages are reviewed: the plan, and the whole
-change at its head (final). Red, green and refactor are written and held by their gates. How the
-coordinator and drivers carry this out is the `delivery.operating-model` convention; what a reviewer
-checks is `delivery.review`; how agents talk, through a local ntfy board with one topic per program,
-tranche and review conversation (`atdd-bun chat`), is `delivery.board`, used only when `delivery.board` is
-set. The skill only points to them.
-
-The records live with the program's reasoning, in the docs profile's `docs/delivery/` area:
-
-```text
-docs/delivery/index.adoc                           the program: why, scope, how it was split (docs profile)
-docs/delivery/tranches/<tranche>/evidence.yaml     one tranche's review record (delivery profile)
-docs/delivery/tranches/<tranche>/*.json            the retained raw reviewer reports
-```
-
-Where delivery is adopted, the docs profile leaves the records folder's records and data files to
-the delivery profile: they are not authored documentation, and changing them needs no docs
-declaration. AsciiDoc there stays documentation. Where the docs profile is active, the first tranche
-also brings `docs/index.adoc` and `docs/delivery/index.adoc`, each with `:doc-id:` and `:status:`,
-since every docs area needs an index.
-
-Upgrading from 0.8.0: records under `delivery/` are reported until `delivery.root: delivery` is set
-(a reported root change, approved once) or they are moved. A data file in an old tranche that no
-record there names is reported on local runs, not at the merge gate; removing it is a gate change a
-human approves, or a new tranche's record can name it.
-
-Upgrading from 0.9.0: an `atdd-bun.yaml` field with the wrong type (a quoted number, `yes`/`no`, a
-non-string list item, `.inf`) is now reported, and on the base branch it blocks every pull request,
-since the policy cannot be compared. Correct such fields on the base branch before upgrading.
-
-Upgrading to 0.10: the policy names writers and reviewers per stage. The 0.9 stage names
-(`plan_review`, `test_review`, `code_review`, `final_review` with `authors` and `reviewers`) are still
-read, as `plan`, `red`, `refactor` and `final`, and 0.9 records that name review authors still count as
-recorded work. Independence now defaults to `different-model`: a repository that relied on the old
-`fresh-process` default sets it explicitly. A repository with no `stages:` gets the new default
-operating model, without the integrity check reporting the change.
-
-From 0.10.2 the pre-commit hook no longer counts uncommitted work: it refused exactly the small
-commits that reduce it. `max_uncommitted_files` is no longer read; commit size stays limited by
-`max_staged_files` and `max_staged_changed_lines`.
-
-From 0.10.3 each ready record is judged by the delivery policy in `atdd-bun.yaml` at its `approved_sha`:
-a later policy change (dropping or reordering a model, removing a review) never makes a merged record
-fail. Records in progress are judged by the current policy.
-
-From 0.10.4 a stage with nothing written (a plan-only or no-op tranche) records no work; a review
-whose range recorded none answers for the latest recorded work before it.
-
-From 0.10.5 only coordinators and drivers use the board: a writer or reviewer takes its task from its
-launch prompt and returns its answer as output, which the driver posts. `atdd-bun chat wait` takes several
-topics and `--skip heartbeat`; reviewers answer in JSON.
-
-From 0.10.7 only a browser spec (a `*.e2e.*` file, or a Playwright file bound by `// Train:`/`// Journey:` or a
-`test:train:`/`test:journey:` URN) is a journey spec. A `bun:test` file may carry the `Acceptance:` line
-traceability needs, including a test proving `acc:train:…` and the journey test `atdd-bun.topology.e2e-location` requires.
-
-Every key is optional; these are the defaults:
-
-```yaml
-delivery:
-  root: docs/delivery/tranches       # one <tranche>/evidence.yaml per tranche, reports beside it
-  require_record: true               # at the gate, a change outside the root (other than atdd-bun.yaml alone) needs a tranche record
-  multiplexer: herdr                 # the terminal multiplexer humans watch agents in; any command name
-  # board: { url: http://127.0.0.1:2586 }   # opt-in: agents talk through a local board; absent, there is none
-  independence: different-model      # a reviewer's model wrote none of the work it reviews; or fresh-process
-  stages:                            # models in preference order: the first, then recorded fallbacks
-    plan:     { writer: [codex, claude-opus, kimi], reviewer: [glm, claude-opus, codex, kimi] }
-    red:      { writer: [glm, claude-sonnet, deepseek-flash, claude-opus, codex, kimi] }
-    green:    { writer: [glm, claude-sonnet, deepseek-flash, claude-opus, codex, kimi] }
-    refactor: { writer: [glm, claude-sonnet, deepseek-flash, claude-opus, codex, kimi] }
-    final:    { reviewer: [codex, glm, claude-opus, kimi] }
-  fallback: { after_failures: 3, within_minutes: 10, when_exhausted: block }   # or wait
-  commands: {}                       # per model: { author: "...", review: "..." } overriding delivery.operating-model's defaults
-```
-
-The profile checks the record, never the running agents. The generated CI sets
-`ATDD_DELIVERY_GATE`: `merge` on pull requests and the merge queue, where every record the branch
-changes must be `ready`, the branch may differ from its approved SHA only under the delivery root,
-and a change outside the root needs a record unless it touches only `atdd-bun.yaml` (`require_record`, default true); `post-merge` on a
-push to a protected branch (the generated workflow's push branches follow `protected_branches`), where the pushed commit must contain every approved SHA it brings in. Merge tranches with a
-merge commit: a squash or rebase merge writes a commit no reviewer saw, and the post-merge check
-fails on it. Moving the root, dropping a stage, relaxing a stage from `different-model` to
-`fresh-process`, no longer reviewing a stage, adding a writer or reviewer, moving a fallback model earlier in a list, turning off
-`require_record`, making fallback easier, or adding or changing a model's `commands` loosens the policy and is reported by the integrity check.
-
-The record's model and run identifiers are the driver's claims. The profile checks that they are
-consistent and that a `ready` record retains every review's raw report (a record in progress may lag
-behind); it does not verify them
-cryptographically.
-
-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. The changed-line
-limit counts a moved file by the edits it carries, so relocating a directory is not measured as
-rewriting it; mass-delete and registry-removal approval still count a move in full.
-The journey view `atdd-bun docs journeys` generates is exempt from the size caps, since its index
-alone can exceed them, and never from the `docs` profile, which refuses a copy that is not exactly
-what the plan generates.
+When enabled without overrides, a primary checkout at `~/Github/<repo>` uses linked worktrees at `~/Github/worktrees/<repo>/<branch>`. The defaults use `primary_directory: .` (the current primary checkout) and `root: ../worktrees/{repo}`; `{repo}` expands to the primary checkout's directory name. Repositories that need another layout can set either field explicitly.
 
 ## Docs-site theme
 
@@ -234,17 +128,17 @@ To re-theme it, override its custom properties (`--paper`, `--ink`, `--accent`,
 
 ## Agents and integrity
 
-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; turn profiles on or off in
-`profiles:` only when the user asks; and, where `delivery` is active, deliver tranches through the
-delivery skill.
+The managed block directs an agent to the profile-preset convention, then to the selected profile's
+generated registry under `conventions/_profiles/`. Each registry is a deterministic projection of
+the profile's detector manifests, convention paths, and direct relationship edges, so the agent
+opens only the conventions relevant to its task. It also prevents the agent from modifying the
+toolkit or changing profile activation without the user's choice.
 
 `atdd-bun integrity`, run by the generated test and first in CI on a clean install, fails when:
 
 - 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;
+- a generated file (workflow, instruction block, integrity test) was edited;
 - `atdd-bun.yaml` is looser than on the base branch (after the first explicit `profiles:` list,
   dropping a profile or the list counts).
 
@@ -254,7 +148,7 @@ Each finding names its restore command.
 
 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
+the managed instruction blocks on every install, add this to the repository's own
 `package.json`:
 
 ```json

package/conventions/_profiles/architecture.yaml

@@ -0,0 +1,190 @@
+schema_version: "1.0.0"
+profile: "architecture"
+implementations:
+  - "bun_clean_architecture_detector"
+conventions:
+  - rule_id: "coder.bun.boundaries-http-client"
+    path: "conventions/coder.bun/coder.bun.boundaries-http-client.convention.yaml"
+  - rule_id: "coder.bun.commons-application-no-integration"
+    path: "conventions/coder.bun/coder.bun.commons-application-no-integration.convention.yaml"
+  - rule_id: "coder.bun.commons-cross-feature-imports-in"
+    path: "conventions/coder.bun/coder.bun.commons-cross-feature-imports-in.convention.yaml"
+  - rule_id: "coder.bun.commons-domain-no-framework-import"
+    path: "conventions/coder.bun/coder.bun.commons-domain-no-framework-import.convention.yaml"
+  - rule_id: "coder.bun.commons-domain-no-outbound"
+    path: "conventions/coder.bun/coder.bun.commons-domain-no-outbound.convention.yaml"
+  - rule_id: "coder.bun.composition-consumer"
+    path: "conventions/coder.bun/coder.bun.composition-consumer.convention.yaml"
+  - rule_id: "coder.bun.composition-root"
+    path: "conventions/coder.bun/coder.bun.composition-root.convention.yaml"
+  - rule_id: "coder.bun.design-hierarchy-import"
+    path: "conventions/coder.bun/coder.bun.design-hierarchy-import.convention.yaml"
+  - rule_id: "coder.bun.dto-mapper"
+    path: "conventions/coder.bun/coder.bun.dto-mapper.convention.yaml"
+  - rule_id: "coder.bun.dto-placement"
+    path: "conventions/coder.bun/coder.bun.dto-placement.convention.yaml"
+  - rule_id: "coder.bun.dto-purity"
+    path: "conventions/coder.bun/coder.bun.dto-purity.convention.yaml"
+  - rule_id: "coder.bun.layer-naming"
+    path: "conventions/coder.bun/coder.bun.layer-naming.convention.yaml"
+relationships:
+  - confidence: 1
+    constraint: "discretionary"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "Confines outbound transport to integration, which is the hierarchy's own home for it."
+    source_ref: "coder.bun.boundaries-http-client"
+    strength: "minor"
+    target_ref: "coder.bun.design-hierarchy-import"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "A specialization: the general inward-only rule, narrowed to the commons application tree."
+    source_ref: "coder.bun.commons-application-no-integration"
+    strength: "important"
+    target_ref: "coder.bun.design-hierarchy-import"
+    type: "requires"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "The hierarchy governs VERTICAL edges between layers; this governs HORIZONTAL ones between sibling features."
+    source_ref: "coder.bun.commons-cross-feature-imports-in"
+    strength: "important"
+    target_ref: "coder.bun.design-hierarchy-import"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "finish_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "Outbound bans project LAYERS; this additionally bans runtime machinery, so the domain runs with no server started."
+    source_ref: "coder.bun.commons-domain-no-framework-import"
+    strength: "important"
+    target_ref: "coder.bun.commons-domain-no-outbound"
+    type: "requires"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "A specialization: the general inward-only rule, narrowed to the commons domain tree."
+    source_ref: "coder.bun.commons-domain-no-outbound"
+    strength: "important"
+    target_ref: "coder.bun.design-hierarchy-import"
+    type: "requires"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "Two halves of one discipline: where wiring MAY happen, and that consumers must ACCEPT what they are given."
+    source_ref: "coder.bun.composition-consumer"
+    strength: "critical"
+    target_ref: "coder.bun.composition-root"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "finish_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "Reachability is measured FROM the structural roots that composition-root confines wiring to."
+    source_ref: "coder.bun.dead-code-reachability"
+    strength: "important"
+    target_ref: "coder.bun.composition-root"
+    type: "requires"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "code layering and design-system layering: both require dependencies to point in one direction"
+    source_ref: "coder.bun.design-dependency-flow"
+    strength: "important"
+    target_ref: "coder.bun.design-hierarchy-import"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "discretionary"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "The mapper translates the type whose home this rule fixes; both keep the boundary in one place."
+    source_ref: "coder.bun.dto-mapper"
+    strength: "minor"
+    target_ref: "coder.bun.dto-placement"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "Purity governs a DTO's shape, placement its home; a pure DTO in the wrong layer still couples the boundary."
+    source_ref: "coder.bun.dto-placement"
+    strength: "important"
+    target_ref: "coder.bun.dto-purity"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "finish_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "The layer segment this rule validates is what the layering rules read to judge an import."
+    source_ref: "coder.bun.green-urn-layer"
+    strength: "important"
+    target_ref: "coder.bun.design-hierarchy-import"
+    type: "enables"
+  - confidence: 1
+    constraint: "discretionary"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "Both govern server.ts as the composition root: one that collaborators are only instantiated there, the other that the JOURNEY_MAP it holds agrees with the declared route space."
+    source_ref: "coder.bun.interlocking-bilateral-binding"
+    strength: "minor"
+    target_ref: "coder.bun.composition-root"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "finish_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "The layering rules can only read a layer that the naming rule guarantees is declared."
+    source_ref: "coder.bun.layer-naming"
+    strength: "critical"
+    target_ref: "coder.bun.design-hierarchy-import"
+    type: "enables"
+  - confidence: 1
+    constraint: "discretionary"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "One governs the server you run, the other the client you call out with."
+    source_ref: "coder.bun.runtime-server-is-bun-serve"
+    strength: "minor"
+    target_ref: "coder.bun.boundaries-http-client"
+    type: "runs_alongside"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "finish_to_start"
+    origin: "atdd-extensions@3aa141e:official/atdd.extension.coder.bun/relationships.yaml"
+    reason: "server.ts is a composition root precisely BECAUSE Bun.serve is the assembly point of a full-stack Bun app."
+    source_ref: "coder.bun.runtime-server-is-bun-serve"
+    strength: "important"
+    target_ref: "coder.bun.composition-root"
+    type: "enables"
+  - confidence: 1
+    constraint: "mandatory"
+    control: "internal"
+    foundation: "start_to_start"
+    origin: "@afokapu/atdd-bun"
+    reason: "vendor SDKs stay in infrastructure adapters as framework imports stay out of domain"
+    source_ref: "coder.bun.telemetry-vendor-sdk"
+    strength: "important"
+    target_ref: "coder.bun.commons-domain-no-framework-import"
+    type: "runs_alongside"