aw-spec-cli 0.1.20 → 0.1.22

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

@@ -749,6 +749,29 @@ def _referrer_closure(aggregate, bundle_abs):
     return sorted(seen)
 
 
+def _has_code(name, bundle_abs):
+    """Does this aggregate have code on disk yet?
+
+    "Depends on me" and "has code that could break" are different questions, and the
+    closure alone answers only the first. Edges come from the PLAN — a feature that has
+    been planned and not implemented is a genuine dependant with nothing to re-test, and
+    `record` stubs a used sibling's concept when it has none, so its name enters the
+    closure either way. `source_files` is the difference: a stub is written with it empty
+    and implement's concept-upsert fills it from what it generated.
+    """
+    path = _resolve_concept(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[]"))
+
+
 def _concept_title(path):
     fm, _ = _read_fm(_read(path))
     t = fm.get("title") if isinstance(fm.get("title"), str) else ""
@@ -995,15 +1018,30 @@ def cmd_list(args):
     closure = []
     for agg in aggregates:
         closure.extend(c for c in _referrer_closure(agg, bundle_abs) if c not in closure)
+    # THE CLOSURE ANSWERS TWO QUESTIONS AND A CALLER USUALLY WANTS ONE. Edges are read off
+    # the PLAN, so a dependant can be fully planned and hold no code at all. A caller that
+    # re-runs TESTS over the blast radius wants `built`: an unbuilt dependant has nothing
+    # to run, and selecting it turns a fence into a failure over an empty test set. A
+    # caller reporting what this change reaches wants the whole closure, with `unbuilt`
+    # named so nobody reads its absence from a test run as "unaffected".
+    built = [c for c in closure if _has_code(c, bundle_abs)]
+    unbuilt = [c for c in closure if c not in built]
     print(f"[xref] {', '.join(aggregates)}: {len(users)} downstream user(s) "
-          f"— {', '.join(sorted({u['using'] for u in users})) or '(none)'}", file=sys.stderr)
+          f"— {', '.join(sorted({u['using'] for u in users})) or '(none)'}"
+          + (f"; {len(unbuilt)} planned but not implemented — {', '.join(unbuilt)}"
+             if unbuilt else ""), file=sys.stderr)
     _emit({"aggregate": aggregate, "aggregates": aggregates,
            "concept": _rel(path, root) if path else "",
            "users": users, "count": len(users), "impact_report": out_rel, "root": root,
            "referrers": direct, "referrers_csv": ",".join(direct),
            "referrer_closure": closure, "referrer_closure_csv": ",".join(closure),
            "referrer_count": len(direct), "referrer_closure_count": len(closure),
-           "indirect_count": max(0, len(closure) - len(direct))})
+           "indirect_count": max(0, len(closure) - len(direct)),
+           # The closure split by whether the dependant has code yet.
+           "built_closure": built, "built_closure_csv": ",".join(built),
+           "built_count": len(built),
+           "unbuilt_closure": unbuilt, "unbuilt_closure_csv": ",".join(unbuilt),
+           "unbuilt_count": len(unbuilt)})
     return 0
 
 
@@ -1229,15 +1267,39 @@ def cmd_concept_paths(args):
                 missing = [s for s in mapped if s not in existing]
                 scope = "feature"
 
+    # NARROWED TO ONE LANE'S SUBTREES. A concept spans every lane that realises the
+    # aggregate — on a fullstack feature that is the service files AND the web files in
+    # one list. A caller generating one lane must not be handed the other's: `implement`
+    # tells each lane to read the code it is about to extend, and a backend pass shown the
+    # UI's files is being invited to touch a subtree it is forbidden to write. Absent, the
+    # whole list stands, which is what every existing caller wants.
+    under = [u.strip().replace(os.sep, "/").lstrip("./") for u in (args.under or []) if u and u.strip()]
+    under = [u if u.endswith("/") else u + "/" for u in under]
+    scoped_out = 0
+    if under:
+        def inside(p):
+            q = p.replace(os.sep, "/").lstrip("./")
+            return any(q.startswith(u) for u in under)
+        before = len(existing)
+        existing = [p for p in existing if inside(p)]
+        declared = [p for p in declared if inside(p)]
+        missing = [p for p in missing if inside(p)]
+        scoped_out = before - len(existing)
+
     note = "" if path else " — no concept recorded yet"
     drift = f", {len(missing)} declared-but-missing" if missing else ""
-    print(f"[xref] concept-paths {aggregate}: {len(existing)} file(s) on disk{drift}{note}"
+    narrowed = f", {scoped_out} outside {' '.join(under)}" if scoped_out else ""
+    print(f"[xref] concept-paths {aggregate}: {len(existing)} file(s) on disk{drift}{narrowed}{note}"
           f" (scope: {scope})", file=sys.stderr)
     _emit({"aggregate": aggregate, "concept": _rel(path, root) if path else "",
            "found": bool(path), "scope": scope, "paths": existing, "count": len(existing),
            "csv": ",".join(existing), "declared": declared,
            "declared_count": len(declared), "missing": missing,
-           "missing_count": len(missing), "root": root})
+           "missing_count": len(missing), "under": under, "excluded_count": scoped_out,
+           # One block per line, for a prompt that lists what the lane already has.
+           "paths_text": "\n".join("  " + p for p in existing) if existing else
+           "  (none — nothing of this aggregate is on disk in this lane yet)",
+           "root": root})
     return 0
 
 
@@ -1418,6 +1480,70 @@ def _resolve_feature(fd, root):
             "shared_with": shared_with, "shared_with_csv": ", ".join(shared_with)}
 
 
+def _crstate():
+    """aw-crstate, loaded by path — it owns the readers for a change's own documents
+    (`**Aggregates touched**`, the model delta beside the master or in its archive) and
+    duplicating them here is how two answers to one question start to drift."""
+    import importlib.util
+    p = os.path.join(os.path.dirname(os.path.abspath(__file__)), "aw-crstate.py")
+    spec = importlib.util.spec_from_file_location("aw_crstate", p)
+    if not spec or not spec.loader:
+        return None
+    mod = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(mod)
+    except Exception:
+        return None
+    return mod
+
+
+def cmd_co_owners(args):
+    """THE FEATURES THAT SHARE THIS CHANGE'S AGGREGATES — the half of a merge's blast
+    radius that referrer edges cannot see.
+
+    `list` answers "who DEPENDS on this aggregate": features that reach it through a
+    Cross-Reference edge, transitively. That is a real blast radius and it is not the whole
+    one. A feature that CO-OWNS the aggregate holds no edge to it at all — it is not a user
+    of `Encounter`, it is one of the capabilities Encounter is made of, and its code lives
+    in the very files this merge rewrites. `Encounter.cs` is extended by every feature that
+    claims Encounter, so a change to it can break a co-owner without touching one referrer.
+
+    SCOPED TO WHAT THE CHANGE TOUCHES, not to everything the feature owns. The delta's own
+    `**Aggregates touched**` header is the authority: a feature owning Encounter and
+    CareTeam whose change touches only Encounter must not drag CareTeam's co-owners through
+    a regression fence they cannot have been affected by. Where that header cannot be read
+    the feature's owned aggregates stand in — wider than needed, never narrower, and
+    `source` says which answer this is so a caller can report it honestly.
+    """
+    root = _root(args.root)
+    fd = args.feature_dir
+    fd_abs = fd if os.path.isabs(fd) else os.path.join(root, fd)
+    feature = _feature_from_dir(fd_abs)
+    ctx = args.context_dir or os.path.dirname(os.path.normpath(fd_abs))
+
+    touched, source = [], "delta"
+    cs = _crstate() if args.cr else None
+    if cs:
+        touched = sorted(cs.aggregates(cs.model_delta_of(ctx, args.cr)))
+    if not touched:
+        # No readable model delta: a spec-only change, or a header this cannot parse.
+        touched = _resolve_feature(fd_abs, root)["owned"]
+        source = "feature-owned"
+
+    own = {_key(a) for a in touched}
+    features = sorted({v["feature"] for v in _feature_index(root).values()
+                       if _key(v["feature"]) != _key(feature)
+                       and own & {_key(a) for a in v["claims"]}}, key=str.lower)
+
+    print(f"[xref] co-owners {feature}: {len(features)} feature(s) share "
+          f"{', '.join(touched) or '(no aggregate)'} (source: {source})", file=sys.stderr)
+    _emit({"feature": feature, "cr_id": args.cr, "source": source,
+           "aggregates": touched, "aggregates_csv": ", ".join(touched),
+           "features": features, "features_csv": ", ".join(features),
+           "count": len(features), "root": root})
+    return 0
+
+
 def cmd_feature_aggregates(args):
     """WHICH AGGREGATE(S) A FEATURE ACTS ON — the name every command that reads the
     bounded context's domain-model.md needs, because the model is organised by
@@ -1826,10 +1952,21 @@ def main(argv):
     cp = sub.add_parser("concept-paths", help="read-only: the slice's source_files (replaces design-paths)")
     cp.add_argument("--aggregate", default="")
     cp.add_argument("--feature-dir", dest="feature_dir", default="")
+    cp.add_argument("--under", action="append", default=[],
+                    help="keep only paths inside this subtree; repeatable. Omitted, every "
+                         "path the concept records is returned.")
     cp.add_argument("--root", default="")
     cp.add_argument("--bundle", default="knowledge")
     cp.set_defaults(func=cmd_concept_paths)
 
+    cw = sub.add_parser("co-owners", help="read-only: the features that SHARE this change's aggregates (no referrer edge, same files)")
+    cw.add_argument("--cr", default="", help="the change id; its **Aggregates touched** scopes the answer")
+    cw.add_argument("--feature-dir", dest="feature_dir", default="")
+    cw.add_argument("--context-dir", dest="context_dir", default="",
+                    help="the bounded context directory; defaults to the feature dir's parent")
+    cw.add_argument("--root", default="")
+    cw.set_defaults(func=cmd_co_owners)
+
     fa = sub.add_parser("feature-aggregates", help="read-only: the aggregate(s) a feature acts on — spec, then the boundary map, then the feature name")
     fa.add_argument("--feature-dir", dest="feature_dir", default="")
     fa.add_argument("--root", default="")

package/assets/.appweaver/stack-profiles/angular.json

@@ -12,5 +12,31 @@
   "prototype_run": "npm start --prefix prototype",
   "detect": [
     "web/angular.json"
+  ],
+  "reserved_names": [
+    "Array",
+    "Date",
+    "Document",
+    "Element",
+    "Error",
+    "Event",
+    "Headers",
+    "History",
+    "Image",
+    "Location",
+    "Map",
+    "Node",
+    "Notification",
+    "Object",
+    "Option",
+    "Range",
+    "Record",
+    "Request",
+    "Response",
+    "Selection",
+    "Set",
+    "Storage",
+    "Text",
+    "Worker"
   ]
 }

package/assets/.appweaver/stack-profiles/blazor-wasm.json

@@ -13,5 +13,43 @@
   "detect": [
     "web/**/*.csproj",
     "web/**/wwwroot/index.html"
+  ],
+  "reserved_names": [
+    "Activity",
+    "Array",
+    "Attribute",
+    "Buffer",
+    "Comparer",
+    "Convert",
+    "Delegate",
+    "Dictionary",
+    "Directory",
+    "Endpoint",
+    "Environment",
+    "Exception",
+    "File",
+    "Guid",
+    "Index",
+    "List",
+    "Lock",
+    "Math",
+    "Object",
+    "Path",
+    "Progress",
+    "Queue",
+    "Random",
+    "Range",
+    "Results",
+    "Route",
+    "Stack",
+    "Stream",
+    "String",
+    "Task",
+    "Thread",
+    "Timer",
+    "Tuple",
+    "Type",
+    "Uri",
+    "Version"
   ]
 }

package/assets/.appweaver/stack-profiles/dotnet-webapi.json

@@ -5,11 +5,50 @@
   "language": "C#",
   "ecosystem": "dotnet",
   "root": "src/",
+  "test_root": "tests/",
   "build": "dotnet build",
   "test": "dotnet test",
   "run": "dotnet run --project {{root}}",
   "detect": [
     "*.sln",
     "src/**/*.csproj"
+  ],
+  "reserved_names": [
+    "Activity",
+    "Array",
+    "Attribute",
+    "Buffer",
+    "Comparer",
+    "Convert",
+    "Delegate",
+    "Dictionary",
+    "Directory",
+    "Endpoint",
+    "Environment",
+    "Exception",
+    "File",
+    "Guid",
+    "Index",
+    "List",
+    "Lock",
+    "Math",
+    "Object",
+    "Path",
+    "Progress",
+    "Queue",
+    "Random",
+    "Range",
+    "Results",
+    "Route",
+    "Stack",
+    "Stream",
+    "String",
+    "Task",
+    "Thread",
+    "Timer",
+    "Tuple",
+    "Type",
+    "Uri",
+    "Version"
   ]
 }

package/assets/.appweaver/stack-profiles/java-spring.json

@@ -5,6 +5,7 @@
   "language": "Java",
   "ecosystem": "java",
   "root": "src/main/java/",
+  "test_root": "src/test/java/",
   "run_from": "root",
   "build": "./mvn clean install",
   "test": "./mvn test",
@@ -12,5 +13,24 @@
   "detect": [
     "pom.xml",
     "build.gradle"
+  ],
+  "reserved_names": [
+    "Character",
+    "Class",
+    "Enum",
+    "Error",
+    "Exception",
+    "Integer",
+    "Module",
+    "Number",
+    "Object",
+    "Package",
+    "Process",
+    "Record",
+    "Runtime",
+    "String",
+    "System",
+    "Thread",
+    "Void"
   ]
 }

package/assets/.appweaver/stack-profiles/nextjs.json

@@ -12,5 +12,31 @@
   "prototype_run": "npm run dev --prefix prototype",
   "detect": [
     "web/next.config.*"
+  ],
+  "reserved_names": [
+    "Array",
+    "Date",
+    "Document",
+    "Element",
+    "Error",
+    "Event",
+    "Headers",
+    "History",
+    "Image",
+    "Location",
+    "Map",
+    "Node",
+    "Notification",
+    "Object",
+    "Option",
+    "Range",
+    "Record",
+    "Request",
+    "Response",
+    "Selection",
+    "Set",
+    "Storage",
+    "Text",
+    "Worker"
   ]
 }

package/assets/.appweaver/stack-profiles/node-express.json

@@ -5,11 +5,38 @@
   "language": "Node.js",
   "ecosystem": "node",
   "root": "src/",
+  "test_root": "tests/",
   "build": "npm run build",
   "test": "npm test",
   "run": "npm run dev",
   "detect": [
     "package.json",
     "src/**/*.ts"
+  ],
+  "reserved_names": [
+    "Array",
+    "Date",
+    "Document",
+    "Element",
+    "Error",
+    "Event",
+    "Headers",
+    "History",
+    "Image",
+    "Location",
+    "Map",
+    "Node",
+    "Notification",
+    "Object",
+    "Option",
+    "Range",
+    "Record",
+    "Request",
+    "Response",
+    "Selection",
+    "Set",
+    "Storage",
+    "Text",
+    "Worker"
   ]
 }

package/assets/.appweaver/stack-profiles/python-fastapi.json

@@ -5,6 +5,7 @@
   "language": "Python",
   "ecosystem": "python",
   "root": "app/",
+  "test_root": "tests/",
   "build": "python -m compileall {{root}}",
   "test": "pytest",
   "run": "uvicorn app.main:app --reload",
@@ -12,5 +13,20 @@
     "pyproject.toml",
     "requirements.txt",
     "app/main.py"
+  ],
+  "reserved_names": [
+    "Any",
+    "Callable",
+    "Dict",
+    "Generator",
+    "Iterator",
+    "List",
+    "Mapping",
+    "Optional",
+    "Sequence",
+    "Set",
+    "Text",
+    "Type",
+    "Union"
   ]
 }

package/assets/.appweaver/stack-profiles/react-vite.json

@@ -13,5 +13,31 @@
   "detect": [
     "web/package.json",
     "web/vite.config.*"
+  ],
+  "reserved_names": [
+    "Array",
+    "Date",
+    "Document",
+    "Element",
+    "Error",
+    "Event",
+    "Headers",
+    "History",
+    "Image",
+    "Location",
+    "Map",
+    "Node",
+    "Notification",
+    "Object",
+    "Option",
+    "Range",
+    "Record",
+    "Request",
+    "Response",
+    "Selection",
+    "Set",
+    "Storage",
+    "Text",
+    "Worker"
   ]
 }

package/assets/.appweaver/stack-profiles/sveltekit.json

@@ -12,5 +12,31 @@
   "prototype_run": "npm run dev --prefix prototype",
   "detect": [
     "web/svelte.config.*"
+  ],
+  "reserved_names": [
+    "Array",
+    "Date",
+    "Document",
+    "Element",
+    "Error",
+    "Event",
+    "Headers",
+    "History",
+    "Image",
+    "Location",
+    "Map",
+    "Node",
+    "Notification",
+    "Object",
+    "Option",
+    "Range",
+    "Record",
+    "Request",
+    "Response",
+    "Selection",
+    "Set",
+    "Storage",
+    "Text",
+    "Worker"
   ]
 }

package/assets/.appweaver/stack-profiles/vue-vite.json

@@ -13,5 +13,31 @@
   "detect": [
     "web/vite.config.*",
     "web/src/App.vue"
+  ],
+  "reserved_names": [
+    "Array",
+    "Date",
+    "Document",
+    "Element",
+    "Error",
+    "Event",
+    "Headers",
+    "History",
+    "Image",
+    "Location",
+    "Map",
+    "Node",
+    "Notification",
+    "Object",
+    "Option",
+    "Range",
+    "Record",
+    "Request",
+    "Response",
+    "Selection",
+    "Set",
+    "Storage",
+    "Text",
+    "Worker"
   ]
 }

package/assets/.appweaver/templates/constitution-domain-template.md

@@ -7,8 +7,8 @@
   project reverse-engineered by `onboard` that map points at the project's OWN generated
   domain rule files and its own charter, both derived from the code — same partition, a
   different corpus. It carries ONLY domain-specific material:
-  the domain principles, domain identifiers/terminology, regulatory regime,
-  interoperability surfaces, and domain governance overrides.
+  the project identity, the domain principles, domain identifiers/terminology, regulatory
+  regime, interoperability surfaces, and domain governance overrides.
 
   ══ THIS FILE IS SHAPE. THE MAPPED CORPUS IS CONTENT. ═════════════════════════════
   This template is part of the kit and governs projects in any industry. It therefore
@@ -35,6 +35,21 @@
   the detail. That keeps the authority/detail overlap to one line.
 -->
 
+## Project Identity
+
+[PROJECT_IDENTITY_CONTENT]
+<!--
+  Form: what this project IS in its domain — the regulated role it plays, the bounded
+  contexts it is organised into, and who consumes it and through what surface — each as a
+  short labelled line. Take them from the mapped charter's own identity section. Where the
+  project's domain-requirements states a different value (a different context list, a
+  narrower role), the project value is a DEVIATION: ratify it here, naming the charter line
+  it departs from and who approved it.
+
+  This section exists because specify loads THIS file and not the charter, so it is the
+  only way the project's contexts and consumers reach specify.
+-->
+
 ## Adopted Modelling Standard
 
 [MODELLING_STANDARD_STATEMENT]

package/assets/.appweaver/templates/ui-model-template.md

@@ -0,0 +1,67 @@
+# UI Model: [Feature Name]
+
+**Aggregate (feature)**: `[Aggregate]`
+**Spec Reference**: `specs/[Aggregate]/spec.md`
+**Workflow Reference**: `specs/[Aggregate]/ui/workflow-model.md`
+**Version**: v1.0
+**Status**: Active
+
+## Overview
+
+[Information architecture mapping user workflows into concrete UI surfaces, routes, interaction states, and component hierarchy.]
+
+## UI Surfaces
+
+### Surface 1: [Surface Title — e.g. Project Directory & Workspace]
+
+- **Surface Type**: `Page` | `Sub-Page` | `Dialog` | `Drawer` | `Modal` | `View`
+- **Route / Mount Path**: `/projects`
+- **Supported Workflows**: [WF-1, WF-2]
+- **Target Personas**: [Project Manager, PMO Member]
+- **Required Interaction States**:
+  - `Loading`: Skeleton placeholders during data retrieval
+  - `Empty`: Zero-state graphic with call-to-action
+  - `Populated`: Structured table / card layout displaying primary entities
+  - `Filtered / Searched`: Dynamic filtering view
+  - `Error`: Inline error notification banner
+- **User Actions & Events**:
+  - Search & filter inputs
+  - Action trigger (e.g. "Create Project" → opens Surface 2)
+  - Row item selection (→ opens Surface 3)
+- **Transitions**:
+  - `On Click [Action]` → Navigates to or opens `[Surface Name]`
+
+---
+
+### Surface 2: [Surface Title — e.g. Create Project Form]
+
+- **Surface Type**: `Drawer` | `Dialog` | `Page`
+- **Route / Mount Path**: `/projects/create` (or Modal on `/projects`)
+- **Supported Workflows**: [WF-1]
+- **Target Personas**: [Project Manager]
+- **Required Interaction States**:
+  - `Initial / Ready`: Blank form with active validation rules
+  - `Validation Error`: Inline field error callouts (e.g. invalid date range)
+  - `Submitting`: Button loading spinner with disabled inputs
+  - `Success`: Dismisses modal & appends item to active list with toast confirmation
+- **User Actions & Events**:
+  - Input fields & attachment uploads
+  - Submit & Cancel controls
+- **Transitions**:
+  - `On Submit Success` → Return to `Surface 1` (Populated state)
+  - `On Cancel` → Close surface without saving
+
+---
+
+### Surface 3: [Surface Title — e.g. Action Confirmation Modal]
+
+- **Surface Type**: `Dialog`
+- **Supported Workflows**: [WF-3]
+- **Target Personas**: [Authorized Roles]
+- **Required Interaction States**:
+  - `Prompt`: Mandatory confirmation text & action buttons
+  - `Executing`: Disables actions during execution
+- **User Actions & Events**:
+  - Confirm & Cancel buttons
+- **Transitions**:
+  - `On Confirm` → Execute state transition & update parent surface UI