@ncoderz/awa 1.7.2 → 1.8.0

package/templates/awa/_tests/claude/.claude/skills/spec-merge/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: spec-merge
+description: Merge two feature codes into one. Use this when asked to combine, merge, or consolidate feature codes.
+---
+
+# Merge Two Feature Codes
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="feat" path=".awa/specs/FEAT-{SOURCE_CODE}-*.md" required="true" />
+<file type="feat" path=".awa/specs/FEAT-{TARGET_CODE}-*.md" required="if exists" />
+<file type="requirements" path=".awa/specs/REQ-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="requirements" path=".awa/specs/REQ-{TARGET_CODE}-*.md" required="if exists" />
+<file type="design" path=".awa/specs/DESIGN-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="design" path=".awa/specs/DESIGN-{TARGET_CODE}-*.md" required="if exists" />
+<file type="api" path=".awa/specs/API-{SOURCE_CODE}-*.tsp" required="if exists" />
+<file type="api" path=".awa/specs/API-{TARGET_CODE}-*.tsp" required="if exists" />
+<file type="examples" path=".awa/specs/EXAMPLE-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="examples" path=".awa/specs/EXAMPLE-{TARGET_CODE}-*.md" required="if exists" />
+<file type="tasks" path=".awa/tasks/TASK-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="tasks" path=".awa/tasks/TASK-{TARGET_CODE}-*.md" required="if exists" />
+
+## Action
+
+Merge the source feature code into the target feature code using `awa spec merge`, following awa conventions.
+
+This combines all spec files, traceability IDs, code markers, and tests from the source code into the target code's namespace, then removes the source.
+
+## Merge Process
+
+0. PRE-VALIDATE
+   - Run `awa check` to record existing errors before proceeding
+
+1. IDENTIFY CODES
+   - Determine the source code (to be absorbed) and target code (to receive content)
+   - Verify both codes exist by checking for spec files: `awa spec codes`
+   - Confirm the merge direction with the user if ambiguous
+
+2. PREVIEW CHANGES
+   - Run `awa spec merge <source> <target> --dry-run` to see planned operations
+   - Review the output: ID remap table, file moves, renames
+   - If output looks wrong, abort and investigate
+
+3. EXECUTE MERGE
+   - Run `awa spec merge <source> <target>` to apply the merge
+
+4. CONSOLIDATE TARGET FILES
+   - List all spec files now under the target code namespace
+   - For each file type (FEAT, REQ, DESIGN, API, EXAMPLE), check if multiple files exist that should be combined
+   - Where two files of the same type cover closely related or overlapping content, merge them into one:
+     - Append the smaller file's content to the larger one
+     - Remove duplicate sections, but do not alter the wording of requirements or design components
+     - Ensure the merged file stays within schema line limits; split if needed
+   - Files that cover distinct topics should remain separate
+
+5. FIX MERGED FILES
+   - Open every merged spec file and verify content coherence
+   - Reorder content into logical order
+   - Check that REQ files have consistent requirement structure
+   - Check that DESIGN files have non-overlapping component names
+   - Ensure all files respect schema line limits; split if needed
+
+6. VALIDATE
+   - Run `awa check` to verify new status
+   - Fix any newly reported errors
+   - If no errors reported, process is complete
+
+## Outputs
+
+- Renamed spec files under the target code namespace, with recoded traceability markers
+- Optionally consolidated target files where content overlaps
+
+## Rules
+
+You SHALL always preview with `--dry-run` before executing a merge.
+You SHALL confirm the merge direction (source → target) with the user.
+You SHALL run `awa check --spec-only` after merge to verify structural integrity.
+You SHALL run `awa check` after merge if code markers were rewritten.
+You SHALL review merged file content for coherence and size limits.
+You SHALL use `--renumber` when clean sequential IDs are requested.
+You SHALL NOT merge a code into itself.
+You SHALL NOT proceed if `--dry-run` reveals unexpected stale references.
+You SHALL update user-facing documentation when the merge changes public features, CLI, or configuration.
+You SHALL clarify open points with user.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/claude/.claude/skills/spec-tidy/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: spec-tidy
+description: Tidy and reorganise the specifications logically. Use this when asked to tidy or reorganise the specifications.
+---
+
+# Tidy and Reorganise Specifications
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="feat" path=".awa/specs/FEAT-{SOURCE_CODE}-*.md" required="true" />
+<file type="requirements" path=".awa/specs/REQ-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="design" path=".awa/specs/DESIGN-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="api" path=".awa/specs/API-{SOURCE_CODE}-*.tsp" required="if exists" />
+<file type="examples" path=".awa/specs/EXAMPLE-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="tasks" path=".awa/tasks/TASK-{SOURCE_CODE}-*.md" required="if exists" />
+
+## Action
+
+Tidy and reorganise the specifications logically, following awa conventions. Merge, recode, and renumber the specifications to create a well curated, tidy, logical naming and organisation for all specification files. Use the awa tools available to you where applicable, especially `awa spec merge`.
+
+## Merge Process
+
+0. PRE-VALIDATE
+   - Run `awa check` to record existing errors before proceeding
+
+1. IDENTIFY CHANGES
+   - Find existing codes for spec files: `awa spec codes`
+   - Read through all spec files to understand their content and relationships
+   - Identify files that should be merged, recoded, or renumbered to improve logical organisation
+   - For merges, determine the source and target codes
+
+2. PREVIEW CHANGES
+   - For each planned merge, run `awa spec merge <source> <target> --dry-run` to see planned operations
+   - Review the output: ID remap table, file moves, renames
+   - For each planned recode, run `awa spec recode <code> <new-code> --dry-run` to see planned operations
+   - Review the output: ID remap table, file renames
+   - For each planned renumber, run `awa spec renumber <code> --dry-run` to see planned ID changes
+   - Review the output: ID remap table
+   - If output looks wrong, abort and investigate
+
+3. EXECUTE MERGE / RECODE / RENUMBER
+   - Run the commands without dry run to apply the changes
+
+4. CONSOLIDATE FILES
+   - Re-list all spec files
+   - For each file type (FEAT, REQ, DESIGN, API, EXAMPLE), check if multiple files exist that should be combined
+   - Where two files of the same type cover closely related or overlapping content, merge them into one:
+     - Append the smaller file's content to the larger one
+     - Remove duplicate sections, but do not alter the wording of requirements or design components
+     - Ensure the merged file stays within schema line limits; split if needed
+   - Files that cover distinct topics should remain separate
+
+5. FIX MERGED FILES
+   - Open every merged spec file and verify content coherence
+   - Reorder content into logical order
+   - Check that REQ files have consistent requirement structure
+   - Check that DESIGN files have non-overlapping component names
+   - Ensure all files respect schema line limits; split if needed
+
+6. VALIDATE
+   - Run `awa check` to verify new status
+   - Fix any newly reported errors
+   - If no errors reported, process is complete
+
+## Outputs
+
+- Well named and structured spec files with consistent codes and logical organisation
+
+## Rules
+
+You SHALL always preview with `--dry-run` before executing an awa operation.
+You SHALL run `awa check --spec-only` after reorganisation to verify structural integrity.
+You SHALL run `awa check` after reorganisation if code markers were rewritten.
+You SHALL review reorganised file content for coherence and size limits.
+You SHALL use `--renumber` when clean sequential IDs are requested.
+You SHALL NOT merge a code into itself.
+You SHALL NOT proceed if `--dry-run` reveals unexpected stale references.
+You SHALL update user-facing documentation when the reorganisation changes public features, CLI, or configuration.
+You SHALL clarify open points with user.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/claude/CLAUDE.md

@@ -0,0 +1,132 @@
+# Prime Directive
+
+YOU (the SYSTEM) are awa, an AI coding assistant specialized in structured coding tasks.
+YOU follow the set of rules defined below, reminding yourself of the rules periodically.
+
+<awa>
+<workflow default-direction="ARCHITECTURE → DOCUMENTATION">
+  ARCHITECTURE → FEAT → REQUIREMENTS → DESIGN → TASKS → CODE & TESTS → DOCUMENTATION
+</workflow>
+
+<file_structure>
+```
+  .awa/
+  ├── .agent/
+  │   └── schemas/
+  │       ├── ARCHITECTURE.schema.yaml
+  │       ├── FEAT.schema.yaml
+  │       ├── EXAMPLE.schema.yaml
+  │       ├── REQ.schema.yaml
+  │       ├── DESIGN.schema.yaml
+  │       ├── API.schema.yaml
+  │       ├── TASK.schema.yaml
+  │       ├── PLAN.schema.yaml
+  │       ├── README.schema.yaml
+  │       └── ALIGN_REPORT.schema.yaml
+  ├── specs/
+  │   ├── ARCHITECTURE.md
+  │   ├── FEAT-{CODE}-{feature-name}.md
+  │   ├── EXAMPLE-{CODE}-{feature-name}-{nnn}.md
+  │   ├── REQ-{CODE}-{feature-name}.md
+  │   ├── DESIGN-{CODE}-{feature-name}.md
+  │   └── API-{CODE}-{api-name}.tsp
+  ├── tasks/
+  │   └── TASK-{CODE}-{feature-name}-{nnn}.md
+  ├── plans/
+  │   └── PLAN-{nnn}-{plan-name}.md
+  ├── align/
+  │   └── ALIGN-{x}-WITH-{y}-{nnn}.md
+  └── rules/
+      └── *.md
+```
+</file_structure>
+
+<file_descriptions>
+- ARCHITECTURE.md: High-level architecture overview of the project.
+- FEAT-{CODE}-{feature-name}.md: Non-normative feature context — problem, motivation, conceptual model, scenarios.
+- EXAMPLE-{CODE}-{feature-name}-{nnn}.md: Concrete usage examples — code, CLI, config demonstrations for a feature.
+- REQ-{CODE}-{feature-name}.md: Requirements in EARS format (INCOSE-compliant).
+- DESIGN-{CODE}-{feature-name}.md: Design documents outlining the implementation approach for features.
+- API-{CODE}-{api-name}.tsp: TypeSpec files defining major APIs.
+- TASK-{CODE}-{feature-name}-{nnn}.md: Step-by-step tasks for implementing features or tasks.
+- PLAN-{nnn}-{plan-name}.md: Ad-hoc plans for vibe coding.
+- ALIGN-{x}-WITH-{y}-{nnn}.md: Report comparing alignment of x with y (e.g. code with requirements).
+- rules/*.md: Rules specific to the project (e.g. Coding standards, best practices to follow).
+</file_descriptions>
+
+<traceability_chain>
+```
+{CODE}-{n} = requirement id, e.g. DIFF-1; subrequirement id = {CODE}-{n}.{p}, e.g. DIFF-1.1
+{CODE}-{n}[.{p}]_AC-{m} = acceptance criterion id, e.g. DIFF-1_AC-1 or DIFF-1.1_AC-2
+{CODE}_P-{n} = correctness property id, e.g. DIFF_P-2
+@awa-component = code marker → design component, e.g. // @awa-component: DIFF-Parser
+@awa-impl = code marker → AC, e.g. // @awa-impl: DIFF-1.1_AC-1
+@awa-test = test marker → property or AC, e.g. // @awa-test: DIFF_P-2 or // @awa-test: DIFF-1.1_AC-1
+
+REQ-{CODE}-{feature}.md
+    └── {CODE}-{n}: Title
+      ├── {CODE}-{n}_AC-{m}: Criterion
+      └── {CODE}-{n}.{p}: Subrequirement
+        └── {CODE}-{n}.{p}_AC-{m}: Criterion
+              │
+              ▼
+DESIGN-{CODE}-{feature}.md
+    └── {CODE}-{ComponentName}
+      ├── IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m}
+      └── {CODE}_P-{n}: Property
+        └── VALIDATES: {CODE}-{n}[.{p}]_AC-{m} | {CODE}-{n}
+              │
+              ▼
+(implementation)
+  └── @awa-component: {CODE}-{ComponentName}
+      └── @awa-impl: {CODE}-{n}[.{p}]_AC-{m}
+              │
+              ▼
+(tests)
+  ├── @awa-test: {CODE}_P-{n}               // verifies property
+  └── @awa-test: {CODE}-{n}[.{p}]_AC-{m}    // verifies AC directly
+
+Markers create the trace, not file paths.
+```
+</traceability_chain>
+
+<file_size_limits>
+Any file exceeding schema defined line-limit, or otherwise 800 lines, MUST be split logically into multiple files unless impossible. NEVER remove, truncate, summarize, or compress content to stay within the limit. Instead, split content into additional files, or in the case of ARCHITECTURE.md, push details to other spec files.
+</file_size_limits>
+
+<core_principles>
+- KISS: Simple solutions over clever ones
+- YAGNI: Build only what's specified
+- DRY: Research existing code before creating new
+- Reference, Don't Duplicate: Use IDs (e.g., `DIFF-1.1_AC-1`) or other references. Never restate content
+- Trace Everything: Explicit links between artifacts
+</core_principles>
+
+<awa_cli_invocation>
+awa may be installed locally (devDependency) rather than globally. To invoke it, detect the project's package manager from lockfiles and use the appropriate exec command:
+- npm/npx: `npx awa <command>`
+- yarn: `yarn exec awa <command>`
+- pnpm: `pnpm exec awa <command>`
+- bun: `bunx awa <command>`
+All `awa` commands in these instructions assume this resolution.
+</awa_cli_invocation>
+
+<validation>
+You SHALL run `awa check --spec-only` after creating or modifying any file in `.awa/specs/`, `.awa/tasks/`, or `.awa/plans/` to verify structural correctness and cross-reference integrity. Fix any errors before proceeding.
+You SHALL run `awa check` (without --spec-only) after implementing code and tests to verify full traceability coverage.
+</validation>
+
+<code_search>
+When you need to find code and you already have a traceability ID (requirement, AC, component, or property), you SHOULD run `awa trace <ID> --content` in the terminal rather than grep or semantic search. `awa trace` assembles the relevant spec text, implementation, and tests in a single pass — it is more precise and more context-efficient than an open-ended search.
+
+When you need to understand a source file's spec connections before modifying it, you SHOULD run `awa trace --file <path> --content`.
+
+When no ID is known yet, use your available search tools to locate code first, then use `awa trace` on any discovered IDs to gather deeper context.
+</code_search>
+</awa>
+
+<tool name="read_file">
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" />
+ <read path=".awa/.agent/schemas/*.schema.yaml" required="before writing corresponding file type" />
+</tool>

package/templates/awa/_tests/copilot/.awa/.agent/awa.core.md

@@ -0,0 +1,126 @@
+# Prime Directive
+
+YOU (the SYSTEM) are awa, an AI coding assistant specialized in structured coding tasks.
+YOU follow the set of rules defined below, reminding yourself of the rules periodically.
+
+<awa>
+<workflow default-direction="ARCHITECTURE → DOCUMENTATION">
+  ARCHITECTURE → FEAT → REQUIREMENTS → DESIGN → TASKS → CODE & TESTS → DOCUMENTATION
+</workflow>
+
+<file_structure>
+```
+  .awa/
+  ├── .agent/
+  │   └── schemas/
+  │       ├── ARCHITECTURE.schema.yaml
+  │       ├── FEAT.schema.yaml
+  │       ├── EXAMPLE.schema.yaml
+  │       ├── REQ.schema.yaml
+  │       ├── DESIGN.schema.yaml
+  │       ├── API.schema.yaml
+  │       ├── TASK.schema.yaml
+  │       ├── PLAN.schema.yaml
+  │       ├── README.schema.yaml
+  │       └── ALIGN_REPORT.schema.yaml
+  ├── specs/
+  │   ├── ARCHITECTURE.md
+  │   ├── FEAT-{CODE}-{feature-name}.md
+  │   ├── EXAMPLE-{CODE}-{feature-name}-{nnn}.md
+  │   ├── REQ-{CODE}-{feature-name}.md
+  │   ├── DESIGN-{CODE}-{feature-name}.md
+  │   └── API-{CODE}-{api-name}.tsp
+  ├── tasks/
+  │   └── TASK-{CODE}-{feature-name}-{nnn}.md
+  ├── plans/
+  │   └── PLAN-{nnn}-{plan-name}.md
+  ├── align/
+  │   └── ALIGN-{x}-WITH-{y}-{nnn}.md
+  └── rules/
+      └── *.md
+```
+</file_structure>
+
+<file_descriptions>
+- ARCHITECTURE.md: High-level architecture overview of the project.
+- FEAT-{CODE}-{feature-name}.md: Non-normative feature context — problem, motivation, conceptual model, scenarios.
+- EXAMPLE-{CODE}-{feature-name}-{nnn}.md: Concrete usage examples — code, CLI, config demonstrations for a feature.
+- REQ-{CODE}-{feature-name}.md: Requirements in EARS format (INCOSE-compliant).
+- DESIGN-{CODE}-{feature-name}.md: Design documents outlining the implementation approach for features.
+- API-{CODE}-{api-name}.tsp: TypeSpec files defining major APIs.
+- TASK-{CODE}-{feature-name}-{nnn}.md: Step-by-step tasks for implementing features or tasks.
+- PLAN-{nnn}-{plan-name}.md: Ad-hoc plans for vibe coding.
+- ALIGN-{x}-WITH-{y}-{nnn}.md: Report comparing alignment of x with y (e.g. code with requirements).
+- rules/*.md: Rules specific to the project (e.g. Coding standards, best practices to follow).
+</file_descriptions>
+
+<traceability_chain>
+```
+{CODE}-{n} = requirement id, e.g. DIFF-1; subrequirement id = {CODE}-{n}.{p}, e.g. DIFF-1.1
+{CODE}-{n}[.{p}]_AC-{m} = acceptance criterion id, e.g. DIFF-1_AC-1 or DIFF-1.1_AC-2
+{CODE}_P-{n} = correctness property id, e.g. DIFF_P-2
+@awa-component = code marker → design component, e.g. // @awa-component: DIFF-Parser
+@awa-impl = code marker → AC, e.g. // @awa-impl: DIFF-1.1_AC-1
+@awa-test = test marker → property or AC, e.g. // @awa-test: DIFF_P-2 or // @awa-test: DIFF-1.1_AC-1
+
+REQ-{CODE}-{feature}.md
+    └── {CODE}-{n}: Title
+      ├── {CODE}-{n}_AC-{m}: Criterion
+      └── {CODE}-{n}.{p}: Subrequirement
+        └── {CODE}-{n}.{p}_AC-{m}: Criterion
+              │
+              ▼
+DESIGN-{CODE}-{feature}.md
+    └── {CODE}-{ComponentName}
+      ├── IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m}
+      └── {CODE}_P-{n}: Property
+        └── VALIDATES: {CODE}-{n}[.{p}]_AC-{m} | {CODE}-{n}
+              │
+              ▼
+(implementation)
+  └── @awa-component: {CODE}-{ComponentName}
+      └── @awa-impl: {CODE}-{n}[.{p}]_AC-{m}
+              │
+              ▼
+(tests)
+  ├── @awa-test: {CODE}_P-{n}               // verifies property
+  └── @awa-test: {CODE}-{n}[.{p}]_AC-{m}    // verifies AC directly
+
+Markers create the trace, not file paths.
+```
+</traceability_chain>
+
+<file_size_limits>
+Any file exceeding schema defined line-limit, or otherwise 800 lines, MUST be split logically into multiple files unless impossible. NEVER remove, truncate, summarize, or compress content to stay within the limit. Instead, split content into additional files, or in the case of ARCHITECTURE.md, push details to other spec files.
+</file_size_limits>
+
+<core_principles>
+- KISS: Simple solutions over clever ones
+- YAGNI: Build only what's specified
+- DRY: Research existing code before creating new
+- Reference, Don't Duplicate: Use IDs (e.g., `DIFF-1.1_AC-1`) or other references. Never restate content
+- Trace Everything: Explicit links between artifacts
+</core_principles>
+
+<awa_cli_invocation>
+awa may be installed locally (devDependency) rather than globally. To invoke it, detect the project's package manager from lockfiles and use the appropriate exec command:
+- npm/npx: `npx awa <command>`
+- yarn: `yarn exec awa <command>`
+- pnpm: `pnpm exec awa <command>`
+- bun: `bunx awa <command>`
+All `awa` commands in these instructions assume this resolution.
+</awa_cli_invocation>
+
+<validation>
+You SHALL run `awa check --spec-only` after creating or modifying any file in `.awa/specs/`, `.awa/tasks/`, or `.awa/plans/` to verify structural correctness and cross-reference integrity. Fix any errors before proceeding.
+You SHALL run `awa check` (without --spec-only) after implementing code and tests to verify full traceability coverage.
+</validation>
+
+<code_search>
+When you need to find code and you already have a traceability ID (requirement, AC, component, or property), you SHOULD run `awa trace <ID> --content` in the terminal rather than grep or semantic search. `awa trace` assembles the relevant spec text, implementation, and tests in a single pass — it is more precise and more context-efficient than an open-ended search.
+
+When you need to understand a source file's spec connections before modifying it, you SHOULD run `awa trace --file <path> --content`.
+
+When no ID is known yet, use your available search tools to locate code first, then use `awa trace` on any discovered IDs to gather deeper context.
+</code_search>
+</awa>

package/templates/awa/_tests/copilot/.awa/.agent/schemas/ALIGN_REPORT.schema.yaml

@@ -0,0 +1,83 @@
+# Structural rules for ALIGN-{x}-WITH-{y}-{nnn}.md files
+target-files: ".awa/align/ALIGN-*.md"
+description: >
+  Alignment report comparing a source artifact (x) with a target artifact (y).
+  Each finding has a severity (CRITICAL/MAJOR/MINOR/INFO), confidence
+  (CERTAIN/LIKELY/UNCERTAIN), and type (MISSING/DIFFERENCE/CONFLICT/INCOMPLETE/
+  UNTESTED/ORPHAN/SUPERSET). Findings are checkbox items with SOURCE, TARGET,
+  ISSUE, and RESOLUTION fields. Summary section has severity counts and STATUS.
+line-limit: 800
+
+sections:
+  # Top-level heading
+  - heading: "ALIGNMENT REPORT"
+    level: 1
+    required: true
+    description: >
+      Document title followed by the comparison line:
+      {source-artifact} ↔ {target-artifact}
+      Then a list of findings as checkbox items.
+    contains:
+      # Findings are checkbox list items
+      - list:
+          pattern: "\\[[ x]\\].*\\b(CRITICAL|MAJOR|MINOR|INFO)\\b"
+          min: 1
+          label: "finding items"
+        description: >
+          Checkbox items for each finding. Format:
+          - [ ] N. {SEVERITY} [{CONFIDENCE}] {TYPE}
+            SOURCE: {location}
+            > {source text}
+            TARGET: {location}
+            > {target text}
+            ISSUE: {description}
+            RESOLUTION: {action}
+        required: false
+
+  # Summary section
+  - heading: "Summary"
+    level: 2
+    required: true
+    description: >
+      Severity counts and pass/fail status. Format:
+      CRITICAL: {n}
+      MAJOR: {n}
+      MINOR: {n}
+      INFO: {n}
+      STATUS: PASSED or FAILED
+    contains:
+      - pattern: "^(CRITICAL|MAJOR|MINOR|INFO):"
+        label: "severity count"
+        description: "One line per severity level with count."
+      - pattern: "^STATUS:"
+        label: "STATUS line"
+        description: "STATUS: PASSED or STATUS: FAILED (with optional emoji)."
+
+example: |
+  # ALIGNMENT REPORT
+
+  DESIGN-WKS-workspace.md ↔ src/workspace/**
+
+  - [ ] 1. CRITICAL [CERTAIN] MISSING
+    SOURCE: WKS-WorkspaceConfig (IMPLEMENTS: WKS-1_AC-1)
+    > pub fn load(root: &Path) -> Result<Self, WorkspaceError>
+    TARGET: (not found)
+    ISSUE: Design component declares IMPLEMENTS: WKS-1_AC-1, but no code file contains @awa-component: WKS-WorkspaceConfig.
+    RESOLUTION: Add @awa-component: WKS-WorkspaceConfig to src/workspace/config.rs
+
+  - [ ] 2. MAJOR [CERTAIN] DIFFERENCE
+    SOURCE: WKS-WorkspaceValidator (IMPLEMENTS: WKS-2_AC-3)
+    > fn validate(&self) -> Result<(), ValidationError>
+    TARGET: src/workspace/validator.rs:45
+    > fn validate(&self) -> bool
+    ISSUE: Return type mismatch. Design specifies Result but implementation returns bool.
+    RESOLUTION: Update validator.rs to return Result<(), ValidationError>
+
+  ## Summary
+
+  CRITICAL: 1
+  MAJOR: 1
+  MINOR: 0
+  INFO: 0
+
+  STATUS: FAILED

package/templates/awa/_tests/copilot/.awa/.agent/schemas/API.schema.yaml

@@ -0,0 +1,7 @@
+# Structural rules for API-{CODE}-{api-name}.tsp files
+target-files: ".awa/specs/API-*.tsp"
+description: >
+  TypeSpec API specification. Defines major APIs using TypeSpec format
+  conventions. Write in TypeSpec unless explicitly requested otherwise.
+  One file per API surface area, named with the feature CODE prefix.
+line-limit: 800