aw-spec-cli 0.1.5 → 0.1.7

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

@@ -1,236 +0,0 @@
-# =============================================================================
-# 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."