aw-spec-cli 0.1.23 → 0.1.24

package/assets/.appweaver/templates/proposed-inventory-template.md

@@ -13,86 +13,121 @@
      Override it per project at
      .appweaver/templates/overrides/proposed-inventory-template.md to change the
      wording, the ordering or the guidance. Keep every token you want filled; drop
-     one and that section simply does not appear.
+     one and that section simply does not appear. The `## Features` heading and its
+     table's column ORDER are what `apply` parses — keep both.
 
      Tokens, each written in single braces:
-       root · head · date · strategy · reason · files · code · coverage
-       probe_table · context_table · feature_table
-       splits_section · cycles_section
+       root · head · date · strategy · reason · scanned · files · code · coverage
+       probe_table · context_table · aggregate_table · feature_table · operation_table
+       review_section · splits_section · cycles_section · unplaced_section
+     `scanned` says what was read, lane by lane; `files` (every file in the declared
+     lanes) and `code` (service-lane source files) are its two numbers on their own.
 -->
 <!-- Generated by `/appweaver inventory`. Edit freely, then run
      `/appweaver inventory apply`. -->
 
 **Repository:** `{root}`  ·  **Commit:** `{head}`  ·  **Generated:** {date}
 **Pass A strategy:** `{strategy}` — {reason}
-**Scanned:** {files} files, {code} source files  ·  **Coverage:** {coverage}%
+**Scanned:** {scanned}  ·  **Coverage:** {coverage}%
 
 This file is the **boundary map for this codebase, and it is yours to change.** Nothing
 below was decided by a person yet — it is what a deterministic scan of the source
 proposes. Read it, correct it, then run `/appweaver inventory apply`, which validates
 your edits and regenerates the machine map that `/appweaver onboard` reads.
 
+## The model this map describes
+
+The same four levels the forward pipeline writes, read back from the code:
+
+| Level | What it is | Where the specs keep it | Where the code keeps it |
+|---|---|---|---|
+| **Bounded context** | a boundary with its own model and language | `specs/<Context>/` and its one `domain-model.md` | the module folder — one per context |
+| **Aggregate** | what must stay consistent together | a `## Aggregate: <Root>` section of that `domain-model.md` | a type declared as an aggregate root, in the module's `Domain/` |
+| **Feature** | a capability the developer chose | `specs/<Context>/<Feature>/spec.md` | the UI lane's `features/<Feature>/` folder, named verbatim |
+| **Operation** | one command or query the code exposes | the behaviour the `spec.md`'s user stories (`US-n`) and requirements describe | one slice under the module's `Features/` (command or query + handler + endpoint + validator), or a handler class where the solution keeps them in its own project |
+
+- A feature lives in **exactly one** bounded context.
+- An operation is **not** a user story. A story usually needs several operations (record
+  a draft, then add, revise and remove its notes), and a read can serve stories in
+  several features. The stories are written with the feature's spec — by `adopt`, for
+  code that exists; this map only places the operations.
+- A feature may act on **several** aggregates, and several features may act on **one**
+  aggregate — within its context. Another context's aggregate is referenced by id.
+- **An operation is never a feature, and a bounded context is never an aggregate.** A
+  slice folder under the service's `Features/` is one operation of its module, however
+  it is named.
+
 ## How to edit this file
 
 - **Rename** a feature or a bounded context by editing its cell. Names are the
   identity — renaming a feature here renames the slice onboard will create.
-- **Move** a feature to another context by editing its Bounded Context cell.
-  A feature lives in exactly one context.
-- **Merge** two features by giving them the same name; their files combine, and the
-  merged feature acts on every aggregate its rows name — that is how one feature spans
-  several aggregates. Keep those rows in the same Bounded Context.
-- **Split** a feature by adding a row with the same Aggregate and a different
-  Feature name. Name the split from the capability, not the noun —
-  `PatientRegistration`, not a second `Patient`.
-- **Reorder** by editing Depends On. Waves are recomputed on apply, so you do
-  not maintain wave numbers by hand.
+- **Move** a feature to another context by editing its Bounded Context cell. Every row
+  of one feature must name the same context.
+- **One feature, several aggregates** is several rows with the same Feature name and
+  different Aggregates. That is how the table writes many-to-many: add a row to make a
+  feature act on another aggregate, delete one to stop it.
+- **Move an operation** between features by editing the Operations cells. The cell on
+  a row lists what that feature does to that row's aggregate. A read may sit under
+  several features; a command normally belongs to one.
+- **Merge** two features by giving them the same name; their operations combine.
+- **Split** a feature by adding a row with the same Aggregate and a different Feature
+  name, then moving operations to it. Name the split from the capability, not the
+  noun — `PatientRegistration`, not a second `Patient`.
+- **Reorder** by editing Depends On. Waves are recomputed on apply, so you do not
+  maintain wave numbers by hand.
 - Rows you delete are dropped from the map and never onboarded.
 
-The Aggregate column must name an aggregate the scan found; everything else is
-yours. `apply` reports anything it cannot resolve rather than guessing.
+The Aggregate column must name an aggregate the scan found, and every name in an
+Operations cell an operation it found; everything else is yours. `apply` reports
+anything it cannot resolve rather than guessing.
 
 ## How these boundaries were found
 
 Three passes over the source. None of them reads a specification, a rule file or an
 exemplar from another project — the code is the only evidence.
 
-**Pass A — what must stay consistent together.** Groups the source into candidate
-aggregates. Three strategies can do this, and only those the evidence supports are
-offered:
+**Pass A — the aggregates.** Four strategies, each offered only where its evidence
+exists:
 
 | strategy | the evidence it reads | available when |
 |---|---|---|
+| `domain` | the aggregate roots the code **declares** — a type deriving from an aggregate-root base or carrying an aggregate-root marker; its context is the module folder holding its `Domain/` layer; it owns what it alone reaches, then what is named after it or used by it alone (its DTOs, errors, mappings, ports); its operations are its module's slices and command/query handlers anywhere in the lane, so a solution split one project per layer reads the same as one split per module | at least one root is declared |
 | `structure` | the repo's own organising axis — a vertical slice, a layer folder under a module, a layer carried as a project-name suffix, or a layer at the top with the module repeated as a noun | always |
 | `reference` | the `using` / `import` / `require` graph, clustered after removing the high-fan-in nodes that are shared kernel rather than features | enough import-parseable source |
-| `persistence` | the schema itself — `DbSet<T>`, `[Table]`, JPA `@Entity`, `schema.prisma`, `CREATE TABLE` — with roots derived by ownership: an entity that owns others' lifecycles and is referenced from outside by id | ORM / schema / migration evidence found |
-
-`structure` always runs whichever strategy is chosen, because the other two produce
-unnamed clusters and need it to give each one a directory and a human name.
-
-**Pass B — what can be cut over together.** Reads the application, API and UI surface
-only, and emits *signals*, never decisions: route families (`[Route("orders")]`,
-`@RequestMapping`, `app.get('/orders/…')`), command/handler groups, UI router segments,
-and rates of change from git history. **Two distinct route families on one aggregate is
-a split candidate** — proposed below, never applied.
-
-Three of the five tests for a feature boundary are computable — one cutover seam,
-stable file ownership, one bounded context — and two are not: whether it serves one
-business need, and whether it can be demonstrated independently. Those two are why this
-file is editable.
-
-**Pass C — the proposal.** One aggregate becomes one feature with the same name. That
-is the default and not a failure. A split is proposed only where Pass B found the
-evidence, and is shown with that evidence for you to accept or ignore. One endpoint is
-never a feature; neither is one whole bounded context.
-
-**Bounded contexts** are derived above Pass A and voted from where each candidate's
-files actually live. A feature belongs to exactly one context — the context of the
-primary aggregate it acts on. A feature that needs another context's aggregate
-references it by id and stays a separate feature over there.
+| `persistence` | the entities the code tells its ORM about — `DbSet<T>`, `IEntityTypeConfiguration<T>`, `modelBuilder.Entity<T>()`, `[Table]`, JPA `@Entity`, `schema.prisma`, `CREATE TABLE` — plus what they hold collections of, with roots derived by ownership: an entity that owns others' lifecycles and is referenced from outside by id. Read from class shape only where nothing is declared | ORM / schema / migration evidence found |
+
+**Declared beats measured.** Where the code declares its roots and operations act on
+them, `domain` is chosen whatever the others score: a declaration is the boundary
+itself. Otherwise the highest-coverage strategy is proposed — coverage says how much of
+the code a strategy placed, not whether it placed it right, so read the counts beside
+it. `structure` always runs underneath, because the other strategies need it to give a
+cluster a directory and a human name.
+
+**Pass B — the operations and their seams.** Reads the application, API and UI surface
+only: each operation's route (`Get("/care/encounters/{id}")`, `[HttpPost]`,
+`@GetMapping`, `app.get(…)`), the aggregate it acts on, and whether it creates one.
+Route families are read below the bounded context's own prefix. **Two route families
+on one aggregate is a split candidate** — proposed below, never applied.
+
+**Pass C — the features.** A feature is a capability, so it is proposed only from
+evidence that names one:
+
+1. every UI `features/<Feature>/` folder becomes a feature, named verbatim, holding the
+   operations it calls and acting on those operations' aggregates;
+2. a read no feature calls joins every feature acting on its aggregate — reads are
+   shared, and they are not what separates two capabilities;
+3. what is left — commands no feature calls, and aggregates no UI feature touches —
+   becomes **one feature per aggregate, named after it**. That default is a placeholder
+   for a capability the code does not name: rename it.
+
+**Order** follows creation: on each aggregate the feature holding its creating operation
+goes first, every other feature on it follows, and an aggregate that references another
+by id follows that one's creator. Reads never order anything.
 
 ## Strategy probe
 
-The clustering each available strategy produced on this tree. The chosen one is
+The clustering each available strategy produced on this tree, with the first names it
+found — judge a strategy by what it found, not only by how many. The chosen one is
 marked; re-run with `--strategy <name>` to pick another.
 
 {probe_table}
@@ -104,14 +139,31 @@ depends on has been onboarded.
 
 {context_table}
 
+## Aggregates
+
+What each context's model holds, and which features act on each aggregate. Files is
+every file the aggregate owns — its model, persistence, application-layer files and
+operations. Read-only — change which features act on what in the Features table below.
+
+{aggregate_table}
+
 ## Features
 
 Dependency order. **Wave 0 depends on nothing** and can be onboarded first; a feature in
 wave N depends only on features in earlier waves. Edit any cell except Wave, which is
-recomputed.
+recomputed. One row per feature **per aggregate it acts on**. Files is what the feature
+brings: its operations' files and its UI feature folder — plus its aggregate's own files
+when it is the only feature on that aggregate.
 
 {feature_table}
-{splits_section}{cycles_section}
+{review_section}{splits_section}{cycles_section}
+## Operations
+
+Every operation the scan found, what it acts on, and the feature(s) it serves.
+Read-only — move an operation by editing the Operations cells above.
+
+{operation_table}
+{unplaced_section}
 ## What happens after you apply this
 
 ```

package/assets/.appweaver/templates/source-map-template.md

@@ -53,15 +53,21 @@
 
 <!--
   ACTION REQUIRED: one row per legacy artefact this slice owns. Every source file
-  in the OKF bundle concept's `source_files` MUST appear here (Fidelity checks
-  full coverage both ways: no unmapped code, no spec id without a code anchor).
+  in the OKF bundle concept's `source_files` MUST have a home (Fidelity checks full
+  coverage both ways: no unmapped code, no spec id without a code anchor) — a row
+  here, or, when the file serves ONLY another feature over the same aggregate, a
+  `sibling: <Feature>` line under Unmapped / open. The rows are this feature's file
+  list: later phases hand exactly these files to their fix loops.
+  "Design element" names the plan's OWN section — its number and heading as that
+  plan has them. The plan's structure follows the code, so the numbering is whatever
+  the plan uses, never a fixed layering.
 -->
 
 | # | Legacy artefact | Kind | Spec ids | Design element | Confidence | Notes / quirk |
 |---|---|---|---|---|---|---|
-| SM-001 | `src/.../MedicinalProduct.cs` | file (aggregate root) | US-1, BR-001 | §1 Domain · MedicinalProduct | certain | |
-| SM-002 | `PRODUCTS` | table | FR-003, DC-001 | §4 Infra · MedicinalProductRepository | inferred | NDC stored unformatted — see WA/CN |
-| SM-003 | `POST /product` | endpoint | US-1, FR-001 | §3 API · RegisterMedicinalProduct | certain | |
+| SM-001 | `src/.../MedicinalProduct.cs` | file (aggregate root) | US-1, BR-001 | backend-plan §[n] [domain section] · MedicinalProduct | certain | |
+| SM-002 | `PRODUCTS` | table | FR-003, DC-001 | backend-plan §[n] [persistence section] · MedicinalProductRepository | inferred | NDC stored unformatted — see WA/CN |
+| SM-003 | `POST /product` | endpoint | US-1, FR-001 | backend-plan §[n] [endpoint section] · RegisterMedicinalProduct | certain | |
 
 ## As-built quirks captured
 
@@ -80,8 +86,10 @@
 <!--
   Source files the reverse pass could not confidently place, and spec ids with no
   code home found. Both are Fidelity gaps to resolve (out of band or by refining
-  the reverse spec/design). Empty when the map is complete.
+  the reverse spec/design). Empty when the map is complete. Sibling files are not
+  gaps: they are placed, in another feature, and listed so the placement is visible.
 -->
 
 - **Unmapped code**: [files not yet placed, or "none"]
+- **Sibling files**: [`<path>` — sibling: <Feature>, one per file that serves only another feature over the same aggregate, or "none"]
 - **Unanchored spec ids**: [spec items with no code, or "none"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aw-spec-cli",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "AppWeaver Spec-Driven Development CLI - scaffolds projects with vertical slices, DDD, CQRS, and agent skills",
   "type": "module",
   "main": "dist/index.js",