aw-spec-cli 0.1.4 → 0.1.5

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

@@ -0,0 +1,412 @@
+# =============================================================================
+# aw-spec-specify (orchestrator) — author the SPEC for the ACTIVE feature
+#
+# Spec-anchored pipeline, spec phase. feature = AGGREGATE (picked/created by
+# /aw-spec-orch select-feature, which sets .aw-spec/feature.json). specify does
+# NOT guess or create the feature — it CONSUMES the active one, and is phase-pure
+# (spec side only; the single design.md is the `design` phase).
+#
+# Auto-detects first-vs-subsequent from spec.md:
+#   • BOOTSTRAP (no spec.md)  → author the MASTER spec (US-1) + init active_version.json.
+#   • DELTA (spec.md exists)  → delegate to the delta-spec module: open a change (cr-setup)
+#     and author the delta-spec ONLY. The master spec.md is left UNTOUCHED — the change
+#     stays OPEN; finalize-delta merges the delta into spec.md + design.md, and the
+#     change is not closed until close-delta at the end of the chain.
+#     (The former standalone `cr` capture's spec half now lives here.)
+#
+# Both paths then run ONE converge block — checklist + clarify + validate — over the
+# document THIS invocation authored, never the other one:
+#   • BOOTSTRAP → the master spec, graded by the spec checklist.
+#   • DELTA     → the delta-spec, graded by a DELTA-SHAPED checklist written inside
+#                 changes/<cr-id>/. The master is not read, not graded, NOT written.
+# The pairing is bound from create-checklist's own output (checklist_file + target →
+# quality_target), so the checklist and the document it grades can never diverge.
+# Why it matters: the delta is authored relative to the master, so a "quality" rewrite
+# of the master mid-change would leave the delta computed against a stale baseline —
+# and in brownfield it would silently edit an adopted, code-derived spec that nothing
+# downstream re-checks for fidelity. Narrow rewrites run include_standards:false.
+# Accuracy of the delta AGAINST the master (id continuity, conflicts) stays where it
+# belongs: /aw-spec-orch analyze-delta-design.
+#
+# Forward paths:
+#   NEW    : specify → design → analyze-design → implement
+#   CHANGE : specify (delta-spec) → design (delta-design) → analyze-delta-design →
+#            implement-delta → build → finalize-delta → analyze-slice → close-delta
+#
+# Launch:  /aw-spec-orch specify [strategy] <what the feature/change does>
+#   e.g.  /aw-spec-orch specify Customers place an order for one or more items
+# Prereq:  /aw-spec-orch select-feature   (sets the active aggregate)
+# =============================================================================
+
+name: aw-spec-specify
+description: Author the specification of the ACTIVE feature (aggregate). First call writes the master spec (US-1); a later call (spec.md exists) delegates to the delta-spec module to author a delta-spec ONLY (master spec.md untouched — finalize-delta merges it) and leaves the change OPEN. The checklist/clarify/validate loops grade whichever document the call authored, using a delta-shaped checklist on the change path. Spec phase only — design is separate.
+version: 2.3.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: What the feature (first call) or the change (later calls) should do, in natural language.
+    required: true
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .aw-spec/scripts/bash/aw-spec-actions.sh
+    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
+
+# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). Specify's ONE
+# technical input — the MODELLING METHODOLOGY (DDD tactical patterns) — is no longer
+# hardcoded here: it is now CONFIGURATION, loaded per-command from
+# docs/domainspecs/<domain>/commandtechrulemap.md by the tech-select module (see the
+# tech_select step below), exactly as the DOMAIN rule files are loaded by domain-select.
+# Per the rule-partition that heading may carry a modelling methodology ONLY — never an
+# architecture / persistence / codegen file; those belong to design + implement, and
+# putting one here would break specify's domain purity. The domain classification /
+# constraint rules still arrive via domain-select (D3). The BASE security/
+# data-classification.md is a design doc — specify gets the domain data-classification
+# overlay via domain-select, and lifts its taxonomy into the spec's Data Classification
+# (DC-) section. (missing files are skipped at assembly time)
+standards:
+  - { path: docs/glossary/ai-rules.md, optional: true }
+
+vars:
+  spec_all_pass: "false"     # validation-loop guard, flipped by the validate query
+  checklist_total: "0"       # bound by checklist-read
+  checklist_passed: "0"      # stays 0 when the checklist has no items to score
+  cr_id: ""                  # set on the DELTA path only
+  cr_dir: ""                 # set on the DELTA path only — changes/<cr-id>/
+  quality_target: ""         # the document the converge loops grade AND rewrite:
+                             # spec.md (bootstrap) | delta-spec.md (delta). Bound from
+                             # create-checklist's own output so it always agrees with
+                             # the checklist. NEVER hand-set to spec_file on the delta
+                             # path — that is what silently drifts an adopted spec.
+  version: ""                # current active_version.json version (for the report)
+
+workflow:
+
+  # 1. CONSUME the active feature (set by select-feature). No derive-names.
+  - id: feature_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature_dir, from: "$.feature_dir" }
+      - { name: spec_file,   from: "$.spec_file" }
+      - { name: spec_exists, from: "$.spec_exists" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature. Run /aw-spec-orch select-feature first (pick or create the aggregate, e.g. Order), then re-run specify."
+
+  # 2. TECHNICAL rule files → sticky standards (configuration, not hardcoded).
+  #    tech-select reads docs/domainspecs/<domain>/commandtechrulemap.md under
+  #    "## /aw-spec-specify" and loads that set. Per the rule-partition that heading is
+  #    the MODELLING-METHODOLOGY slot only (DDD tactical patterns) — it must never list an
+  #    architecture / persistence / codegen file, which would break specify's domain purity.
+  #    No blocking gate: an unconfigured project (no domain, no map, or no specify heading)
+  #    soft-continues and simply loads nothing extra. Placed AFTER require_feature so the
+  #    no-feature stop fires before any selection box.
+  - id: tech_select
+    action: include
+    module: .aw-spec/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-specify }
+
+  # 3. Resolve the active domain + its rule files → sticky standards (D3).
+  - id: domain_select
+    action: include
+    module: .aw-spec/orchestrator/modules/domain-select.orch.yaml
+    with: { command: aw-spec-specify }
+
+  # 4. Pre-execution hooks: resolve (script) then dispatch (invoking agent).
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_specify"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # ═══════════════════════ BOOTSTRAP — no spec.md yet ═══════════════════════
+  # Copy the spec template into the (already-existing) feature dir + init version.
+  - id: boot_scaffold
+    condition: "{{spec_exists}} == false"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--allow-existing"]
+
+  - id: boot_version_init
+    condition: "{{spec_exists}} == false"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: version-init
+    args: ["--feature-dir", "{{feature_dir}}"]
+
+  - id: boot_ctx
+    condition: "{{spec_exists}} == false"
+    action: build_context
+    context:
+      - "{{spec_file}}"                      # the copied template = section structure
+      - .aw-spec/memory/constitution.domain.md      # the DOMAIN authority — specify's frame. Declared
+                                                     # REQUIRED (bare string, not `optional: true`) ON PURPOSE:
+                                                     # specify is the ONLY phase that reads the domain rules and
+                                                     # its task text tells the agent this file is in context, so
+                                                     # a missing one must ANNOUNCE (`[context] MISSING (required)`)
+                                                     # rather than silently thin the payload. It announces, it does
+                                                     # not stop — constitution/onboard write this file before
+                                                     # specify ever runs on either flow.
+                                                     # NOT constitution.technical: architecture (I–XV) is a
+                                                     # HOW concern for design/implement, not domain modelling.
+  - id: boot_generate
+    condition: "{{spec_exists}} == false"
+    action: agent_author
+    output_target: { type: file, path: "{{spec_file}}" }
+    task: |
+      Author the MASTER specification for this aggregate by filling out the
+      template in context. This is the first user story, US-1. Base everything on:
+
+      {{USER_INPUT}}
+
+      Rules for the content you generate:
+      - The feature IS the aggregate; set the Aggregate field and keep US-1's id.
+      - Preserve the template's section order and headings.
+      - SPECIFY IS THE ONLY PHASE THAT READS THE DOMAIN RULES. Design and implement
+        work from the spec/design, never the domain docs — so this spec is the SOLE
+        carrier of the domain into the pipeline. Model the domain COMPLETELY here, or
+        it is lost downstream.
+      - DDD IS THE RATIFIED MODELLING STANDARD (NON-NEGOTIABLE → the modelling-methodology
+        standard in the sticky standards, wired per-project via commandtechrulemap
+        "## /aw-spec-specify", plus the domain's own DDD overlay). The domain
+        model in this spec MUST be expressed strictly in DDD terms: a consistent
+        ubiquitous language; the aggregate + its root; entities vs value objects;
+        invariants owned by the aggregate; the bounded-context boundary. Capture these
+        as domain MODEL, not code — no C# types, no persistence, no framework. This is
+        the one technical standard specify applies, because the domain model is part of
+        the spec; design/implement inherit it through the spec, never re-derive it.
+      - Focus on WHAT users need and WHY. Include NO implementation mechanics
+        (languages, frameworks, code structure, endpoint/adapter design). Note: an
+        external interoperability OBLIGATION — which standard/resources must be met —
+        is a requirement, not implementation; record it as an Integration Contract,
+        but never how the adapter is built.
+      - Write for non-technical business stakeholders.
+      - Write System Requirements in EARS as the template shows (THE SYSTEM SHALL
+        / WHEN…/ IF…THEN / WHILE…/ WHERE…) — each atomic and testable.
+      - Capture always-true BUSINESS invariants as Business Rules (BR-n), and state
+        the aggregate boundary (what it owns vs references by id, and out of scope).
+        Record reasonable defaults in Assumptions.
+      - DOMAIN LIFT — when the active domain's rules impose them, lift into the three
+        dedicated sections (stable ids; cite the source rule where lifted):
+          • Constraints & NFRs (CN-n) — regulatory / retention / immutability /
+            audit-mandate and performance-as-a-limit rules. These are NOT business
+            invariants (those are BR) and NOT behaviour (those are FR).
+          • Data Classification (DC-n) — sensitivity categories + where each may /
+            MUST NOT appear (public surface, logs, metrics, traces, projections).
+          • Integration Contracts (IC-n) — external interop obligations (outbound
+            projections, terminology / reference services, inbound feeds) at contract
+            level, mapped to the Key Entities they concern.
+        If the domain imposes none, write "None (as of v1.0)" — never delete a section.
+      - This is v1.0: fill the initial Change History row's date and keep US-1's
+        "Added: v1.0" marker.
+      - ALWAYS include a "## Success Criteria" section with 2-4 measurable,
+        technology-agnostic, verifiable SC-nnn outcomes derived from the acceptance
+        criteria. It is MANDATORY — never drop it; when a metric must be inferred,
+        state a reasonable, testable target rather than omitting the section.
+      - Add at most 3 "[NEEDS CLARIFICATION: <question>]" markers, and only for
+        choices that materially affect scope/UX and have no reasonable default.
+      - Every section the template marks *(mandatory)* — at minimum System
+        Requirements and Success Criteria — plus Business Need, User Stories, and
+        the Change History row MUST be present and populated. The domain-lift sections
+        (Constraints & NFRs, Data Classification, Integration Contracts) MUST also be
+        present — populated when the domain applies, else "None (as of v1.0)". You may
+        omit only a genuinely inapplicable OPTIONAL item (e.g. the WHERE optional-feature
+        requirement, or an empty Assumptions list) — never a mandatory section, and
+        never write "N/A".
+      - Do NOT embed any checklist and NO design/implementation.
+
+  # ═════════════════════════ DELTA — spec.md exists ═════════════════════════
+  # A later requirement = a new user story on the SAME aggregate. Delegate to the
+  # delta-spec module: it opens the change (cr-setup, single-active-change guarded) and
+  # authors the delta-spec ONLY — the master spec.md is left UNTOUCHED. The change
+  # stays OPEN; finalize-delta merges the delta into spec.md later in the chain. Runs in
+  # this context (shares vars + the DDD + domain sticky standards). The former standalone
+  # `cr` capture's spec half now lives here. Downstream: design (delta-design) →
+  # analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice →
+  # close-delta (close-delta is what finally archives the change and bumps the version).
+  - id: delta_spec_module
+    condition: "{{spec_exists}} == true"
+    action: include
+    module: .aw-spec/orchestrator/modules/delta-spec.orch.yaml
+
+  # ══════ CONVERGE — checklist + clarify + validate, ON THE DOCUMENT JUST WRITTEN ══════
+  # These loops run on WHICHEVER document this invocation authored — the master spec on
+  # the bootstrap path, the delta-spec on the change path. They must NEVER write the
+  # master while a change is open: the delta is authored relative to the master, so
+  # mutating the master here would leave the delta computed against a stale baseline
+  # AND (brownfield) silently edit an adopted, code-derived spec that no downstream
+  # stage re-checks for fidelity. Hence quality_target — bound from the SAME script call
+  # that creates the checklist, so the checklist and the graded document cannot diverge.
+  #
+  # 5. Quality checklist (shared script — static content, NO model). Idempotent in
+  #    content; note it rewrites the file, so it is deliberately scoped to the path that
+  #    authored the document (a delta run no longer resets the master's scored boxes).
+  - id: create_checklist
+    condition: "{{spec_exists}} == false"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: create-checklist
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: checklist_file,  from: "$.checklist_file" }
+      - { name: quality_target,  from: "$.target" }      # → spec.md
+
+  # Delta twin: a DELTA-SHAPED checklist (ADDED/MODIFIED/REMOVED completeness, merge
+  # readiness) written INSIDE changes/<cr-id>/, grading the delta-spec. The master
+  # checklist's items assume a full spec and would mis-fire here, which is exactly why
+  # this is a separate checklist rather than the same one re-pointed.
+  - id: create_delta_checklist
+    condition: "{{spec_exists}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: create-checklist
+    args: ["--feature-dir", "{{feature_dir}}", "--kind", "delta", "--change-dir", "{{cr_dir}}"]
+    outputs:
+      - { name: checklist_file,  from: "$.checklist_file" }
+      - { name: quality_target,  from: "$.target" }      # → changes/<cr-id>/delta-spec.md
+
+  # 6. Resolve [NEEDS CLARIFICATION] markers interactively (≤3). Non-interactive
+  #    runs answer with the first/recommended option (a documented default).
+  - id: extract_clarifications
+    action: agent_query
+    context: ["{{quality_target}}"]
+    include_standards: false
+    task: |
+      Extract up to 3 unresolved "[NEEDS CLARIFICATION: <question>]" markers from
+      the document in context (a feature spec, or one change's delta-spec), most
+      scope/security/UX-impacting first. Return {"clarifications":[]} if there are none.
+    schema: { clarifications: [ { id: c1, question: "<the question>", options: ["<answer A>", "<answer B>", "<answer C>"] } ] }
+    mock: { clarifications: [] }
+    outputs:
+      - { name: clarifications, from: "$.clarifications" }
+
+  - id: clarify_loop
+    action: loop
+    over: "{{clarifications}}"
+    as: c
+    max_iterations: 3
+    steps:
+      - id: ask_clar
+        action: ask
+        prompt: "{{c.question}}"
+        options_from: "{{c.options}}"
+        answer_key: "{{c.id}}"
+        answer_var: c_answer
+      - id: resolve_clar
+        action: agent_author
+        context: ["{{quality_target}}"]
+        include_standards: false           # rewrite-in-place: the graded document only
+        task: |
+          Replace the matching "[NEEDS CLARIFICATION]" marker in the document in
+          context with this answer and update the affected requirement/section
+          accordingly. Preserve structure and headings. If it is a delta-spec, stay
+          within the delta — keep every item's ADDED / MODIFIED / REMOVED placement.
+            Question: {{c.question}}
+            Answer:   {{c_answer}}
+        output_target: { type: file, path: "{{quality_target}}" }
+
+  # 7. Spec-quality validation loop — evaluate the spec against the checklist,
+  #    fix failing items, re-check (max 3), then score the checklist file.
+  - id: checklist_read
+    action: execute_script
+    script: { ref: actions }
+    subcommand: checklist-read
+    args: ["--file", "{{checklist_file}}"]
+    outputs:
+      - { name: checklist_total, from: "$.total" }
+
+  - id: validation_loop
+    action: loop
+    while: "{{spec_all_pass}} != true"
+    max_iterations: 3
+    steps:
+      - id: validate
+        action: agent_query
+        context: ["{{checklist_file}}", "{{quality_target}}"]
+        include_standards: false
+        task: |
+          Evaluate the document under review (in context) against each checklist item
+          (in context, 1-based in order). The checklist's own title states which kind
+          of document it grades — a feature spec, or one change's delta-spec; judge it
+          as that kind and nothing more. An item passes when the document satisfies it.
+          (An item about remaining [NEEDS CLARIFICATION] markers passes once none
+          remain.) In "failing", quote the offending/absent part per failed item.
+        schema: { all_pass: false, results: { "1": true, "2": false }, failing: [ { n: 2, issue: "<quote>" } ] }
+        mock: { all_pass: true, results: {}, failing: [] }
+        outputs:
+          - { name: spec_all_pass, from: "$.all_pass" }
+          - { name: spec_results,  from: "$.results" }
+          - { name: spec_failing,  from: "$.failing" }
+      - id: pass_break
+        action: break
+        condition: "{{spec_all_pass}} == true"
+      - id: patch_spec
+        action: agent_author
+        context: ["{{quality_target}}"]
+        include_standards: false
+        task: |
+          Fix these quality failures in the document in context, preserving its
+          section order and headings. Do NOT add implementation detail; keep it
+          business-facing and testable.
+          If the document is a DELTA-SPEC: it describes one change, not the whole
+          feature. Fix it AS a delta — keep the ADDED / MODIFIED / REMOVED structure,
+          never expand it into a full specification, never copy in unchanged master
+          content to satisfy an item, and never edit the master spec.
+            Failures: {{spec_failing}}
+        output_target: { type: file, path: "{{quality_target}}" }
+
+  - id: score_checklist
+    action: execute_script
+    condition: "{{checklist_total}} != 0"
+    script: { ref: actions }
+    subcommand: checklist-apply
+    args: ["--file", "{{checklist_file}}", "--results", "{{spec_results}}"]
+    outputs:
+      - { name: checklist_passed, from: "$.after_checked" }
+
+  # 8. Read the current version for the report (both paths).
+  - id: version_read
+    action: execute_script
+    script: { ref: actions }
+    subcommand: version-read
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: version,        from: "$.version" }
+      - { name: active_change,  from: "$.active_change" }
+
+  # 9. Post-execution hooks: resolve (script) then dispatch (invoking agent).
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_specify"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  feature_directory: "{{feature_dir}}"
+  spec_file: "{{spec_file}}"
+  version: "{{version}}"
+  change_id: "{{cr_id}}"
+  authored_document: "{{quality_target}}"   # spec.md (bootstrap) | delta-spec.md (delta)
+  checklist_file: "{{checklist_file}}"
+  checklist_quality: "{{checklist_passed}}/{{checklist_total}} items passing"
+  next: "/aw-spec-orch design — BOOTSTRAP authors design.md from the spec; a DELTA (this run opened change {{cr_id}}) authors the delta-design for it. A change then flows: analyze-delta-design → implement-delta → build → finalize-delta → analyze-slice → close-delta (finalize-delta merges the delta into spec.md + design.md but leaves the change open; analyze-slice verifies the slice against the merged master; close-delta archives the change and bumps the version)."

package/assets/.aw-spec/scripts/bash/aw-inventory.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# aw-inventory.sh — thin wrapper: delegate to the single python core.
+#
+# The brownfield inventory logic lives ONCE in ../python/aw-inventory.py (a
+# faithful cross-platform port of Reference/okf-inventory.sh + aggregate-root
+# signals). This wrapper exists only so the orchestrator's execute_script,
+# which dispatches sh:/ps1: variants, can invoke it. All args (subcommand +
+# options) pass straight through.
+#
+#   aw-inventory.sh scan     [--root <dir>] [--out <path>] [--bundle <dir>] [--config <yml>]
+#   aw-inventory.sh validate --bundle <dir> [--repo-root <dir>]
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 "$DIR/../python/aw-inventory.py" "$@"

package/assets/.aw-spec/scripts/bash/aw-parity.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# aw-parity.sh — thin wrapper: delegate to the single python core.
+#
+# Brownfield PARITY runner (the cutover gate). Logic lives ONCE in
+# ../python/aw-parity.py; this wrapper exists only so the orchestrator's
+# execute_script (sh:/ps1: dispatch) can invoke it. All args pass through.
+#
+#   aw-parity.sh scaffold --feature-dir <dir>
+#   aw-parity.sh check    --manifest <path>
+#   aw-parity.sh run      --manifest <path> [--out <report.md>]
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 "$DIR/../python/aw-parity.py" "$@"

package/assets/.aw-spec/scripts/bash/aw-rev-constitution.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# aw-rev-constitution.sh — thin wrapper: delegate to the single python core.
+#
+# Brownfield GOVERN-BACKWARD substrate, driven by `/aw-spec-orch onboard` (the
+# standalone rev-constitution workflow is RETIRED). Logic lives
+# ONCE in ../python/aw-rev-constitution.py; this wrapper exists only so the
+# orchestrator's execute_script (sh:/ps1: dispatch) can invoke it. Args pass through.
+#
+#   aw-rev-constitution.sh list-adopted [--root <dir>] [--specs <dir>] [--bundle <dir>]
+#   aw-rev-constitution.sh pack-setup   --name <domain> [--fallback <name>] [--root <dir>]
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 "$DIR/../python/aw-rev-constitution.py" "$@"