aw-spec-cli 0.1.8 → 0.1.10

package/assets/.appweaver/templates/constitution-technical-template.md

@@ -0,0 +1,108 @@
+# [PROJECT_NAME] Constitution — Technical Base
+<!--
+  AppWeaver split-constitution model. This is the TECHNICAL half — the
+  domain-agnostic constitution derived from the set mapped under
+  "## /aw-spec-constitution" in the active project's tech-rule-bindings.md: the technology
+  base (the mapped stack corpus's technology-constitution.md — its principles and base
+  governance), that corpus's STANDARD technical rules, and the project team's own
+  service/technical-requirements.md. A project reverse-engineered by `onboard` has no
+  such set when this half is authored: there the AS-BUILT CODE is the whole evidence, and
+  the rule files are generated afterwards as the detail layer under whatever is ratified
+  here.
+  It carries NO domain-specific principle, identifier, terminology, or regulatory rule —
+  those live in the paired constitution.domain.md.
+
+  ══ THIS FILE IS SHAPE. THE EVIDENCE IS CONTENT. ══════════════════════════════════
+  This template is part of the kit and governs projects in any industry, any language
+  and any stack. It therefore names NO technology, library, type, framework or
+  architectural pattern anywhere — deliberately. An example that named one would be a
+  suggestion, and a suggestion in a template becomes ratified law in a project it does
+  not fit.
+
+  Take the principles — their SUBJECTS, their WORDING, their ORDER and their COUNT —
+  from the evidence the run puts in front of you: the mapped technology base and the
+  project's own technical-requirements where a corpus is mapped, and the CODEBASE ITSELF
+  where this half is being reverse-engineered from an existing repo and no map exists
+  yet. Never from this file, and never from a stack you happen to know. If the evidence
+  supports eight principles this half ends at VIII; if it supports twenty-six it ends at
+  XXVI. The five slots below are a scaffold, not a set: add or delete '### ' blocks
+  freely and number them I, II, III … in the evidence's own order. The domain half
+  resumes at the number after your last one, so where you stop is a fact the domain half
+  depends on.
+  ═══════════════════════════════════════════════════════════════════════════════════
+
+  Where the project's own requirements file diverges from a standard rule, that is a
+  DEVIATION: ratify it as one, naming the rule it departs from and who approved it.
+
+  This file is the standing technical authority for the TECHNICAL authoring phases —
+  DESIGN and IMPLEMENT (specify loads constitution.domain, not this; the gates load
+  neither). Keeping it domain-free is what lets design author architecture from "spec
+  + technical docs only" and lets the tech base stay swappable. Do NOT add domain
+  principles here.
+
+  THIN AUTHORITY: each principle is ONE declarative, testable line + a pointer to its
+  rule doc. Do NOT restate the rule doc's detail here — this file says WHICH rules are
+  supreme/non-negotiable and adopted; the docs (also loaded in the phase) carry the
+  detail. That keeps the authority/detail overlap to one line.
+-->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Form: "I. <the base's first principle, by its own name> (NON-NEGOTIABLE)". The
+     numeral, the name and whether the marker applies all come from the mapped base. -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Form: ONE declarative, testable sentence saying what MUST hold, then the rule doc
+     that carries the detail. State the rule, not the mechanism that implements it —
+     an implementation choice belongs in the rule doc, not in the ratified line. -->
+
+### [PRINCIPLE_2_NAME]
+[PRINCIPLE_2_DESCRIPTION]
+
+### [PRINCIPLE_3_NAME]
+[PRINCIPLE_3_DESCRIPTION]
+
+### [PRINCIPLE_4_NAME]
+[PRINCIPLE_4_DESCRIPTION]
+
+### [PRINCIPLE_5_NAME]
+<!-- Form: continue one '### ' block per principle through the base's LAST one, then
+     stop. Do not pad to a round number, do not stop early because a count "looks
+     right", and do not import a principle the base does not state. Mark NON-NEGOTIABLE
+     only where the base does. -->
+[PRINCIPLE_5_DESCRIPTION]
+
+## [SECTION_2_NAME]
+<!-- Form: the base's structural mandate — how the codebase must be laid out and what
+     that layout is not allowed to blur. Name the section as the base names it. -->
+
+[SECTION_2_CONTENT]
+<!-- Form: the layout as the base defines it for THIS project's stack, plus a pointer to
+     the rule doc holding the full structure. Domain folder ADDITIONS are declared in
+     constitution.domain.md, not here. -->
+
+## [SECTION_3_NAME]
+<!-- Form: the base's conventions / forbidden-patterns / quality-gate section. -->
+
+[SECTION_3_CONTENT]
+<!-- Form: naming and coding conventions, forbidden patterns, dependency governance, CI
+     quality gates and the base AI operating rules — each a thin adopted line pointing at
+     the rule doc that carries it. Domain overlays are referenced from
+     constitution.domain.md. -->
+
+## Governance
+<!-- Form: this constitution's authority over other engineering guidance, the amendment
+     procedure, and the versioning policy. This base governance also applies to
+     constitution.domain.md; domain-specific approver / change-authority overrides are
+     declared there. -->
+
+[GOVERNANCE_RULES]
+<!-- Form: amendment procedure; SemVer-for-governance (MAJOR = weaken a NON-NEGOTIABLE or
+     break the mandated structure; MINOR = new principle or mandatory requirement;
+     PATCH = clarification); compliance review cadence. Reviewers cite the principle
+     NUMBER, so the numbering above is load-bearing. The paired constitution.domain.md
+     extends this section with domain change-authority. -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- ISO YYYY-MM-DD dates. This file versions INDEPENDENTLY of constitution.domain.md —
+     a technical-base change need not bump the domain half, and vice-versa. -->

package/assets/.appweaver/templates/constitution-ui-template.md

@@ -0,0 +1,116 @@
+# [PROJECT_NAME] Constitution — User Experience Base
+<!--
+  AppWeaver split-constitution model. This is the UI half — the standing
+  governance for the FRONTEND LANE, derived from the set mapped under
+  "## /aw-spec-ui-constitution" in the active project's tech-rule-bindings.md: the standard
+  frontend rules (the mapped lane corpus's ui-constitution.md) and the project team's own
+  frontend/ui-requirements.md. A lane reverse-engineered by `onboard` has no such set when
+  this half is authored: there the UI SOURCE is the whole evidence, and the lane's rule
+  files are generated afterwards as the detail layer under whatever is ratified here.
+  It exists only in a project that HAS a frontend lane;
+  a backend-only project has no such file at all.
+
+  ══ THIS FILE IS SHAPE. THE EVIDENCE IS CONTENT. ══════════════════════════════════
+  This template is part of the kit and governs frontends on any stack. It therefore
+  names NO framework, language, router, design system, component library or conformance
+  standard anywhere — deliberately. An example that named one would be a suggestion, and
+  a suggestion in a template becomes ratified law in a lane it does not fit.
+
+  Take the principles — their SUBJECTS, their WORDING, their ORDER and their COUNT —
+  from the evidence the run puts in front of you: the mapped ui-constitution.md and the
+  team's ui-requirements where a lane corpus is mapped, and the LANE'S OWN SOURCE where
+  this half is being reverse-engineered. The five slots below are a scaffold, not a set.
+  ═══════════════════════════════════════════════════════════════════════════════════
+
+  It is the UI lane's counterpart to constitution.technical.md, not a third tier
+  of governance. Like that file it is DOMAIN-FREE: it is authored before
+  domain-select runs, so no domain rule file can reach it. Domain reaches the UI
+  lane the same way it reaches the service lane — through the spec.
+
+  Loading policy: standing input to UI-DESIGN and UI-IMPLEMENT. It is NOT loaded
+  by specify (which loads constitution.domain.md), and NOT by the service lane's
+  design/implement (which load constitution.technical.md). One lane's
+  constitution never governs the other lane's code.
+
+  NUMBERING: principles are a UX-* series (UX-I, UX-II, …) and deliberately do NOT
+  continue the technical half's numbering or the domain half's. This half is PARALLEL
+  to the technical base, not a continuation of it, and the composed constitution.md
+  must not read as though one series ran on into another. Because the series is its
+  own, it is unaffected by how many principles the technology base happens to have.
+
+  WHAT THE LANE'S GOVERNANCE MUST SETTLE — as principles, in the lane rules' own terms:
+  the accessibility obligation; where visual truth comes from; that the UI's only input
+  from the service lane is the design contract, so an interface it needs but the contract
+  lacks is a contract change and never a local workaround; that every reachable
+  interaction state is a specified requirement rather than something invented in a
+  component; and the lane's own testing obligation. Cover what the mapped rules cover —
+  this list is the agenda, not the wording.
+
+  THIN AUTHORITY: each principle is ONE declarative, testable line. Do NOT restate
+  the source's detail here — this file says WHICH experience rules are supreme,
+  non-negotiable and adopted; the mapped ui-constitution.md carries the detail.
+-->
+
+## Declared Lane
+
+[UI_LANE_DECLARATION]
+<!-- Form: one line naming the lane, its stack and the root directory it owns — all three
+     taken from the mapped ui-constitution.md, which declares them, and never invented
+     here. The root is the subtree ui-implement may write; it must match
+     .appweaver/stacks.json where that file exists, and a disagreement is a STACK-MISMATCH:
+     failure, not a silent rewrite. -->
+
+## Experience Principles
+<!-- A UX-* series. Parallel to the technical half, never a continuation of it. -->
+
+### [PRINCIPLE_UX_1_NAME]
+<!-- Form: "UX-I. <the experience concern this rule governs> (NON-NEGOTIABLE)". -->
+[PRINCIPLE_UX_1_DESCRIPTION]
+<!-- Form: ONE declarative, testable sentence saying what MUST hold, plus a pointer to the
+     lane rule file that carries the detail. Where a principle depends on a threshold or a
+     conformance target, say that the target is binding and cite where the spec records
+     it — do not restate the target here, and do not invent one. -->
+
+### [PRINCIPLE_UX_2_NAME]
+[PRINCIPLE_UX_2_DESCRIPTION]
+
+### [PRINCIPLE_UX_3_NAME]
+[PRINCIPLE_UX_3_DESCRIPTION]
+
+### [PRINCIPLE_UX_4_NAME]
+[PRINCIPLE_UX_4_DESCRIPTION]
+
+### [PRINCIPLE_UX_5_NAME]
+<!-- Form: continue UX-V+ with one '### ' block per principle the mapped lane rules state,
+     then stop. Service-lane principles stay in constitution.technical.md and domain
+     principles in constitution.domain.md. -->
+[PRINCIPLE_UX_5_DESCRIPTION]
+
+## [UI_STRUCTURE_SECTION_NAME]
+<!-- Form: the lane's structural mandate, named as the lane rules name it. -->
+
+[UI_STRUCTURE_CONTENT]
+<!-- Form: the lane root and the layout beneath it, as the mapped rules define it for this
+     lane's stack, including where generated contract clients land. This layout sits
+     ENTIRELY under the lane's root; it never adds to the service lane's structure in
+     constitution.technical.md. -->
+
+## [UI_CONVENTIONS_SECTION_NAME]
+<!-- Form: the lane's conventions / forbidden-patterns / quality-gate section. -->
+
+[UI_CONVENTIONS_CONTENT]
+<!-- Form: naming, state-management policy, forbidden patterns, and the lane's CI gates —
+     each a thin adopted line pointing at the lane rule file that carries it. -->
+
+## Governance
+
+[UI_GOVERNANCE_RULES]
+<!-- Form: this half versions independently of the other two. The base amendment procedure
+     and SemVer policy in constitution.technical.md apply unchanged — state only the
+     UI-lane overrides here (who may amend the lane's visual authority, who signs off a
+     waiver against an accessibility obligation). Retiring the frontend lane is a decision
+     to retire this file; nothing removes it automatically. -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- ISO YYYY-MM-DD dates. Versions INDEPENDENTLY of constitution.technical.md and
+     constitution.domain.md — a change to the lane's rules bumps this file only. -->

package/assets/.appweaver/templates/delta-design-template.md

@@ -0,0 +1,69 @@
+# Delta Design — [CR-ID]: [TITLE]
+
+**Feature (aggregate)**: [Aggregate]
+
+**Base version**: [vX.Y]   <!-- the current master design version; the design phase bumps the minor on close -->
+
+<!--
+  This delta applies to the SINGLE master design at specs/[Aggregate]/design.md —
+  never a new design doc. Classify every design change ADDED / MODIFIED / REMOVED
+  against the current master, per LAYER section (Domain · Application · API · Infra),
+  in the SAME technology-agnostic form as the master: behaviour as signatures +
+  pre/post/invariant/raises, contracts as field shapes — NO code. A new command
+  (e.g. UpdateOrder) is a new USER STORY realised as delta design elements, NOT a
+  new feature/aggregate. After this delta is applied to design.md, `implement`
+  regenerates the touched slice; regression re-tests the shared-element dependents.
+-->
+
+## Change summary
+
+[One paragraph: what the design change is and which user story / spec delta it serves.]
+
+## ADDED — new design elements
+
+<!-- New entities/VOs/events, use-cases/handlers, endpoints, ports, adapters, and the
+     realisation of any new spec constraint/classification/contract. Serves = a spec id
+     (FR-/BR-/CN-/DC-/IC-/US-); design reads the spec, never the domain rule files. -->
+
+| Layer (§) | Element | Kind | Serves |
+|---|---|---|---|
+| Application (§2) | `[Command/Query]` + handler | use-case | US-[n] · FR-[nnn] |
+| API (§3) | `[VERB] [/route]` | endpoint | US-[n] · FR-[nnn] |
+| Domain (§1) | `[Event]` / `[VO]` | event / value object | BR-[nnn] · CN-[nnn] |
+| Infrastructure (§4.2) | `I[External]` adapter | contract realisation | IC-[nnn] |
+| Cross-cutting (§5) | [audit / retention / exposure decision] | constraint realisation | CN-[nnn] · DC-[nnn] |
+
+## MODIFIED — existing design elements
+
+<!-- Edits to elements the master already defines (add a behaviour, change a contract). -->
+
+| Layer (§) | Element | What changes | Why |
+|---|---|---|---|
+| Domain (§1) | `[Root].[Behaviour]` | add [method] + invariant | US-[n] |
+| Infrastructure (§4) | `I[Aggregate]Repository` | add [operation] | US-[n] |
+
+## REMOVED
+
+- [design element removed + why] — or `None`
+
+## Cross-layer impact
+
+[Which layer sections ripple; shared elements touched (e.g. the aggregate root);
+new migration needed? (yes/no); any contract change other systems couple to.]
+
+## Regression targets
+
+[Existing user stories / behaviours to re-verify because a shared element changed —
+e.g. re-test CreateOrder when the Order root or its repository is MODIFIED.]
+
+## New assumptions / workarounds (from this change)
+
+<!-- Anything this change defers — folds into the master's §7 / §8 ledgers on apply. -->
+
+- **DA-[n]**: [assumption to clarify later] — or `None`
+- **WA-[n]**: [structural workaround to clear later] — or `None`
+
+## On close
+
+The design phase amends the master design.md doc-first, appends the Change History
+row, bumps the version (minor), and archives this record under `changes/archive/`.

package/assets/.appweaver/templates/delta-spec-template.md

@@ -0,0 +1,63 @@
+# Delta Spec — [CR-ID]: [TITLE]
+
+**Feature (aggregate)**: [Aggregate]
+
+**Change type**: [new-requirement | changed-requirement | defect | refactor]
+
+**Created**: [DATE]
+
+**Base version**: [vX.Y]   <!-- the current master version; close-delta bumps the minor at the end of the chain -->
+
+<!--
+  A change request is a DELTA on the feature's existing spec.md — never a new spec.
+  Classify every item ADDED / MODIFIED / REMOVED against the current master, using
+  the SAME vocabulary as the master spec: System Requirements in EARS, Business
+  Rules (BR-n) as invariants, User Stories with Given/When/Then acceptance criteria,
+  and — where their rules apply — Constraints & NFRs (CN-n), Data Classification
+  (DC-n), Integration Contracts (IC-n) and Experience Standards (UX-n). A CR that changes
+  a retention/audit rule, a data-exposure rule, an interop obligation or a project-wide
+  experience standard is a CN-/DC-/IC-/UX- delta, not a smuggled code change. A UX- delta
+  states the standard only — never a screen, page or component, which the prototype and
+  design.ui.md settle. Adding a command (e.g. UpdateOrder to the Order aggregate) is a new
+  user story (US-n), NOT a new feature. Feature = aggregate (see spec-template.md).
+-->
+
+## Change summary
+
+[One paragraph: what is changing and why.]
+
+## ADDED
+
+<!-- New user stories, system requirements, business rules, entities, or lifted items (CN/DC/IC/UX). -->
+
+- **US-[n] — [title]** (Priority: P?)
+  - **Why this priority**: [the value and why it ranks here]
+  - **Exercises**: [FR-nnn, BR-nnn]
+  - **Acceptance**: Given [state], When [action], Then [outcome]
+  - **Independent test**: [how this story is verified on its own]
+- **FR-[nnn]**: WHEN [trigger] THE SYSTEM SHALL [response]   <!-- EARS — pick the fitting pattern -->
+- **BR-[nnn]**: [a new invariant that must always hold] — or `None`
+- **CN-[nnn]**: [new constraint / NFR — retention, immutability, audit, performance-as-a-limit; cite lifted source] — or `None`
+- **DC-[nnn]**: [new data-classification category or exposure rule] — or `None`
+- **IC-[nnn]**: [new integration contract / interop obligation] — or `None`
+- **UX-[nnn]**: [new project-wide experience standard — accessibility, interaction states, content, journey integrity, responsiveness-as-a-limit; cite lifted source] — or `None`
+- **Entity**: [new entity / value object + what it represents] — or `None`
+
+## MODIFIED
+
+- **FR-[nnn]**: was [old] → now [new]   <!-- keep EARS form -->
+- **BR-[nnn]**: was [old] → now [new]
+- **CN-[nnn]** / **DC-[nnn]** / **IC-[nnn]** / **UX-[nnn]**: was [old] → now [new]
+- **US-[n]**: [what changes and why]
+
+## REMOVED
+
+- [FR / BR / CN / DC / IC / UX / US / entity removed and why] — or `None`
+
+## Impact
+
+- **Affected FR / BR / CN / DC / IC / UX / US / SC**: [ids]
+- **Regression risk**: [existing behaviour that must still hold — e.g. CreateOrder must still pass]
+- **On merge**: the new US-[n] is tagged `Added: (this CR)` in the master; finalize-delta
+  merges this delta into spec.md + design.md and appends the Change History row, and
+  close-delta (after analyze-slice) archives the change and bumps the minor version.