aw-spec-cli 0.1.31 → 0.1.32

package/assets/.appweaver/scripts/python/aw-stack.py

@@ -1771,7 +1771,7 @@ def cmd_verify(args):
     lanes = (data or {}).get("lanes") or []
     required = [k for k in (args.require or []) if k in ("backend", "frontend")]
     worked = working_lane(repo, lanes)["kinds"]
-    issues = []
+    issues, missing_roots = [], []
 
     # An empty file and an absent one are the SAME state. The kit ships
     # stacks.json with an empty `lanes` array so a project can fill it in by hand, so
@@ -1802,13 +1802,15 @@ def cmd_verify(args):
                     "subtree; without one nothing can be built, run or written into it. "
                     "Re-run `/appweaver select-stack` and give it a lane root folder."
                     % (lane_id, kind, lane.get("profile", "?")))
-            elif (not args.allow_missing_root and not root_on_disk(repo, root)
-                  and (not args.working_only or kind in worked or kind in required)):
-                issues.append(
+            elif not root_on_disk(repo, root):
+                missing_roots.append(
                     "lane '%s' (%s, stack %s) declares lane root folder '%s', which is not a "
                     "directory in this repository. Re-run `/appweaver select-stack` and "
                     "point the lane at the directory that holds its source."
                     % (lane_id, kind, lane.get("profile", "?"), root))
+                if (not args.allow_missing_root
+                        and (not args.working_only or kind in worked or kind in required)):
+                    issues.append(missing_roots[-1])
         # `declare` refuses an overlap, so one can only arrive here through a
         # hand-edited file — a supported way to fill this in, and the one path that
         # does not pass the writer. The invariant is worth a second check anywhere:
@@ -1838,6 +1840,13 @@ def cmd_verify(args):
         "kinds": sorted({l.get("kind", "") for l in lanes if l.get("kind")}),
         "root_check": not args.allow_missing_root,
         "root_check_working_only": bool(args.working_only),
+        # The kinds whose lane root folder is on disk, and the issue each declared lane
+        # without one would raise. Reported whether or not the check is on: a phase that
+        # reads code with `--allow-missing-root` reads the lanes that exist, and stops only
+        # when none does.
+        "kinds_on_disk": sorted({l.get("kind") for l in lanes
+                                 if l.get("kind") and root_on_disk(repo, l.get("root", ""))}),
+        "missing_roots": " ".join(missing_roots),
         "issues": issues,
         "issue_count": len(issues),
         # No lanes always carries an issue now, so a clean run always has lanes to name.

package/assets/.appweaver/scripts/python/aw-xref.py

@@ -112,9 +112,9 @@ _IDENT_RE = re.compile(r"^[A-Za-z][A-Za-z0-9._-]*$")
 # ─────────────────── source_files architecture grouping ────────────────────
 # `source_files` stays a FLAT YAML list — validate_okf (E2/W6), the aw-inventory
 # concept resolver and the source-map fidelity check all key on that shape, and
-# both lenient frontmatter parsers in the toolchain only understand scalars +
-# flat block lists. So the grouping is emitted as YAML comment headers, which
-# PyYAML and both lenient parsers skip: readable grouping, zero schema change, no
+# the toolchain's lenient frontmatter reader (aw-inventory's parse_frontmatter)
+# understands scalars and flat lists only. So the grouping is emitted as YAML comment
+# headers, which PyYAML and that reader skip: readable grouping, zero schema change, no
 # duplicated path list. Regenerated on every write (comments are lost on read and
 # re-derived deterministically), so it is idempotent.
 #
@@ -426,27 +426,33 @@ def _render_impact_md(aggregate, users):
 
 
 # ─────────────────────────── frontmatter I/O ───────────────────────────────
+_INVENTORY = None
+
+
+def _inventory():
+    """aw-inventory, loaded by path once — it owns the concept frontmatter reader, and a
+    second copy here is how two answers to what a concept lists start to drift."""
+    global _INVENTORY
+    if _INVENTORY is None:
+        import importlib.util
+        p = os.path.join(os.path.dirname(os.path.abspath(__file__)), "aw-inventory.py")
+        spec = importlib.util.spec_from_file_location("aw_inventory", p)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        _INVENTORY = mod
+    return _INVENTORY
+
+
 def _read_fm(text):
-    """Return (frontmatter dict, body). Scalars are strings; block lists are lists.
-    Mirrors aw-inventory.py's lenient parser so the two agree without a YAML dep."""
-    if not text.startswith("---"):
-        return {}, text
-    lines = text.splitlines()
-    end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
-    if end is None:
-        return {}, text
-    fm, key = {}, None
-    for ln in lines[1:end]:
-        m = re.match(r"^([A-Za-z0-9_]+):\s*(.*)$", ln)
-        if m:
-            key = m.group(1)
-            val = m.group(2).strip()
-            fm[key] = val.strip("'\"") if val else []
-        elif key and re.match(r"^\s*-\s+", ln):
-            if not isinstance(fm.get(key), list):
-                fm[key] = []
-            fm[key].append(re.sub(r"^\s*-\s+", "", ln).strip().strip("'\""))
-    return fm, "\n".join(lines[end + 1:])
+    """Return (frontmatter dict, body), read by aw-inventory's parse_frontmatter: scalars
+    are strings, and a list — block or flow — is a list."""
+    return _inventory().parse_frontmatter(text)
+
+
+def _fm_list(value):
+    """A frontmatter list field as its non-empty strings (aw-inventory's fm_list): a
+    single value where a list belongs is a one-item list."""
+    return _inventory().fm_list(value)
 
 
 def _render_fm(fm):
@@ -763,13 +769,7 @@ def _has_code(name, bundle_abs):
     if not path:
         return False
     fm, _ = _read_fm(_read(path))
-    files = fm.get("source_files")
-    if isinstance(files, list):
-        return any(str(f).strip() for f in files)
-    # The front-matter reader returns a BLOCK list as a list and anything else as the raw
-    # scalar, so the `source_files: []` a stub carries arrives as the STRING "[]" — which
-    # is empty, and truthy to anyone who does not look inside it.
-    return bool(str(files or "").strip(" \t[]"))
+    return bool(_fm_list(fm.get("source_files")))
 
 
 def _concept_title(path):
@@ -1087,8 +1087,7 @@ def cmd_concept_upsert(args):
                 if args.merge:
                     # CR mode: {{files}} is only the delta's changed files — UNION with the
                     # slice's existing source_files, never replace (that would drop the rest).
-                    existing = fm.get("source_files") if isinstance(fm.get("source_files"), list) else []
-                    merged = list(existing)
+                    merged = _fm_list(fm.get("source_files"))
                     for s in source_files:
                         if s not in merged:
                             merged.append(s)
@@ -1131,7 +1130,7 @@ def _merge_features(existing, names):
     """`existing` plus each of `names` not already listed, compared case- and
     punctuation-insensitively. Never drops an entry: a concept's feature list only grows,
     the same as adopt extends a concept additively."""
-    out = [x for x in (existing if isinstance(existing, list) else []) if x]
+    out = _fm_list(existing)
     keys = {_key(x) for x in out}
     for n in names:
         if n and _key(n) not in keys:
@@ -1236,10 +1235,8 @@ def cmd_concept_paths(args):
     declared, existing, missing = [], [], []
     if path:
         fm, _ = _read_fm(_read(path))
-        raw = fm.get("source_files")
-        # _read_fm gives a list for a block list, "" for an empty scalar; the `# Layer`
-        # group headers _render_fm writes are comments and are already skipped by it.
-        items = raw if isinstance(raw, list) else ([raw] if isinstance(raw, str) and raw else [])
+        # The `# Layer` group headers _render_fm writes are comments, skipped by _read_fm.
+        items = _fm_list(fm.get("source_files"))
         seen = set()
         for s in items:
             s = (s or "").strip().strip('"').strip("'").replace(os.sep, "/")
@@ -1546,13 +1543,28 @@ def cmd_co_owners(args):
 
 def _map_features(root):
     """(features, commit) from the confirmed boundary map — ([], "") where there is none."""
+    m = _feature_map(root)
+    return (m.get("features") or []), (m.get("commit") or "")
+
+
+def _feature_map(root):
+    """The confirmed boundary map, or {} where there is none."""
     try:
         with open(os.path.join(root, ".appweaver", "inventory", "feature-map.json"),
                   encoding="utf-8") as fh:
             m = json.load(fh)
     except (OSError, ValueError):
-        return [], ""
-    return (m.get("features") or []), (m.get("commit") or "")
+        return {}
+    return m if isinstance(m, dict) else {}
+
+
+def _published_ids(root):
+    """{operation: [id, …]} — the ids the boundary map records each operation as
+    published under in the API document, verbatim. Operations published under none
+    are left out."""
+    return {o["name"]: list(o.get("operation_ids") or [])
+            for o in _feature_map(root).get("operations") or []
+            if isinstance(o, dict) and o.get("name") and o.get("operation_ids")}
 
 
 def _operation_scope(root, feature, siblings):
@@ -1576,13 +1588,21 @@ def _operation_scope(root, feature, siblings):
     return mine, others, commit
 
 
-def _operations_note(mine, others):
-    """One prompt-ready line: this feature's operations and the ones that are not its own."""
+def _operations_note(mine, others, ids=None):
+    """One prompt-ready line: this feature's operations and the ones that are not its own.
+    `ids` ({operation: [id, …]}) names the id each is published under in the API
+    document, which a plan's endpoint carries verbatim as its Operation id."""
     if not mine:
         return ("The boundary map records no operation list for this feature: scope its user "
                 "stories by the feature itself, and treat an operation whose folder or name "
                 "belongs to another feature as that feature's.")
-    line = "This feature's operations (the confirmed boundary map): %s." % ", ".join(mine)
+    ids = ids or {}
+    line = "This feature's operations (the confirmed boundary map): %s." % ", ".join(
+        o + (" (published as %s)" % ", ".join("`%s`" % i for i in ids[o]) if ids.get(o) else "")
+        for o in mine)
+    if any(ids.get(o) for o in mine):
+        line += (" A published id is the API document's operationId: an endpoint's Operation "
+                 "id in a plan is that id, copied exactly.")
     if others:
         line += (" Operations that belong ONLY to another feature over the same aggregate — "
                  "not this feature's: %s." % "; ".join(
@@ -1649,7 +1669,7 @@ def cmd_feature_aggregates(args):
     mine, others, commit = _operation_scope(root, r["feature"], r["shared_with"])
     r.update({"operations": mine, "operations_csv": ", ".join(mine),
               "sibling_operations": others,
-              "operations_note": _operations_note(mine, others),
+              "operations_note": _operations_note(mine, others, _published_ids(root)),
               "baseline_commit": commit, "baseline_time": _commit_time(root, commit)})
     print(f"[xref] feature-aggregates {r['feature']}: acts on {r['aggregates_csv']} "
           f"(from {r['source']}); owns {r['owned_csv']}; {len(mine)} operation(s)", file=sys.stderr)

package/assets/.appweaver/templates/okf-concept-template.md

@@ -75,7 +75,9 @@ ui_source_files:
 
   The grouping is DERIVED from the paths by _group_source_files (aw-xref.py) and
   re-derived on every write (tests → a `tests` bucket; repo-root files → `(root)`), so
-  never hand-maintain the comment headers.
+  never hand-maintain the comment headers. Every list here is also read in YAML's flow
+  form (`features: [A, B]`, `ui_source_files: []`); the next script write turns it into
+  the block form above.
 
   `ui_source_files` is the SAME shape for the slice's FRONTEND surface — the components,
   routes, stores and stylesheets that serve this aggregate — and it is a separate key

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

@@ -20,8 +20,9 @@
        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.
+     `scanned` says what was read, lane by lane, and names each declared lane whose lane
+     root folder does not exist yet; `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`. -->
@@ -41,10 +42,10 @@ 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 |
+| **Bounded context** | a boundary with its own model and language | `specs/<Context>/` and its one `domain-model.md` | the module folder — one per context, named in PascalCase (`care/` → `Care`), read below a Java or Kotlin package's base package (`com/acme/clinic/care/` → `Care`); a tree organised by layer alone (`src/controllers/`, `src/models/`) has no context folder and is one context, `Core` |
 | **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 |
+| **Feature** | a capability the developer chose | `specs/<Context>/<Feature>/spec.md` | the UI lane's `features/<Feature>/` folder, named verbatim — or, in a frontend without one, its own module, route or page folders |
+| **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); a command/query handler class; a use case (`RecordEncounterUseCase`, an `…Interactor`); or an endpoint — a controller action, an annotated or decorated handler, a router call — named by the operation id it publishes, else by what it invokes, else by its handler |
 
 - A feature lives in **exactly one** bounded context.
 - An operation is **not** a user story. A story usually needs several operations (record
@@ -91,9 +92,9 @@ 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 |
+| `domain` | the aggregate roots the code **declares** — a type deriving from an aggregate-root base, embedding one (a Go struct), 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 the command/query handlers, use cases and endpoints 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 (`domain/`, `controllers/`, `routes/`, `routers/`, Go's `http/` or `transport/`, hexagonal `adapters/` and `ports/`, and `web/` or `service/` beside a `domain/` or `models/` folder), a layer carried as a project-name suffix, or a layer at the top with the module repeated as a noun — read from the file name, singular and in PascalCase (`routes/medication_orders.py` → `MedicationOrder`, `IPatientRepository.cs` → `Patient`). An entry point (`main.go`, `Program.cs`, `index.js`, `__init__.py`) names no module unless it sits in a domain folder. An application with no module folders (one project or base package holding the layers) is read the same way, each file joining the domain noun its name contains (`RecordEncounterUseCase` → `Encounter`); an infrastructure or helper file naming none of them (`Data/ClinicDbContext.cs`) serves every aggregate and is left unplaced. Shared code (`shared/`, `common/`, a shared kernel) and the files of a project root that holds modules (its manifest, entry point and wiring) belong to no module and are left unplaced | always |
+| `reference` | the `using` / `import` / `require` graph, clustered after removing the high-fan-in nodes that are shared kernel rather than features. A file no import touches takes its `structure` module, and what `structure` leaves unplaced (shared code, a project root's manifest and entry point) stays unplaced | enough import-parseable source |
 | `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
@@ -105,7 +106,21 @@ 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.
+`@GetMapping`, `@router.post`, `app.get(…)`, `r.Post(…)`), joined to the prefix its
+controller, router or route group declares, the aggregate it acts on, and whether it
+creates one. A controller with no route declarations is read by convention,
+`/<controller>/<action>`. A route made only of infrastructure words — a health, liveness or
+readiness probe, a ping, a status or version report (`/healthz`, `/api/health`,
+`/health/ready`, `/ping`) — serves the platform and is never an operation, and a UI call
+to one links nothing; a resource's own `/status` (`/care/encounters/{id}/status`) is
+read as usual. Each operation also carries the id it is **published** under
+in the API document, verbatim — declared beside its endpoint (`.WithName`,
+`@Operation(operationId = …)`, `operation_id=`, a route `Name`), or by route in an OpenAPI
+or Swagger document or the doc comments the lane keeps (swagger-jsdoc, swag). What the
+code declares wins: a document fills only an operation whose code declares no id, and
+two documents that disagree are both shown. An operation published under none shows
+`—`; an id is never made up. An id names its operation in PascalCase
+(`record_encounter` → `RecordEncounter`) and is shown verbatim.
 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.
 
@@ -113,7 +128,16 @@ on one aggregate is a split candidate** — proposed below, never applied.
 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;
+   operations it calls and acting on those operations' aggregates. A call reaches an
+   operation by its route — the verb and path the frontend calls, in the folder's own
+   files or through the API function, client or service it imports, against the routes
+   the service lane declares; parameters (`{id}`, `{id:guid}`, `:id`, `${id}`) read
+   alike and a leading `api/` or version segment is ignored. An imported function or
+   the folder itself named after an operation links it too. A call no service route
+   matches is listed under **Needs a decision**. A frontend with no
+   `features/` folder is read from the first of its own feature folders that exists —
+   `modules/`, `app/` route segments (Next.js, Angular), `pages/` (React, Nuxt, Blazor),
+   `views/` (Vue), `routes/` (SvelteKit, Remix) — each folder name made PascalCase;
 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 —
@@ -124,11 +148,24 @@ evidence that names one:
 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.
 
+**A project with no service lane** — a front end whose API lives in another repository —
+is read from its UI lane alone (strategy `ui`). The API resources it calls are the
+aggregates it works on (`/care/encounters/…` → `Encounter`), each distinct call is an
+operation, and a leading route segment that every route under it follows with a resource
+(`/care/encounters`, `/care/medication-orders`) is a bounded context; one context, `Core`,
+holds the rest. A feature acts on what it calls, in its own files or
+through the API function, client or service it imports.
+
+**A lane declared before it is built** — its lane root folder does not exist yet — is read as
+if it were not declared, and the Scanned line above names it. A service lane not built yet
+reads the project from its UI lane, as above; a UI lane not built yet leaves the features to
+the service lane's evidence.
+
 ## Strategy probe
 
 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.
+marked; re-run `/appweaver inventory <name>` to build the map from another.
 
 {probe_table}
 
@@ -159,8 +196,10 @@ when it is the only feature on that aggregate.
 {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.
+Every operation the scan found, what it acts on, the id it is published under, and the
+feature(s) it serves. `adopt` hands the published id to the feature's plans, whose
+endpoints carry it as their Operation id. Read-only — move an operation by editing the
+Operations cells above.
 
 {operation_table}
 {unplaced_section}

package/assets/foundations/java/Hexagonal/unpack-foundation.ps1

@@ -0,0 +1,168 @@
+#requires -Version 5.1
+<#
+.SYNOPSIS
+    Unpack an AW-Spec Java foundation pack into a target application, replacing the Java
+    package sentinel with the target application's package.
+
+.DESCRIPTION
+    Windows / PowerShell mirror of unpack-foundation.sh.
+
+    Reads -PackFile, takes the sentinel from its header (override with -Sentinel) and writes
+    every <<<DIR>>> and <<<FILE>>> block under -OutDir with the sentinel rewritten in both
+    file CONTENTS and file/dir PATHS:
+
+        io.appweaver  ->  <lowercase application name>     (contents)
+        io/appweaver  ->  <lowercase application name>     (paths)
+
+    The pack is the Maven module itself (pom.xml, mvnw, src/main/java, src/test/java) and
+    lands in -OutDir exactly as packed: that directory IS the module. Text blocks are
+    written as UTF-8 (no BOM, LF); base64 blocks are decoded as-is. Refuses to overwrite
+    existing files unless -Force; the check also runs under -DryRun, so a non-zero exit from
+    a dry run tells the orchestrator that collisions exist.
+
+.EXAMPLE
+    ./unpack-foundation.ps1 -PackFile ./Hexagonal.pack.txt -TargetAppName FlightBooking -OutDir backend
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)] [string] $PackFile,
+    [Parameter(Mandatory)] [string] $TargetAppName,
+    [string] $OutDir = 'src',
+    [string] $Sentinel,
+    [switch] $Force,
+    [switch] $DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+
+# --- validate args ---
+if (-not (Test-Path -LiteralPath $PackFile -PathType Leaf)) { throw "Pack file not found: $PackFile" }
+if ($TargetAppName -cnotmatch '^[A-Za-z0-9._-]+$') {
+    throw "Invalid application name '$TargetAppName'. Allowed characters: A-Z a-z 0-9 . _ -"
+}
+
+$pack  = (Resolve-Path -LiteralPath $PackFile).Path
+$lines = ([System.IO.File]::ReadAllText($pack)) -split "`r?`n"
+
+# --- sentinel from header unless overridden ---
+if (-not $Sentinel) {
+    foreach ($l in $lines) {
+        if ($l -match '^#\s*sentinel:\s*(.+?)\s*$') { $Sentinel = $Matches[1]; break }
+    }
+}
+if (-not $Sentinel) { throw "Could not determine sentinel from pack. Use -Sentinel." }
+
+# --- Java replacement: dotted and slashed forms of the sentinel -> lowercase app name ---
+# NOTE: an array of pairs, not a hashtable — hashtable keys are case-INSENSITIVE in PowerShell.
+$targetPackage = $TargetAppName.ToLowerInvariant()
+$forms = @(
+    @{ From = $Sentinel;                          To = $targetPackage }
+    @{ From = ($Sentinel -replace '\.', '/');     To = $targetPackage }
+)
+$replacements = @()
+$seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::Ordinal)
+foreach ($pair in $forms) {
+    $from = [string]$pair.From
+    if ([string]::IsNullOrEmpty($from)) { continue }
+    if (-not $seen.Add($from)) { continue }    # ordinal dedupe of identical From tokens
+    $replacements += [pscustomobject]@{ From = $from; To = [string]$pair.To }
+}
+# longest token first so overlaps resolve correctly
+$replacements = @($replacements | Sort-Object { $_.From.Length } -Descending)
+
+function Apply-Repl([string] $text) {
+    foreach ($r in $replacements) { $text = $text.Replace($r.From, $r.To) }
+    return $text
+}
+
+# --- output root (not created until a real run) ---
+if ([System.IO.Path]::IsPathRooted($OutDir)) { $outRoot = $OutDir }
+else { $outRoot = Join-Path (Get-Location).Path $OutDir }
+$outRoot = [System.IO.Path]::GetFullPath($outRoot)
+$sep     = [System.IO.Path]::DirectorySeparatorChar
+
+# --- parse pack blocks ---
+$files   = @()
+$dirRels = @()
+$i = 0
+while ($i -lt $lines.Count) {
+    if ($lines[$i] -match '^<<<FILE path="([^"]+)"(?:\s+encoding="(\w+)")?>>>\s*$') {
+        $rel = $Matches[1]; $enc = $Matches[2]
+        $i++
+        $buf = New-Object System.Collections.Generic.List[string]
+        while ($i -lt $lines.Count -and $lines[$i] -ne '<<<ENDFILE>>>') {
+            $buf.Add($lines[$i]); $i++
+        }
+        $files += [pscustomobject]@{ Rel = $rel; Enc = $enc; Content = ($buf -join "`n") }
+    }
+    elseif ($lines[$i] -match '^<<<DIR path="([^"]+)">>>\s*$') {
+        $dirRels += $Matches[1]
+    }
+    $i++
+}
+if ($files.Count -eq 0) { throw "No <<<FILE>>> blocks found in pack: $pack" }
+
+function Resolve-Dest([string] $rel) {
+    $renamed = Apply-Repl $rel
+    foreach ($seg in ($renamed -split '[\\/]')) {
+        if ($seg -eq '..') { throw "Refusing path outside the output folder: $rel" }
+    }
+    if ([System.IO.Path]::IsPathRooted($renamed)) { throw "Refusing absolute path in pack: $rel" }
+    return (Join-Path $outRoot $renamed.Replace('/', $sep))
+}
+
+# The pack carries the empty Java package parents (src/main/java/io, src/test/java/io);
+# once io.appweaver is renamed they would be left behind empty, so they are not created.
+$skipDirs = @('src/main/java/io', 'src/test/java/io')
+$dirDests = @()
+foreach ($d in $dirRels) {
+    if ($skipDirs -contains $d) { continue }
+    $dirDests += (Resolve-Dest $d)
+}
+
+$fileDests = @($files | ForEach-Object { Resolve-Dest $_.Rel })
+
+# --- conflict guard (also under -DryRun: a non-zero exit there means "collisions exist") ---
+if (-not $Force) {
+    $conflicts = @($fileDests | Where-Object { Test-Path -LiteralPath $_ })
+    if ($conflicts.Count -gt 0) {
+        throw ("Destination already exists (use -Force to overwrite):`n  " + ($conflicts -join "`n  "))
+    }
+}
+
+# --- directories, then files ---
+$directoriesCreated = 0
+foreach ($d in $dirDests) {
+    if ($DryRun) { Write-Host "WOULD CREATE DIRECTORY  $d"; continue }
+    New-Item -ItemType Directory -Force -Path $d | Out-Null
+    $directoriesCreated++
+}
+
+$utf8 = [System.Text.UTF8Encoding]::new($false)
+$written = 0
+for ($n = 0; $n -lt $files.Count; $n++) {
+    $f    = $files[$n]
+    $dest = $fileDests[$n]
+    if ($DryRun) { Write-Host "WOULD WRITE  $dest"; continue }
+    $destDir = Split-Path -Parent $dest
+    if ($destDir -and -not (Test-Path -LiteralPath $destDir)) {
+        New-Item -ItemType Directory -Force -Path $destDir | Out-Null
+    }
+    if ($f.Enc -eq 'base64') {
+        [System.IO.File]::WriteAllBytes($dest, [Convert]::FromBase64String(($f.Content -replace '\s', '')))
+    } else {
+        [System.IO.File]::WriteAllText($dest, ((Apply-Repl $f.Content) + "`n"), $utf8)
+    }
+    $written++
+}
+
+# --- summary ---
+Write-Host ''
+if ($DryRun) {
+    Write-Host "DryRun: $($files.Count) file(s) and $($dirRels.Count) directorie(s) would be written to:"
+} else {
+    Write-Host "Unpacked $written file(s) and $directoriesCreated directorie(s) to:"
+}
+Write-Host "  $outRoot"
+Write-Host "  Sentinel: $Sentinel"
+Write-Host "  Package:  $targetPackage"

package/package.json

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