aw-spec-cli 0.1.19 → 0.1.21

package/assets/.appweaver/orchestrator/workflows/aw-spec-inventory.orch.yaml

@@ -1,37 +1,52 @@
 # =============================================================================
-# aw-spec-inventory (orchestrator) — B0 of the Brownfield Pipeline
+# aw-spec-inventory (orchestrator) — brownfield discovery
 #
-# The reverse front-end's first phase (see Brownfield-Pipeline.md). Scan
-# an EXISTING codebase, propose AGGREGATE-ROOT boundaries + dependency seams,
-# and emit an aggregate-organized OKF v0.1 knowledge bundle + a migration
-# backlog. Each candidate aggregate is a future specs/<Feature>/ vertical slice —
-# this bundle is the BASE the forward brownfield steps read to reverse-engineer
-# spec.md + backend-plan.md per slice.
+# The first command of the brownfield sequence after select-stack. It answers
+# one question and writes it down: WHICH FEATURES AND BOUNDED CONTEXTS does this
+# codebase contain, and in what order can they be onboarded?
 #
-#   INVENTORY  → adopt → (fidelity) → characterize → [ forward pipeline ]   ← you are here
+#   select-stack → INVENTORY → [edit the proposal] → inventory apply
+#                              → onboard <BoundedContext> (once per context)
+#                                                          ← you are here
 #
-# Two-part shape, mirroring the OKF generate flow:
-#   1. a DETERMINISTIC scan (aw-inventory.py scan) → the factual JSON substrate
-#      (files, languages, churn, entrypoints, data/route/api files, and
-#      aggregate_signals = candidate roots clustered by vertical-slice layout);
-#   2. an ENRICHMENT agent that turns that substrate into the OKF bundle,
-#      organized BY AGGREGATE ROOT, then a conformance gate (validate_okf.py).
+# Three passes over the code. The generated document explains each of them to the
+# operator reading it; the wording lives in the template
+# .appweaver/templates/proposed-inventory-template.md, overridable per project:
+#   A  aggregate identification — what must stay consistent together. Three
+#      strategies (structure / reference graph / persistence), each offered only
+#      where the evidence for it exists, each reporting its own numbers.
+#   B  the seam overlay — what can be cut over together. Always runs, over
+#      application/API/UI only. Emits signals, never decisions.
+#   C  the proposal — 1:1 aggregate-to-feature by default, splits proposed with
+#      their evidence and never applied, grouped into bounded contexts and
+#      ordered into dependency waves.
 #
-# It does NOT author spec.md / backend-plan.md (that is /appweaver adopt per slice)
-# and does NOT touch source code — all writes stay inside the bundle dir.
+# The deliverable is `specs/proposed-inventory.md` — an EDITABLE document. The
+# operator renames, moves, merges, splits and re-orders in that file, then runs
+# `/appweaver inventory apply`, which validates every edit and regenerates the
+# machine map `.appweaver/inventory/feature-map.json` that onboard reads.
 #
-# Launch:  /appweaver inventory [strategy] [focus/scope hints]
+# It does NOT author specs, plans or governance (that is onboard, per context)
+# and never modifies source.
+#
+# Launch:  /appweaver inventory [structure|reference|persistence] [focus hints]
+#          /appweaver inventory apply
 # =============================================================================
 
 name: aw-spec-inventory
-description: Scan a brownfield codebase and produce an aggregate-organized OKF v0.1 knowledge bundle plus a migration backlog — the base for reverse-engineering spec.md + backend-plan.md per aggregate/vertical slice. Deterministic scan + enrichment agent + conformance gate; never modifies source.
-version: 1.1.0
+description: Brownfield discovery — scan an existing codebase and propose its Features and Bounded Contexts, in dependency order with their dependencies, as an editable specs/proposed-inventory.md. Runs three passes (aggregate identification by a selectable evidence-gated strategy, a seam overlay over application/API/UI, and a 1:1-by-default feature proposal with evidenced splits offered but never applied). `apply` validates the operator's edits and regenerates the machine map onboard consumes. Never modifies source.
+version: 2.0.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
 inputs:
   user_input:
-    description: Optional focus / scope hints (e.g. an area to prioritize, or a granularity note).
+    description: >-
+      Either the literal word `apply` — validate the edited specs/proposed-inventory.md
+      and regenerate the machine map — or an optional Pass A strategy name
+      (structure | reference | persistence) to force, plus free-text focus hints.
+      With no argument, the highest-coverage available strategy is proposed and the
+      operator confirms it from a menu carrying each strategy's measured numbers.
     required: false
     bind: USER_INPUT
 
@@ -43,181 +58,190 @@ scripts:
     sh:  .appweaver/scripts/bash/aw-spec-actions.sh
     ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
 
-# No modelling rule file is loaded. author_bundle states the vocabulary it needs
-# inline — entities, value objects, domain events, the aggregate that OWNS them,
-# and the clean/torn seam test — in terms no stack owns, which is what lets this
-# scan run against an arbitrary codebase. A rule file here would reach every step
-# (this is the sticky set) and would hand the agent one project's house style as
-# the shape to look for.
+# Nothing project-shaped in the sticky set: every pass here is deterministic and
+# reads the code, so no rule file or exemplar has any part to play.
 standards:
   - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
 
 vars:
-  bundle_present: "false"
-  conformant: "false"
+  mode: "propose"          # apply-mode driver
+  strategy: ""             # forced Pass A strategy; empty = probe default
+  feature_count: "0"
+  proposal_ok: "false"
 
 workflow:
 
-  # 1. DETERMINISTIC scan of the current codebase → JSON substrate. Emits the
-  #    factual base (files, churn, categories, aggregate_signals) and reports
-  #    whether the target bundle already holds curation.
-  - id: scan
+  # 0. MODE. The engine compares variables as text and has no compound
+  #    conditions, so the two entry points are separated by one ordered set.
+  - id: mode_apply
+    action: set
+    condition: "{{USER_INPUT}} == apply"
+    vars: { mode: "apply" }
+
+  # ═══════════════════ APPLY — read the operator's edits back ═══════════════
+  # Runs first and stops the workflow, so the propose half never re-derives a
+  # map over the top of an edited one.
+
+  - id: apply_edits
     action: execute_script
+    condition: "{{mode}} == apply"
     script: { ref: inventory }
-    subcommand: scan
+    subcommand: apply
+    on_error: continue
     outputs:
-      - { name: inventory_json,   from: "$.inventory_json" }
-      - { name: root,             from: "$.root" }
-      - { name: head,             from: "$.head" }
-      - { name: file_count,       from: "$.file_count" }
-      - { name: aggregate_count,  from: "$.aggregate_count" }
-      - { name: bundle_dir,       from: "$.bundle_dir" }
-      - { name: bundle_present,   from: "$.bundle_present" }
-      - { name: bundle_md_count,  from: "$.bundle_md_count" }
-
-  # 1b. Substance gate: a scan that found no aggregate candidates has nothing to
-  #     organize a bundle around (empty repo, or no recognizable domain layout).
-  - id: require_aggregates
-    action: verify_context
-    require_true: aggregate_count
-    on_false: stop
-    on_false_message: "Scan found no candidate aggregates in {{root}} (file_count={{file_count}}). Point /appweaver inventory at a codebase with a recognizable domain/vertical-slice layout, or scan a subtree that contains one."
+      - { name: proposal_ok,      from: "$.ok" }
+      - { name: feature_map,      from: "$.feature_map" }
+      - { name: feature_count,    from: "$.feature_count" }
+      - { name: context_count,    from: "$.context_count" }
+      - { name: wave_count,       from: "$.wave_count" }
+      - { name: cycle_count,      from: "$.cycle_count" }
+      - { name: contexts_ordered, from: "$.contexts_ordered" }
+      - { name: apply_problems,   from: "$.problems" }
 
-  # 1c. Curation guard (OKF rule): a bundle that already has concept files is
-  #     hand/agent curation — regenerating from scratch would destroy it. Stop
-  #     and let the operator clear or back up {{bundle_dir}} before re-running.
-  - id: bundle_guard
+  # A rejected edit names the row it could not resolve. Stopping here is the
+  # point: a map built from a half-understood file would be onboarded silently.
+  - id: apply_gate
     action: verify_context
-    require_value: bundle_present
-    equals: "false"
+    condition: "{{mode}} == apply"
+    require_value: proposal_ok
+    equals: "true"
     on_mismatch: stop
-    on_mismatch_message: "The OKF bundle at {{bundle_dir}} already holds {{bundle_md_count}} concept file(s) — inventory would overwrite that curation. Back up or remove {{bundle_dir}} to regenerate from scratch (a future /appweaver inventory-update will refresh incrementally)."
+    on_mismatch_message: >
+      specs/proposed-inventory.md could not be applied: {{apply_problems}}
+      Fix those rows and re-run /appweaver inventory apply. The Aggregate column
+      must name an aggregate the scan found; every Depends On value must name a
+      Feature that exists in the same table.
 
-  # 2. Pre-execution hooks.
-  - id: resolve_pre_hooks
+  - id: apply_report
+    action: verify_context
+    condition: "{{mode}} == apply"
+    require_non_empty: feature_map
+    on_empty: stop
+    on_empty_message: "apply reported success but wrote no map — re-run /appweaver inventory."
+
+  - id: applied
+    action: set
+    condition: "{{mode}} == apply"
+    vars: { next_hint: "Onboard the contexts in order: {{contexts_ordered}}" }
+
+  # ═══════════════════ PROPOSE — discover and write the map ═════════════════
+
+  # 1. WHICH LANES, AND WHERE IS THEIR SOURCE. Same declaration onboard reads:
+  #    the scan is scoped to the declared subtrees so backend candidates are not
+  #    drawn from UI source and vice versa.
+  - id: lane_model
     action: execute_script
+    condition: "{{mode}} == propose"
     script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "before_inventory"]
-    outputs:
-      - { name: before_hooks, from: "$.hooks" }
-  - id: dispatch_pre_hooks
-    action: dispatch_hooks
-    hooks_from_variable: before_hooks
-
-  # 3. ENRICHMENT — turn the substrate into an aggregate-organized OKF bundle.
-  #    Context is fed via build_context (agent_generate reads the envelope, NOT a
-  #    step-level context: key): the factual substrate, the OKF format authority
-  #    (generate.md), and the brownfield design (seam/backlog framing).
-  - id: ctx_author
-    action: build_context
-    context:
-      - { path: "{{inventory_json}}" }             # the deterministic substrate (aggregate_signals etc.)
-      - { path: .appweaver/templates/okf-concept-template.md }   # OKF v0.1 format authority (frontmatter, index, log, rules)
-      - { path: Brownfield-Pipeline.md }           # seam-as-unit-of-work, migration backlog, source anchor
-  - id: author_bundle
-    action: agent_generate
-    tools: "Read,Write,Edit"
-    permission_mode: acceptEdits
-    task: |
-      Act as the OKF enrichment agent for the Brownfield-Pipeline INVENTORY (B0)
-      phase. Produce a CONFORMANT OKF v0.1 knowledge bundle at {{bundle_dir}},
-      organized BY AGGREGATE ROOT, from the deterministic substrate
-      {{inventory_json}} (in context). Follow the OKF concept template in context for
-      format (frontmatter, index.md/log.md rules, cross-linking, hard rules) —
-      but ORGANIZE around aggregates, not services/modules. Scope/focus hints:
-      {{USER_INPUT}}
-
-      Read the substrate first. Its `aggregate_signals` are CANDIDATE roots,
-      each with its files grouped by layer (domain / feature / infra / api) plus
-      detected entities; `git.history.churn` ranks significance; the category
-      lists (data_layer_files, route_like_files, api_definitions, ops_files,
-      docs, adr_docs) and `top_level_dirs` fill in the rest. Signals are input,
-      NOT decisions — YOU draw the real boundaries.
-
-      Consolidate the candidates into REAL aggregates:
-      - Merge a src module and its mirror test module into ONE aggregate (e.g.
-        src/.../MedicinalProducts + tests/.../MedicinalProducts → MedicinalProduct).
-      - Treat service-level / shared infrastructure (a shared DbContext, cross-
-        cutting adapters) as a Platform/Shared concept, NOT an aggregate.
-      - Fold value objects, entities, domain events and CQRS commands/endpoints
-        into the aggregate that OWNS them — one aggregate concept, not one per type.
-
-      Write the bundle (all paths under {{bundle_dir}}, bundle-relative links
-      begin with "/", per OKF §5.1):
-      - `index.md` (bundle root) — frontmatter EXACTLY `okf_version: "0.1"` and
-        nothing else; body = sections of bulleted links reusing each concept's
-        `description`.
-      - `architecture/overview.md` (type: Reference) — system purpose, the
-        AGGREGATE MAP (each aggregate + its seam), tech stack, and links to every
-        other concept.
-      - `aggregates/<aggregate>.md` (type: Aggregate) — ONE per aggregate root.
-        Cover: Responsibilities; the entities / value objects / domain events /
-        commands / API endpoints / persistence it owns (from the signal's layer
-        files); invariants (INFERRED from code — mark confidence, park anything
-        unclear in `open_questions`, never guess); the SEAM (the boundary you
-        could route across — repository, endpoint, table owner, queue — and
-        whether it is CLEAN or TORN, i.e. shares a transaction/table with another
-        slice); and the candidate `specs/<Feature>/` slice name (feature =
-        aggregate). Set `source_files` to the module's files, grouped with YAML
-        comment headers by each file's OWN folder — the path segment that VARIES
-        across the files after their shared parent directory (the layer folder in
-        a vertical slice; the tier project in an n-tier / layered app; tests → a
-        single `tests` group). Do NOT impose a fixed Domain/Application/UI
-        taxonomy — the CODE's folders ARE the grouping, and the toolchain
-        re-derives them the same way on every later write. Set `timestamp` to the
-        latest commit time across them.
-      - `data/` and `api/` concepts only where a data model or API surface needs
-        its own home beyond the owning aggregate (medium granularity: prefer
-        folding into the aggregate).
-      - `migration-backlog.md` (type: Reference, at bundle root) — the B0
-        deliverable: a table `| aggregate | candidate slice | seam (clean/torn) |
-        depends on | risks | adopt order |`, sequenced so clean seams go first
-        and TORN seams are flagged as remediation items (introduce the seam
-        before adopting). This is the strangler rollout plan.
-      - An `index.md` in EVERY subdirectory (no frontmatter).
-      - `log.md` (bundle root) — first line under a `## <today's date>` heading
-        must be `Commit: ` + backtick + `{{head}}` + backtick (validator rule E4),
-        then a one-line Initialization entry noting the concept count.
-
-      Provenance + safety (OKF hard rules):
-      - Stamp every concept `origin: reverse-engineered` and `generated_by:
-        aw-spec-inventory/1.1.0` in frontmatter.
-      - The CODE is the source of truth; capture what IS (bugs/quirks included),
-        not what SHOULD be. Where intent/invariants are unclear from code + git
-        history, add a concrete `open_questions` entry rather than inventing one.
-      - NEVER fabricate facts, and NEVER emit secrets/tokens/credentials/internal
-        hostnames found in the code — describe shape, never values.
-      - Write ONLY inside {{bundle_dir}}; do NOT modify any source file.
-      Report the bundle tree and the concept count by type.
+    subcommand: lane-verify
+    args: ["--command", "/appweaver inventory"]
     outputs:
-      - { name: bundle_files, from: "$.files" }
+      - { name: lane_model_ok,     from: "$.ok" }
+      - { name: lane_model_issues, from: "$.message" }
+      - { name: be_root,           from: "$.backend_source_path" }
+      - { name: fe_root,           from: "$.frontend_source_path" }
 
-  - id: verify_authored
+  - id: lane_model_gate
     action: verify_context
-    require_non_empty: bundle_files
-    on_empty: stop
-    on_empty_message: "No bundle files were written to {{bundle_dir}}. Ensure the substrate {{inventory_json}} has aggregate_signals and re-run."
+    condition: "{{mode}} == propose"
+    require_true: lane_model_ok
+    on_false: stop
+    on_false_message: >
+      /appweaver inventory cannot run: {{lane_model_issues}}
+      The scan is scoped to the declared lanes, so it has to be told which subtree
+      holds which lane before it starts. Run /appweaver select-stack first — it
+      detects what this repo already is and lets you correct the proposal.
 
-  # 4. CONFORMANCE gate — OKF v0.1 validator (errors block; warnings are noted).
-  - id: validate_bundle
+  # 2. PASS A + B + C. One deterministic call: every AVAILABLE strategy's
+  #    clustering is run (cheap — the expensive half is authoring, which does not
+  #    happen here), the seam overlay is laid over the chosen one, and the
+  #    proposal is written with its dependency waves.
+  - id: propose
     action: execute_script
+    condition: "{{mode}} == propose"
     script: { ref: inventory }
-    subcommand: validate
-    args: ["--bundle", "{{bundle_dir}}", "--repo-root", "{{root}}"]
+    subcommand: propose
+    args: ["--service-root", "{{be_root}}", "--ui-root", "{{fe_root}}", "--strategy", "{{strategy}}"]
     outputs:
-      - { name: conformant,   from: "$.conformant" }
-      - { name: okf_errors,   from: "$.errors" }
-      - { name: okf_warnings, from: "$.warnings" }
-      - { name: concepts,     from: "$.concepts" }
+      - { name: proposal_ok,       from: "$.ok" }
+      - { name: proposal_md,       from: "$.proposal_md" }
+      - { name: feature_map,       from: "$.feature_map" }
+      - { name: root,              from: "$.root" }
+      - { name: chosen_strategy,   from: "$.strategy" }
+      - { name: feature_count,     from: "$.feature_count" }
+      - { name: context_count,     from: "$.context_count" }
+      - { name: wave_count,        from: "$.wave_count" }
+      - { name: cycle_count,       from: "$.cycle_count" }
+      - { name: coverage_pct,      from: "$.coverage_pct" }
+      - { name: split_candidates,  from: "$.split_candidates" }
+      - { name: contexts_ordered,  from: "$.contexts_ordered" }
+      - { name: strategy_options,  from: "$.strategy_options" }
 
-  - id: conformance_gate
+  # 2b. Substance gate. Zero features is the one outcome that leaves onboard with
+  #     nothing to do, and it is reported as what it is rather than as a crash.
+  - id: require_features
     action: verify_context
-    require_true: conformant
+    condition: "{{mode}} == propose"
+    require_true: feature_count
     on_false: stop
-    on_false_message: "The OKF bundle at {{bundle_dir}} is NON-CONFORMANT (errors: {{okf_errors}}). Fix the reported ERRORs (unparseable frontmatter, missing `type`, malformed index.md/log.md) and re-run — or edit the bundle by hand, then re-validate."
+    on_false_message: >
+      No candidate features were found in {{root}}. Every Pass A strategy either
+      returned nothing or was unavailable for want of evidence. Point
+      /appweaver inventory at a subtree that holds application source, or check
+      that the lane declaration names the right path.
+
+  # 3. THE STRATEGY PICK. Offered from the probe, each option carrying its own
+  #    measured numbers — features found, share of source covered, how many
+  #    one-file candidates it produced. A strategy that would return nothing is
+  #    not in the list, because choosing it would be the zero-candidate stop
+  #    arrived at deliberately. One option auto-confirms.
+  - id: pick_strategy
+    action: user_select
+    condition: "{{mode}} == propose"
+    prompt: >
+      Pass A found these candidate boundaries. Which evidence should the feature
+      map be built from? (`{{chosen_strategy}}` is proposed: highest coverage,
+      ties broken by fewest single-file candidates.)
+    options_from_variable: strategy_options
+    preselect_from: chosen_strategy
+    single_option_confirm: true
+    outputs:
+      - { name: picked, from: selection }
+
+  # 4. Re-derive on the operator's pick. Deterministic and about a second, so it
+  #    is re-run unconditionally rather than branched on whether the pick moved.
+  - id: repropose
+    action: execute_script
+    condition: "{{mode}} == propose"
+    script: { ref: inventory }
+    subcommand: propose
+    args: ["--service-root", "{{be_root}}", "--ui-root", "{{fe_root}}", "--strategy", "{{picked}}"]
+    outputs:
+      - { name: proposal_md,      from: "$.proposal_md" }
+      - { name: feature_map,      from: "$.feature_map" }
+      - { name: chosen_strategy,  from: "$.strategy" }
+      - { name: feature_count,    from: "$.feature_count" }
+      - { name: context_count,    from: "$.context_count" }
+      - { name: wave_count,       from: "$.wave_count" }
+      - { name: cycle_count,      from: "$.cycle_count" }
+      - { name: coverage_pct,     from: "$.coverage_pct" }
+      - { name: split_candidates, from: "$.split_candidates" }
+      - { name: contexts_ordered, from: "$.contexts_ordered" }
+
+  # 5. Hooks, after the map exists and before the operator is handed it.
+  - id: resolve_pre_hooks
+    action: execute_script
+    condition: "{{mode}} == propose"
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_inventory"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    condition: "{{mode}} == propose"
+    hooks_from_variable: before_hooks
 
-  # 5. Post-execution hooks.
   - id: resolve_post_hooks
     action: execute_script
     script: { ref: actions }
@@ -230,9 +254,28 @@ workflow:
     hooks_from_variable: after_hooks
 
 outputs:
-  inventory_json: "{{inventory_json}}"
-  bundle_dir: "{{bundle_dir}}"
-  aggregate_count: "{{aggregate_count}}"
-  concepts: "{{concepts}}"
-  warnings: "{{okf_warnings}}"
-  next: "Review {{bundle_dir}} (start with architecture/overview.md and migration-backlog.md). Then adopt a slice: /appweaver adopt <Aggregate> reverse-engineers its spec.md + backend-plan.md from the bundle, and the forward pipeline carries it from there."
+  proposal: "{{proposal_md}}"
+  feature_map: "{{feature_map}}"
+  strategy: "{{chosen_strategy}}"
+  features: "{{feature_count}}"
+  contexts: "{{context_count}}"
+  waves: "{{wave_count}}"
+  cycles: "{{cycle_count}}"
+  coverage_pct: "{{coverage_pct}}"
+  split_candidates: "{{split_candidates}}"
+  contexts_ordered: "{{contexts_ordered}}"
+
+next: >
+  {{feature_count}} feature(s) across {{context_count}} bounded context(s) were
+  proposed from `{{chosen_strategy}}` evidence ({{coverage_pct}}% of source
+  covered), ordered into {{wave_count}} dependency wave(s).
+
+  READ AND EDIT specs/proposed-inventory.md — it is the boundary map, and it is
+  yours. Rename features and contexts, move a feature to another context, merge
+  two by giving them one name, split one by adding a row with the same Aggregate,
+  and set Depends On to change the order. {{split_candidates}} split(s) were
+  PROPOSED with their evidence and none were applied.
+
+  Then run `/appweaver inventory apply` to validate those edits and regenerate the
+  machine map, and onboard the contexts one at a time in the order it reports:
+  {{contexts_ordered}}