aw-spec-cli 0.1.4 → 0.1.5

package/assets/.aw-spec/orchestrator/rev-templates/ai-rules.reference.md

@@ -0,0 +1,40 @@
+<!--
+  rev-templates/ai-rules.reference.md — domain-agnostic AI OPERATING rules for
+  the reverse-engineering authors. Unlike the other files in this folder this is
+  NOT a shape skeleton — it is genuine, generic operating guidance (how to
+  behave), and it asserts NO project principle, NO domain content, and NO tech
+  stack. It is safe to load directly. Kept here (not in the greenfield docs/
+  tree) so the brownfield reverse-engineering authors are self-contained on a real
+  brownfield repo.
+-->
+# AI Operational Rules (reverse-engineering)
+
+> Pure operating rules — domain-agnostic, stack-agnostic. Applies to every brownfield
+> reverse-engineering authoring step (onboard's constitution + rule-pack authors, adopt).
+
+The **code, the deterministic scan, and any adopted spec.md / design.md / source-map.md + the
+OKF bundle are ground truth.** Author only what they evidence; they override any pre-trained
+habit and any greenfield template ideal.
+
+## Evidence discipline
+
+- Author a principle / rule ONLY for a trait the adopted docs actually evidence. If the code does
+  not show it, it is not a rule here.
+- CITE the concrete proof inline (a design section, a named type / port / config, a spec id). An
+  assertion you cannot ground does not belong in the output.
+- State partial / stubbed / optional behaviour AT THE LEVEL THE CODE REACHES — never the ideal.
+  Route unmet ideals / stubs / deferrals to the as-built debt list, never assert them.
+
+## Format vs content
+
+- The skeletons in this folder are SHAPE ONLY. Copy their headings, frontmatter, and tone; never
+  copy a bracketed token or an example concept as if it were this project's value.
+- Do NOT import a concept, identifier, terminology, regulatory claim, or rule that this project's
+  code / specs / designs do not evidence.
+
+## Operating envelope
+
+- Write ONLY the declared output target (or, for the pack, only inside the pack folder). No
+  drive-by edits to unrelated files.
+- No secrets, connection strings, or production hostnames in any authored file.
+- Preserve the rule partition: design and implement receive no domain file.

package/assets/.aw-spec/orchestrator/rev-templates/comandrulemap.skeleton.md

@@ -0,0 +1,59 @@
+<!--
+  rev-templates/comandrulemap.skeleton.md — SHAPE-ONLY reference for the pack's
+  comandrulemap.md (note the exact misspelling: resolve-domain reads it by that
+  name). It shows the five per-command headings, the RULE PARTITION (design +
+  implement get NO domain file), the bullet shape, and the quick-reference
+  table. It lists NO real rule files — every bullet is a placeholder for a file
+  the pack author actually generated from THIS project's evidence.
+
+  Wire ONLY files you generated. Never list a file you did not write.
+-->
+# [PROJECT_NAME] Domain — Command → Rule-File Map
+
+Per-command list of the **[PROJECT_NAME] domain** rule files loaded (via `resolve-domain` +
+`domain-select`, into the sticky standards set) for the spec-anchored orchestrator pipeline.
+
+**The model (see `.aw-spec/RULE-PARTITION.md`):** domain files feed only three
+consumers — **specify** (authors them into the spec as FR/BR/CN-/DC-/IC-), **constitution** (the
+domain principles), and the **gates** (conformance checklist). **design** and **implement** load
+**NO** domain file — the domain reaches them solely through the spec/design ids. This is the rule
+partition; preserve it exactly.
+
+- All paths are workspace-relative and live in `docs/domainspecs/[domain]/`.
+- `resolve-domain --command <name>` collects the `- ` bullets under `## /<name>`.
+
+---
+
+## /aw-spec-constitution
+<!-- Domain identity / regulatory / interop sources that become domain principles in
+     constitution.domain.md. -->
+- docs/domainspecs/[domain]/[identity-or-requirements-file].md
+- docs/domainspecs/[domain]/[each generated domain-principle source].md
+
+## /aw-spec-specify
+<!-- The FULL generated domain set. Specify models the domain and LIFTS the overlay constraints
+     into the spec's CN-/DC-/IC- (design/implement never see these files). -->
+- docs/domainspecs/[domain]/[each generated domain rule file].md
+
+## /aw-spec-design
+_None — design loads no domain file. Domain reaches design only through the spec (BR-/CN-/DC-/IC-)._
+
+## /aw-spec-implement
+_None — implement loads no domain file. Domain reaches implement only through design.md._
+
+## /aw-spec-gate
+<!-- Conformance checklist for the gates (analyze-design · analyze-slice): the domain-derived
+     constraints design/implement were NOT given as authoring input, VALIDATED against output. -->
+- docs/domainspecs/[domain]/[each *.domain.md overlay to validate against].md
+
+---
+
+## Quick reference (command → domain file count)
+
+| Command | Domain rule files | Role |
+|---|---|---|
+| /aw-spec-constitution | [n] | domain principles |
+| /aw-spec-specify | [n] | author into spec (lift → CN-/DC-/IC-) |
+| /aw-spec-design | 0 | none — spec is the only domain input |
+| /aw-spec-implement | 0 | none — design is the only domain input |
+| /aw-spec-gate | [n] | conformance checklist (validate, don't author) |

package/assets/.aw-spec/orchestrator/rev-templates/commandtechrulemap.skeleton.md

@@ -0,0 +1,97 @@
+<!--
+  rev-templates/commandtechrulemap.skeleton.md — SHAPE-ONLY reference for the
+  pack's commandtechrulemap.md (resolve-tech reads it by that exact name — the
+  TECHNICAL twin of comandrulemap.md, which resolve-domain reads). It shows the
+  per-command headings, the TECHNICAL RULE PARTITION, the bullet shape, and the
+  quick-reference table. It lists NO real rule files — every bullet is a
+  placeholder for a tech/ file the pack author actually generated from THIS
+  project's CODE.
+
+  Wire ONLY files you generated (all under docs/domainspecs/[domain]/tech/).
+  Never list a file you did not write. Never list a greenfield docs/architecture,
+  docs/security, docs/governance, or docs/interop path — those are the greenfield
+  fixture and are NOT this project's rules.
+-->
+# [PROJECT_NAME] — Command → Technical-Rule-File Map (as-built)
+
+Per-command list of the **[PROJECT_NAME] technical** rule files loaded (via `resolve-tech` +
+the `tech-select` module, into the sticky standards set) for the spec-anchored orchestrator
+pipeline. This is the technical counterpart of `comandrulemap.md` (which maps the DOMAIN rule
+files), and the CODE-DERIVED replacement for the greenfield technical map.
+
+**The model:** the technical rule files (this project's own architecture / persistence /
+concurrency / testing / security-posture set, reverse-engineered from the code into
+`docs/domainspecs/[domain]/tech/`) are CONFIGURATION — tune this map, not the workflows. The
+technology base itself (`constitution.technical.md`) is NOT listed here — every consumer still
+refers to it directly, as-is.
+
+- All paths are workspace-relative and live in `docs/domainspecs/[domain]/tech/`.
+- `resolve-tech --command <name>` collects the `- ` bullets under `## /<name>`.
+- **`## /aw-spec-specify` is the MODELLING-METHODOLOGY slot** — exactly one file,
+  `tech/domain-modelling.md`: HOW this code expresses a domain model. Never an architecture /
+  persistence / codegen / security file; those would break specify's domain purity. Every other
+  heading below feeds the HOW phases.
+- A command with no heading here loads no mapped technical file (only the workflow's universal
+  `ai-rules.md` seed + `constitution.technical.md`, referred to directly).
+
+---
+
+## /aw-spec-specify
+<!-- MODELLING METHODOLOGY ONLY — exactly one file. HOW this codebase expresses a domain model
+     (what marks an aggregate root, entity vs value object, where invariants live, the context
+     boundary), NOT what the model is (that is the domain pack's domain-driven-design.domain.md,
+     wired via comandrulemap). No technology rule may appear under this heading. -->
+- docs/domainspecs/[domain]/tech/domain-modelling.md
+
+## /aw-spec-design
+<!-- The as-built architecture / cross-cutting technical rules the design author mediates the spec
+     against. NO domain file here — domain reaches design only as spec ids. -->
+- docs/domainspecs/[domain]/tech/[as-built-architecture].md
+- docs/domainspecs/[domain]/tech/[each generated architecture/cross-cutting rule].md
+
+## /aw-spec-implement
+<!-- The framework / code-generation rule set the generator builds against (from design.md). -->
+- docs/domainspecs/[domain]/tech/[each generated codegen/convention rule].md
+
+## /aw-spec-implement-delta
+<!-- The CR analog of implement — same code-generation set, scoped to the delta-design. -->
+- docs/domainspecs/[domain]/tech/[each generated codegen/convention rule].md
+
+## /aw-spec-build
+<!-- The layering + convention rules the compile-fixer respects. -->
+- docs/domainspecs/[domain]/tech/[as-built-architecture].md
+
+## /aw-spec-analyze-slice
+<!-- The design↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
+- docs/domainspecs/[domain]/tech/[testing/convention rule to validate against].md
+
+## /aw-spec-adopt
+<!-- Brownfield reverse-engineering: the technical REFERENCE set the reversed design mediates the
+     reversed spec ↔ existing code against — the CODE wins, these are reference only. -->
+- docs/domainspecs/[domain]/tech/[architecture/cross-cutting reference rule].md
+
+## /aw-spec-run
+<!-- The runtime / execution conventions the app-run step honors — add ONLY if the code evidences
+     a runtime/hosting concern file. NOT data-migration (migration is the deferred later phase). -->
+- docs/domainspecs/[domain]/tech/[runtime/hosting rule].md
+
+<!-- Do NOT add /aw-spec-characterize or /aw-spec-parity in the DEV flow — characterize is
+     opt-on-touch and parity is deferred to the migration phase. /aw-spec-constitution is NOT
+     mapped either (constitution.technical.md is referred to directly). Add such a heading later
+     ONLY if that phase is entered AND you generated a file it should load — an absent heading
+     soft-continues (loads nothing). -->
+
+---
+
+## Quick reference (command → technical file count)
+
+| Command | Technical rule files | Role |
+|---|---|---|
+| /aw-spec-specify | 1 | the as-built modelling methodology the domain model is expressed in — no technology |
+| /aw-spec-design | [n] | as-built architecture the design author mediates the spec against |
+| /aw-spec-implement | [n] | code-generation set the generator builds against (from design.md) |
+| /aw-spec-implement-delta | [n] | same code-generation set, scoped to the open change's delta-design |
+| /aw-spec-build | [n] | layering + convention rules the compile-fixer respects |
+| /aw-spec-analyze-slice | [n] | conformance rules the design↔code gate validates against |
+| /aw-spec-adopt | [n] | technical reference set for the reversed design (brownfield) |
+| /aw-spec-run | [n] | runtime/execution conventions the app-run step honors (only if evidenced) |

package/assets/.aw-spec/orchestrator/rev-templates/domain-constitution.skeleton.md

@@ -0,0 +1,61 @@
+<!--
+  rev-templates/domain-constitution.skeleton.md — SHAPE-ONLY reference for the
+  domain-constitution SOURCE (docs/[domain]-constitution.md), the human-readable
+  charter the domain half is authored from (so the normal /aw-spec-orch
+  constitution can re-derive it later). It shows the Project-Identity + Domain-
+  Principle shape ONLY. No principle set to inherit; every principle is
+  discovered from the adopted specs and cited.
+
+  THIS IS A PROJECT CHARTER, NOT AN AGGREGATE SPEC. Even with one adopted
+  aggregate, describe the domain / bounded context AS A WHOLE — the adopted
+  aggregate(s) are the current evidence, never the subject.
+-->
+# [PROJECT_NAME] Domain Constitution (as-built)
+
+> `origin: reverse-engineered` · [YYYY-MM-DD]. Domain addenda to the technology base — compose
+> with the technical half; not ratified on its own.
+
+## Project Identity
+
+- **Project name:** [PROJECT_NAME] (from the OKF overview).
+- **Mission:** [from the OKF overview Purpose].
+- **Bounded contexts / aggregate map:** [list the adopted aggregate(s) AND named external
+  references / ports as not-yet-adopted contexts — from the overview's aggregate map + index].
+- **Architecture posture:** [as-built posture named from the designs — not an ideal].
+
+## Domain Principles
+
+<!-- Numbered to CONTINUE the technology base, which is authored later and is evidenced-only (do
+     NOT assume it ends at any fixed numeral). Use a stable "D1, D2, …" convention here; the
+     composed constitution assigns the exact roman numerals. TITLE each by its DOMAIN CONCERN,
+     never by an aggregate name. State each as a rule that would still hold if a second aggregate
+     entered the same context; cite the aggregate(s) + spec ids as the evidence it generalises. -->
+
+### D1 — [DOMAIN-CONCERN TITLE] [(NON-NEGOTIABLE)?]
+[The rule the code ACTUALLY enforces — as-built, testable. Note an observed gap as a plain
+principle, not a target.]
+Extends technology [principle ref]. Evidence: [BR-/CN-/DC-/IC-/FR- ids]. → [pack file(s)]
+
+### D2 — [DOMAIN-CONCERN TITLE] [(NON-NEGOTIABLE)?]
+[…]
+Extends technology [principle ref]. Evidence: [ids]. → [pack file(s)]
+
+<!-- … one per domain concern the specs evidence … -->
+
+## Folder Structure Additions
+
+- [Only domain-specific additions the module actually uses; otherwise "none beyond the base".]
+
+## Security & Governance Addenda
+
+- [As-built posture: auditability, authorization surface, classification — named from evidence.]
+- [Stub/permissive adapters recorded as migration debt, not claimed as satisfied ideals.]
+
+## Governance Overrides
+
+- [Domain change-authority / mandatory approvers — observed or TODO(GOVERNANCE): assign.]
+- Base amendment procedure and SemVer policy in the technical half still apply.
+
+## Domain Requirements Pointer
+
+→ docs/domainspecs/[domain]/domain-requirements.md

package/assets/.aw-spec/orchestrator/rev-templates/domain-requirements.skeleton.md

@@ -0,0 +1,48 @@
+---
+origin: reverse-engineered
+generated_by: aw-spec-onboard/[VERSION]
+---
+<!--
+  rev-templates/domain-requirements.skeleton.md — SHAPE-ONLY reference for the
+  pack's domain-requirements.md: a PROJECT-LEVEL overview of the domain the pack
+  governs (not a single-aggregate spec). It opens with a bounded-context /
+  module map (from the OKF overview + aggregate index), then per-subsection
+  pointers to the generated rule files, platform topology, and governance
+  overrides. Fill the map from the ACTUAL adopted aggregates + named external
+  references; add a subsection pointer ONLY for a file you generated.
+-->
+# DOMAIN REQUIREMENTS — [PROJECT_NAME] (project-level)
+
+> Project-level enumeration and headline profiles for the **[PROJECT_NAME]** domain. Detailed
+> domain rules are expanded in the sibling files in this folder. Reverse-engineered, as-built.
+
+=====================================================================
+[DOMAIN: Bounded Contexts / Modules]
+=====================================================================
+- [Context / module] — aggregate root: **[Aggregate]** (adopted — current evidence); owns
+  [entities] and the value objects ([named VOs]). See [[domain-driven-design.domain]].
+- [Named external reference / port] — [role]; not adopted as an aggregate.
+- [… list each bounded context observed in the OKF overview / aggregate index …]
+
+=====================================================================
+[DOMAIN: subsection pointers]
+=====================================================================
+[DOMAIN: <subsection>]        -> docs/domainspecs/[domain]/[generated-file].md
+[DOMAIN: <subsection>]        -> docs/domainspecs/[domain]/[generated-file].md
+[DOMAIN: Platform Topology]   -> below
+
+=====================================================================
+[DOMAIN: Platform Topology]
+=====================================================================
+- [Runtime / external dependencies AS INVENTORIED — from the OKF overview/platform note, not an ideal.]
+- [Only what the platform actually declares; unknowns are Open Questions, not assumed capabilities.]
+
+=====================================================================
+[DOMAIN: Governance Overrides]
+=====================================================================
+- [Approvers / change-authority observed or TODO(GOVERNANCE): assign at ratification.]
+- [Any domain-specific review trigger the code/specs evidence.]
+
+## Related
+
+- [[domain-driven-design.domain]] · [[<generated siblings>]]

package/assets/.aw-spec/orchestrator/rev-templates/domain-rule-file.skeleton.md

@@ -0,0 +1,39 @@
+---
+origin: reverse-engineered
+generated_by: aw-spec-onboard/[VERSION]
+concern: "[concern-slug]"
+---
+<!--
+  rev-templates/domain-rule-file.skeleton.md — SHAPE-ONLY reference for ONE
+  generated `<concern>.domain.md` overlay in the pack. Write one such file per
+  concern the adopted specs/designs ACTUALLY exhibit (evidenced-only, lean) —
+  e.g. domain-driven-design, persistence, auditing, authorization, cqrs,
+  eventing, data-classification, api-versioning, or a domain reference file for
+  an identifier/vocabulary the code uses.
+
+  Every rule below MUST trace to a BR-/CN-/DC-/IC-/FR- id, a named value object
+  / port / entity, or the OKF overview. No rule the code does not evidence.
+  Keep the frontmatter (origin + generated_by + concern). Copy the SHAPE only.
+-->
+# [Concern] — [PROJECT_NAME] Domain Addenda
+
+> Technology base: [[<technical-base-concern>]]. Commands: [the commands this file feeds, per the partition].
+
+> [One-line framing of what this concern IS in this project — from evidence, not an ideal.]
+
+## [Section — e.g. Categories / Rules / Invariants]
+
+- [As-built rule the code enforces.] (evidence: [BR-/CN-/DC-/IC-/FR- id or named type])
+- [As-built rule.] (evidence: […])
+
+## [Section — e.g. Exposure & logging / Constraints / Lifecycle]
+
+- [As-built rule.] (evidence: […])
+
+<!-- Where the code's behaviour is a stub / partial / permissive, STATE IT AS-BUILT and note that
+     the CONTRACT still stands (stub behaviour is migration debt, not a waiver) — do not upgrade a
+     stub into a satisfied ideal. -->
+
+## Related
+
+- [[<sibling generated overlay>]] · [[<technical-base-concern>]]

package/assets/.aw-spec/orchestrator/rev-templates/technical-constitution.skeleton.md

@@ -0,0 +1,106 @@
+<!--
+  ═══════════════════════════════════════════════════════════════════════════
+  rev-templates/technical-constitution.skeleton.md — SHAPE-ONLY reference.
+
+  This file is the FORMAT + VOCABULARY reference for the reverse-engineered
+  TECHNICAL half (constitution.technical.md). It is loaded as a `standards:`
+  entry for the technical-half author (include_standards:true). It carries the
+  AppWeaver principle-heading style, the Sync-Impact-Report shape, the
+  evidence-line pattern, and the section skeleton — and NOTHING ELSE.
+
+  IT DELIBERATELY CONTAINS NO PRINCIPLE SET. There is no fixed I–XV list to
+  inherit. Every [BRACKET] token below is a slot the author fills from evidence
+  — never a value to copy. Copy the SHAPE, discover the CONTENT from the code.
+
+  DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
+  here to leak):
+    • EVIDENCE-FIRST — author a principle ONLY for a technology trait the
+      adopted design.md files + the OKF overview/platform note actually
+      evidence. If the code does not show it, it is not a principle.
+    • CITE inline — every principle ends with an `(evidence: …)` line naming a
+      design section, a concrete type / port / DbContext / config, or an OKF
+      stack line. A principle with no groundable evidence does not belong.
+    • AS-BUILT LEVEL — state a partial / stubbed / optional trait at the level
+      the code actually reaches; never the aspirational ideal.
+    • OMIT pure aspiration — a trait the code shows zero of is not softened into
+      a principle; it is left out.
+    • ROUTE gaps — an unmet ideal / stub / inactive-optional concern goes into
+      the "As-Built Debt → migration backlog" list below, never asserted.
+    • VARIABLE LENGTH — number sequentially from I with no gaps and no padding
+      to a fixed count. The final numeral is the domain half's continuation
+      point.
+  ═══════════════════════════════════════════════════════════════════════════
+-->
+<!--
+Sync Impact Report
+- Version: [OLD] -> [NEW]   (reverse-engineered technical baseline)
+- Project: [PROJECT_NAME]
+- Discovered technical principles: I–[N] (domain half continues at [N+1])
+- Principle set (as-built):
+  I   [PRINCIPLE_TITLE]
+  II  [PRINCIPLE_TITLE]
+  …   (only traits the code evidences — no fixed count)
+- Template ideals DELIBERATELY OMITTED (lack of as-built evidence):
+  - [IDEAL] — [why the code does not evidence it]
+  - …
+- As-Built Debt → migration backlog (see knowledge/migration-backlog.md; do not restate the table):
+  - [gap / stub / inactive-optional concern] — [where it is tracked]
+  - …
+- Dependent artifacts:
+  - constitution.domain.md — ⚠ authored next; continues at [N+1]
+  - docs/[domain]-constitution.md — [✅/⚠] domain charter source
+  - docs/domainspecs/[domain]/ — [✅/⚠] pack
+- TODOs: [none mechanical | …]
+-->
+# [PROJECT_NAME] Constitution — Technical Base
+
+> Reverse-engineered, **as-built**, domain-agnostic technical half. Authority for DESIGN and
+> IMPLEMENT. Domain principles live in `constitution.domain.md` (continues at **[N+1]**).
+> This file asserts only technology traits evidenced by the adopted designs + OKF overview/platform.
+
+## Core Principles
+
+<!-- One block PER EVIDENCED TRAIT. Tag (NON-NEGOTIABLE) only where the code enforces it as such.
+     Replace the bracketed text; keep the `### <numeral>. <title>` + rule + `(evidence: …)` shape. -->
+
+### I. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
+[One declarative, testable rule the adopted designs actually evidence. State it at the level the
+code reaches — partial/stubbed/optional traits are stated as partial, not as the ideal.]
+(evidence: [design §X.Y named type / port / DbContext / config; or OKF overview Tech-stack line])
+
+### II. [PRINCIPLE TITLE] [(NON-NEGOTIABLE)?]
+[…]
+(evidence: […])
+
+<!-- … continue with only the principles the code evidences … -->
+
+> **Domain half continues at principle [N+1]** in `constitution.domain.md`.
+
+## Mandatory Folder Structure (base)
+
+- [Solution projects / module layout AS INVENTORIED — from the OKF overview + designs, not an ideal.]
+- [Cross-cutting host files that stay at their template levels.]
+- Domain-specific folder additions (if any) are declared only in the domain constitution half.
+
+## Conventions, Forbidden Patterns, AI Rules & Quality Gates (base)
+
+- [Prefer the framework abstractions ALREADY in use — name them from evidence.]
+- [Forbidden patterns the code's structure implies — e.g. no cross-aggregate write, endpoints do not touch persistence.]
+- Base AI operating rules: [pointer to the operating-rules reference].
+- Any pre-existing greenfield standards docs are **reference only** until reverse-engineered against
+  this codebase — where they conflict with the as-built evidence above, **this constitution wins**.
+
+## Governance
+
+- This technical half + the paired domain half supersede README / agent-context files where they
+  disagree on engineering rules.
+- Amendments via PR that updates the affected half (+ pack/docs if needed), includes a migration
+  plan for non-compliant code, and bumps SemVer:
+  - **MAJOR** — remove/weaken a NON-NEGOTIABLE principle or break mandatory structure
+  - **MINOR** — add a principle or mandatory section
+  - **PATCH** — clarifications
+- Reviewers cite principle numbers. Domain change-authority overrides live in the domain half.
+- Runtime agent guidance MUST point at the composed constitution and MUST NOT restate these
+  principles at length.
+
+**Version**: [X.Y.Z] | **Ratified**: [YYYY-MM-DD] | **Last Amended**: [YYYY-MM-DD]

package/assets/.aw-spec/orchestrator/rev-templates/technical-rule-file.skeleton.md

@@ -0,0 +1,54 @@
+---
+origin: reverse-engineered
+generated_by: aw-spec-onboard/[VERSION]
+concern: "[concern-slug]"
+---
+<!--
+  rev-templates/technical-rule-file.skeleton.md — SHAPE-ONLY reference for ONE
+  generated technical rule file in the pack's tech/ folder
+  (docs/domainspecs/[domain]/tech/<concern>.md). It is the TECHNICAL twin of
+  domain-rule-file.skeleton.md. Write one such file per TECHNOLOGY concern the
+  CODE ACTUALLY exhibits (evidenced-only, lean) — e.g. as-built-architecture,
+  persistence, concurrency, testing, security-posture, api-surface, eventing,
+  observability, hosting — NOT per domain concern (those are the *.domain.md
+  overlays), NOT per greenfield ideal.
+
+  ONE concern in this pack is not a technology concern and is still written here:
+  `domain-modelling` — the as-built modelling METHODOLOGY (what marks an aggregate
+  root, entity vs value object, where invariants live, the context boundary). It is
+  the only file wired under `## /aw-spec-specify`, and it carries NO business
+  vocabulary: HOW this code models, never WHAT it models (that is the domain pack's
+  domain-driven-design.domain.md). Same shape as below — cite code coordinates.
+
+  Every rule below MUST cite a CODE COORDINATE (a real file/folder path or named
+  type) and, where it maps, the technical-constitution principle numeral it
+  details. This is the DETAIL layer under constitution.technical.md — the thin
+  ratified principle points here; here is the enforceable rule. State what the
+  code DOES (quirks, stubs, partials included), never a greenfield assumption.
+  Keep the frontmatter (origin + generated_by + concern). Copy the SHAPE only —
+  this file carries NO real technology, path, or framework name.
+-->
+# [Concern] — [PROJECT_NAME] Technical Rule (as-built)
+
+> Ratified by: constitution.technical.md principle [N] ([short principle title]).
+> Commands: [the technical commands this file feeds, per the partition — e.g. design · implement · build].
+
+> [One-line framing of what this concern IS in this codebase — from the code, not an ideal.]
+
+## [Section — e.g. Structure / Layering / Rules / Contracts]
+
+- [As-built rule the code follows.] (code: [real file/folder path or named type]; principle [N])
+- [As-built rule.] (code: […])
+
+## [Section — e.g. Dependency direction / Constraints / Conventions]
+
+- [As-built rule.] (code: […])
+
+<!-- Where the code's behaviour is a stub / partial / permissive / inactive, STATE IT AS-BUILT at the
+     level the code reaches, and mark it so — do NOT upgrade a stub into a satisfied greenfield ideal,
+     and do NOT invent a rule the code does not evidence. An unmet ideal is simply omitted here
+     (migration/modernization is a separate later phase, not this pack's concern). -->
+
+## Related
+
+- [[<sibling generated tech rule>]] · constitution.technical.md principle [N]

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

@@ -0,0 +1,160 @@
+# =============================================================================
+# _smoke — CI smoke workflow for the orchestrator engine (no model, no writes
+# outside .aw-spec/orchestrator/.smoke-out)
+#
+# Exercises every extended construct in one run: inputs, set (raw object),
+# execute_script (read-only subcommand), verify_context gates, ask
+# (non-interactive default), foreach + while loops + break, agent_query
+# (mock:), agent_author (mock content), build_context, include
+# (domain-select module), dispatch_hooks (empty).
+#
+# Run:
+#   python3 .aw-spec/orchestrator/orchestrator.py \
+#     .aw-spec/orchestrator/workflows/_smoke.orch.yaml --non-interactive --json
+# Expected: status ok, echo=hello, sum of foreach passes, smoke.md written.
+# =============================================================================
+
+name: orch-smoke
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional text echoed into the authored artifact.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .aw-spec/scripts/bash/aw-spec-actions.sh
+    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  out_dir: .aw-spec/orchestrator/.smoke-out
+  seen: ""
+
+workflow:
+
+  # set with a raw list (resolve_value keeps it a real list)
+  - id: seed
+    action: set
+    vars:
+      fruits: ["apple", "banana"]
+      echo: "hello"
+
+  # F1: read-only script subcommand; outputs[] binding
+  - id: script_ro
+    action: execute_script
+    script: { ref: actions }
+    subcommand: list-domains
+    outputs:
+      - { name: domains, from: "$.domains" }
+
+  # F2: gates — value gate + non-empty gate (informational, no stop)
+  - id: gate_value
+    action: verify_context
+    require_value: echo
+    equals: "hello"
+    on_mismatch: stop
+    on_mismatch_message: "set/resolve is broken"
+  - id: gate_nonempty
+    action: verify_context
+    require_non_empty: domains
+    on_empty_message: "no domains found (allowed in smoke)"
+
+  # F7: ask — --non-interactive picks the first option
+  - id: pick_mode
+    action: ask
+    prompt: "Smoke mode?"
+    options: ["fast", "slow"]
+    answer_var: mode
+  - id: gate_mode
+    action: verify_context
+    require_value: mode
+    equals: "fast"
+    on_mismatch: stop
+    on_mismatch_message: "non-interactive ask default is broken"
+
+  # F3: foreach over a list var, binding item + item_index
+  - id: each_fruit
+    action: loop
+    over: "{{fruits}}"
+    as: fruit
+    steps:
+      - id: collect
+        action: set
+        vars:
+          seen: "{{seen}}{{fruit}}@{{fruit_index}};"
+
+  # while + break still work
+  - id: count
+    action: loop
+    while: "true"
+    max_iterations: 3
+    steps:
+      - id: stop_at_1
+        action: break
+        condition: "{{iteration}} == 1"
+
+  # F6: structured query — mock: supplies the result in mock transport
+  - id: q_shape
+    action: agent_query
+    schema: { ok: true, items: [] }
+    mock: { ok: true, items: ["one", "two"] }
+    task: Report ok plus a short list of items.
+    outputs:
+      - { name: q_ok,    from: "$.ok" }
+      - { name: q_items, from: "$.items" }
+  - id: gate_q
+    action: verify_context
+    require_true: q_ok
+    on_false: stop
+    on_false_message: "agent_query mock/result binding is broken"
+
+  # F3 again: foreach over a query-produced list
+  - id: each_item
+    action: loop
+    over: "{{q_items}}"
+    as: it
+    steps:
+      - id: collect_items
+        action: set
+        vars:
+          seen: "{{seen}}{{it}};"
+
+  # context management stays with the orchestrator: envelope for the author step
+  - id: ctx_author
+    action: build_context
+    context:
+      - { path: "{{out_dir}}/smoke.md", optional: true }
+
+  # F5: authored artifact — engine writes the file (mock content here)
+  - id: author_doc
+    action: agent_author
+    output_target: { type: file, path: "{{out_dir}}/smoke.md" }
+    task: "Write a one-paragraph smoke report. Echo: {{echo}} {{USER_INPUT}}"
+
+  # F2: file gate against what the engine just wrote
+  - id: gate_file
+    action: verify_context
+    required_files: ["{{out_dir}}/smoke.md"]
+
+  # F9: include — the shared domain-select module (read-only script + asks;
+  # non-interactive: gate→continue, mode→all)
+  - id: domain
+    action: include
+    module: .aw-spec/orchestrator/modules/domain-select.orch.yaml
+    with:
+      command: specify
+
+  # F8: hooks — empty var logs 'none'
+  - id: hooks
+    action: dispatch_hooks
+    hooks_from_variable: no_hooks_declared
+
+outputs:
+  echo: "{{echo}}"
+  mode: "{{mode}}"
+  seen: "{{seen}}"
+  q_items: "{{q_items}}"
+  domain: "{{domain}}"
+  note: "all engine constructs exercised"