aw-spec-cli 0.1.4 → 0.1.5

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

@@ -0,0 +1,236 @@
+# =============================================================================
+# aw-spec-inventory (orchestrator) — B0 of the Brownfield Pipeline
+#
+# 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 + design.md per slice.
+#
+#   INVENTORY  → adopt → (fidelity) → characterize → [ forward pipeline ]   ← 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).
+#
+# It does NOT author spec.md / design.md (that is /aw-spec-orch adopt per slice)
+# and does NOT touch source code — all writes stay inside the bundle dir.
+#
+# Launch:  /aw-spec-orch inventory [strategy] [focus/scope hints]
+# =============================================================================
+
+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 + design.md per aggregate/vertical slice. Deterministic scan + enrichment agent + conformance gate; never modifies source.
+version: 1.1.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).
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  inventory:
+    sh:  .aw-spec/scripts/bash/aw-inventory.sh
+    ps1: .aw-spec/scripts/powershell/aw-inventory.ps1
+  actions:
+    sh:  .aw-spec/scripts/bash/aw-spec-actions.sh
+    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
+
+# Domain-modelling authority — helps the enrichment agent NAME/classify what it
+# finds (aggregate vs entity vs value object vs event) when drawing boundaries.
+# Optional: a non-DDD or non-domain repo simply has no overlay to load.
+standards:
+  - { path: docs/domain/domain-driven-design.md, optional: true }
+  - { path: docs/glossary/ai-rules.md, optional: true }
+
+vars:
+  bundle_present: "false"
+  conformant: "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
+    action: execute_script
+    script: { ref: inventory }
+    subcommand: scan
+    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 /aw-spec-orch inventory at a codebase with a recognizable domain/vertical-slice layout, or scan a subtree that contains one."
+
+  # 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
+    action: verify_context
+    require_value: bundle_present
+    equals: "false"
+    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 /aw-spec-orch inventory-update will refresh incrementally)."
+
+  # 2. Pre-execution hooks.
+  - id: resolve_pre_hooks
+    action: execute_script
+    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: .aw-spec/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.
+    outputs:
+      - { name: bundle_files, from: "$.files" }
+
+  - id: verify_authored
+    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."
+
+  # 4. CONFORMANCE gate — OKF v0.1 validator (errors block; warnings are noted).
+  - id: validate_bundle
+    action: execute_script
+    script: { ref: inventory }
+    subcommand: validate
+    args: ["--bundle", "{{bundle_dir}}", "--repo-root", "{{root}}"]
+    outputs:
+      - { name: conformant,   from: "$.conformant" }
+      - { name: okf_errors,   from: "$.errors" }
+      - { name: okf_warnings, from: "$.warnings" }
+      - { name: concepts,     from: "$.concepts" }
+
+  - id: conformance_gate
+    action: verify_context
+    require_true: conformant
+    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."
+
+  # 5. Post-execution hooks.
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_inventory"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    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: /aw-spec-orch adopt <Aggregate> reverse-engineers its spec.md + design.md from the bundle, and the forward pipeline carries it from there."