@ncoderz/awa 1.8.5 → 1.9.0

package/templates/awa/_partials/awa.core.md

@@ -22,15 +22,18 @@ YOU are also an expert software architect and developer, and write specification
   │       ├── API.schema.yaml
   │       ├── TASK.schema.yaml
   │       ├── PLAN.schema.yaml
-  │       ├── README.schema.yaml
-  │       └── ALIGN_REPORT.schema.yaml
+  │       ├── DEPRECATED.schema.yaml
+  │       ├── ALIGN_REPORT.schema.yaml
+  │       └── README.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
+  │   ├── API-{CODE}-{api-name}.tsp
+  │   └── deprecated/
+  │       └── DEPRECATED.md
   ├── tasks/
   │   └── TASK-{CODE}-{feature-name}-{nnn}.md
   ├── plans/
@@ -52,6 +55,7 @@ YOU are also an expert software architect and developer, and write specification
 - 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).
+- deprecated/DEPRECATED.md: Tombstone file for retired spec ids.
 - rules/*.md: Rules specific to the project (e.g. Coding standards, best practices to follow).
 </file_descriptions>
 

package/templates/awa/_partials/awa.spec-deprecate.md

@@ -0,0 +1,86 @@
+# Deprecate Requirements
+
+## 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" />
+ <read path=".awa/.agent/schemas/DEPRECATED.schema.yaml" 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="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="true" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="deprecated" path=".awa/specs/deprecated/DEPRECATED.md" required="if exists" />
+
+## Action
+
+Deprecate (retire) the specified requirements, acceptance criteria, properties, or components by adding their IDs to the tombstone file and cleaning up references.
+
+## Process
+
+1. IDENTIFY IDS TO DEPRECATE
+   - From the user input, determine which IDs to retire (requirement IDs, AC IDs, property IDs, component names)
+   - Verify each ID exists in the current specs using `awa trace <ID>`
+   - List the IDs grouped by feature code for confirmation
+
+2. UPDATE TOMBSTONE FILE
+   - Open or create `.awa/specs/deprecated/DEPRECATED.md`
+   - For each feature code affected, find or create the `# {CODE}` heading
+   - Add the deprecated IDs under the appropriate heading, comma-separated per line
+   - Group logically: requirement IDs, then AC IDs, then property IDs, then component names
+   - Ensure the file conforms to `DEPRECATED.schema.yaml` — only bare IDs, no prose
+
+3. REMOVE DEPRECATED CODE (ONLY IF REQUESTED)
+   - If the user specifically requests it, remove deprecated code, test and markers
+
+4. REMOVE FROM ACTIVE SPECS
+   - Remove deprecated requirements and their ACs from REQ files
+   - Remove deprecated components and properties from DESIGN files
+   - Remove IMPLEMENTS/VALIDATES references to deprecated IDs from remaining design components
+   - If an entire spec file becomes empty after removal, delete it
+
+5. CLEAN UP TASKS / PLANs
+   - In any TASK or PLAN files, mark tasks referencing deprecated IDs as complete or remove them
+   - Update task IMPLEMENTS/TESTS references that point to deprecated IDs
+
+6. VALIDATE
+   - Run `awa check` to verify:
+     - No orphaned markers reference deprecated IDs
+     - No active spec reuses a deprecated ID (`deprecated-id-conflict`)
+     - Traceability chain is intact for remaining requirements
+   - Run `awa check --deprecated` to surface any stale references as warnings
+   - Fix any errors found
+
+7. REPORT
+   - Summarize which IDs were deprecated
+   - Note any code that lost markers but was left in place
+   - Note any remaining `deprecated-ref` warnings from `--deprecated` output
+
+## Outputs
+
+<file path=".awa/specs/deprecated/DEPRECATED.md" />
+- Updated REQ, DESIGN, and TASK spec files (deprecated content removed)
+- Updated source and test files (stale markers removed)
+
+## Rules
+
+You SHALL verify each ID exists before deprecating it.
+You SHALL add every deprecated ID to the tombstone file — no ID may be lost silently.
+You SHALL NOT reuse a deprecated ID for new requirements.
+You SHALL NOT delete code that implements deprecated requirements — only remove traceability markers.
+You SHALL run `awa check` after deprecation to verify the traceability chain is clean.
+You SHALL confirm the list of IDs with the user before making changes if the scope is large (more than 5 IDs).
+You SHOULD deprecate an entire requirement and all its ACs together, not individual ACs in isolation, unless the user explicitly requests partial deprecation.
+You MAY use todos and tools as needed.

package/templates/awa/_partials/awa.usage.md

@@ -27,15 +27,18 @@ All spec artifacts live in `.awa/`:
     │       ├── API.schema.yaml
     │       ├── TASK.schema.yaml
     │       ├── PLAN.schema.yaml
-    │       ├── README.schema.yaml
-    │       └── ALIGN_REPORT.schema.yaml
+    │       ├── DEPRECATED.schema.yaml
+    │       ├── ALIGN_REPORT.schema.yaml
+    │       └── README.schema.yaml
     ├── specs/
     │   ├── ARCHITECTURE.md                # System overview
     │   ├── FEAT-{CODE}-*.md               # Feature context and motivation
     │   ├── EXAMPLE-{CODE}-*-{nnn}.md     # Usage examples per feature
     │   ├── REQ-{CODE}-*.md                # Requirements (EARS format)
     │   ├── DESIGN-{CODE}-*.md             # Design and components
-    │   └── API-{CODE}-*.tsp               # TypeSpec API definitions
+    │   ├── API-{CODE}-*.tsp               # TypeSpec API definitions
+    │   └── deprecated/
+    │       └── DEPRECATED.md              # Tombstone file for retired spec IDs
     ├── tasks/
     │   └── TASK-{CODE}-*-{nnn}.md         # Implementation steps
     ├── plans/
@@ -58,10 +61,13 @@ All spec artifacts live in `.awa/`:
 | Tasks | `TASK-{CODE}-*-{nnn}.md` | Step-by-step implementation work items |
 | Code & Tests | Source files | Implementation with traceability markers |
 | Documentation | `README.md`, `docs/` | User-facing docs |
+| *(lateral)* | `EXAMPLE-{CODE}-*-{nnn}.md` | Concrete usage examples for a feature |
+| *(lateral)* | `API-{CODE}-*.tsp` | TypeSpec API definitions |
+| *(lateral)* | `PLAN-{nnn}-*.md` | Ad-hoc plans for vibe coding |
+| *(lateral)* | `ALIGN-{x}-WITH-{y}-{nnn}.md` | Alignment reports comparing artifacts |
+| *(lateral)* | `deprecated/DEPRECATED.md` | Tombstone for retired spec IDs |
 
-Lateral artifacts (produced at any stage): EXAMPLE, PLAN, ALIGN reports.
-
-The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans).
+The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans). Lateral artifacts can be produced at any stage.
 
 ## Traceability Chain
 
@@ -160,10 +166,11 @@ Check traceability chain integrity and spec schema conformance. Exit code 0 = cl
 | `--allow-warnings` | Allow warnings without failing |
 | `--spec-only` | Run only spec-level checks; skip code-to-spec traceability |
 | `--no-fix` | Skip auto-regeneration of Requirements Traceability sections and Feature Codes table |
+| `--deprecated` | Surface warnings for code markers and cross-references targeting deprecated IDs |
 
 Before running checks, `awa check` auto-regenerates Requirements Traceability sections in DESIGN and TASK files, and the Feature Codes table in ARCHITECTURE.md. Use `--no-fix` to skip this.
 
-Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `spec-only`, `id-pattern`, `cross-ref-patterns`.
+Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `id-pattern`, `cross-ref-patterns`, `extra-spec-globs`, `extra-spec-ignore`.
 
 ### awa trace
 
@@ -313,6 +320,8 @@ Create `.awa.toml` in the project root. CLI arguments always override config val
     markers = ["@awa-impl", "@awa-test", "@awa-component"]
     spec-ignore = []
     code-ignore = ["node_modules/**", "dist/**", "vendor/**", "target/**", "build/**", "out/**", ".awa/**"]
+    extra-spec-globs = [".awa/**/*"]        # additional spec globs for schema validation
+    extra-spec-ignore = [".awa/.agent/**"]  # patterns to exclude from extra spec scanning
     ignore-markers = []
     id-pattern = "..."                      # regex for valid traceability IDs
     cross-ref-patterns = ["IMPLEMENTS:", "VALIDATES:"]

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

@@ -0,0 +1,88 @@
+---
+name: awa-deprecate
+description: Deprecate requirements by retiring IDs to the tombstone file. Use this when asked to deprecate, retire, or remove requirements, acceptance criteria, or components.
+---
+
+# Deprecate Requirements
+
+## 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" />
+ <read path=".awa/.agent/schemas/DEPRECATED.schema.yaml" 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="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="true" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="deprecated" path=".awa/specs/deprecated/DEPRECATED.md" required="if exists" />
+
+## Action
+
+Deprecate (retire) the specified requirements, acceptance criteria, properties, or components by adding their IDs to the tombstone file and cleaning up references.
+
+## Process
+
+1. IDENTIFY IDS TO DEPRECATE
+   - From the user input, determine which IDs to retire (requirement IDs, AC IDs, property IDs, component names)
+   - Verify each ID exists in the current specs using `awa trace <ID>`
+   - List the IDs grouped by feature code for confirmation
+
+2. UPDATE TOMBSTONE FILE
+   - Open or create `.awa/specs/deprecated/DEPRECATED.md`
+   - For each feature code affected, find or create the `# {CODE}` heading
+   - Add the deprecated IDs under the appropriate heading, comma-separated per line
+   - Group logically: requirement IDs, then AC IDs, then property IDs, then component names
+   - Ensure the file conforms to `DEPRECATED.schema.yaml` — only bare IDs, no prose
+
+3. REMOVE FROM ACTIVE SPECS
+   - Remove deprecated requirements and their ACs from REQ files
+   - Remove deprecated components and properties from DESIGN files
+   - Remove IMPLEMENTS/VALIDATES references to deprecated IDs from remaining design components
+   - If an entire spec file becomes empty after removal, delete it
+
+4. CLEAN UP TASKS / PLANs
+   - In any TASK or PLAN files, mark tasks referencing deprecated IDs as complete or remove them
+   - Update task IMPLEMENTS/TESTS references that point to deprecated IDs
+
+5. VALIDATE
+   - Run `awa check` to verify:
+     - No orphaned markers reference deprecated IDs
+     - No active spec reuses a deprecated ID (`deprecated-id-conflict`)
+     - Traceability chain is intact for remaining requirements
+   - Run `awa check --deprecated` to surface any stale references as warnings
+   - Fix any errors found
+
+6. REPORT
+   - Summarize which IDs were deprecated
+   - Note any code that lost markers but was left in place
+   - Note any remaining `deprecated-ref` warnings from `--deprecated` output
+
+## Outputs
+
+<file path=".awa/specs/deprecated/DEPRECATED.md" />
+- Updated REQ, DESIGN, and TASK spec files (deprecated content removed)
+- Updated source and test files (stale markers removed)
+
+## Rules
+
+You SHALL verify each ID exists before deprecating it.
+You SHALL add every deprecated ID to the tombstone file — no ID may be lost silently.
+You SHALL NOT reuse a deprecated ID for new requirements.
+You SHALL NOT delete code that implements deprecated requirements — only remove traceability markers.
+You SHALL run `awa check` after deprecation to verify the traceability chain is clean.
+You SHALL confirm the list of IDs with the user before making changes if the scope is large (more than 5 IDs).
+You SHOULD deprecate an entire requirement and all its ACs together, not individual ACs in isolation, unless the user explicitly requests partial deprecation.
+You MAY use todos and tools as needed.

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

@@ -1,5 +1,5 @@
 ---
-name: spec-merge
+name: awa-spec-merge
 description: Merge two feature codes into one. Use this when asked to combine, merge, or consolidate feature codes.
 ---
 

package/templates/awa/_tests/{copilot/.github/skills/spec-tidy → claude/.claude/skills/awa-spec-tidy}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: spec-tidy
+name: awa-spec-tidy
 description: Tidy and reorganise the specifications logically. Use this when asked to tidy or reorganise the specifications.
 ---
 

package/templates/awa/_tests/claude/.claude/skills/awa-usage/SKILL.md

@@ -32,6 +32,7 @@ All spec artifacts live in `.awa/`:
     │       ├── API.schema.yaml
     │       ├── TASK.schema.yaml
     │       ├── PLAN.schema.yaml
+    │       ├── DEPRECATED.schema.yaml
     │       ├── README.schema.yaml
     │       └── ALIGN_REPORT.schema.yaml
     ├── specs/
@@ -40,7 +41,9 @@ All spec artifacts live in `.awa/`:
     │   ├── EXAMPLE-{CODE}-*-{nnn}.md     # Usage examples per feature
     │   ├── REQ-{CODE}-*.md                # Requirements (EARS format)
     │   ├── DESIGN-{CODE}-*.md             # Design and components
-    │   └── API-{CODE}-*.tsp               # TypeSpec API definitions
+    │   ├── API-{CODE}-*.tsp               # TypeSpec API definitions
+    │   └── deprecated/
+    │       └── DEPRECATED.md              # Tombstone file for retired spec IDs
     ├── tasks/
     │   └── TASK-{CODE}-*-{nnn}.md         # Implementation steps
     ├── plans/
@@ -63,10 +66,13 @@ All spec artifacts live in `.awa/`:
 | Tasks | `TASK-{CODE}-*-{nnn}.md` | Step-by-step implementation work items |
 | Code & Tests | Source files | Implementation with traceability markers |
 | Documentation | `README.md`, `docs/` | User-facing docs |
+| *(lateral)* | `EXAMPLE-{CODE}-*-{nnn}.md` | Concrete usage examples for a feature |
+| *(lateral)* | `API-{CODE}-*.tsp` | TypeSpec API definitions |
+| *(lateral)* | `PLAN-{nnn}-*.md` | Ad-hoc plans for vibe coding |
+| *(lateral)* | `ALIGN-{x}-WITH-{y}-{nnn}.md` | Alignment reports comparing artifacts |
+| *(lateral)* | `deprecated/DEPRECATED.md` | Tombstone for retired spec IDs — prevents reuse, `--deprecated` flags stale refs |
 
-Lateral artifacts (produced at any stage): EXAMPLE, PLAN, ALIGN reports.
-
-The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans).
+The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans). Lateral artifacts can be produced at any stage.
 
 ## Traceability Chain
 
@@ -165,10 +171,11 @@ Check traceability chain integrity and spec schema conformance. Exit code 0 = cl
 | `--allow-warnings` | Allow warnings without failing |
 | `--spec-only` | Run only spec-level checks; skip code-to-spec traceability |
 | `--no-fix` | Skip auto-regeneration of Requirements Traceability sections and Feature Codes table |
+| `--deprecated` | Surface warnings for code markers and cross-references targeting deprecated IDs |
 
 Before running checks, `awa check` auto-regenerates Requirements Traceability sections in DESIGN and TASK files, and the Feature Codes table in ARCHITECTURE.md. Use `--no-fix` to skip this.
 
-Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `spec-only`, `id-pattern`, `cross-ref-patterns`.
+Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `id-pattern`, `cross-ref-patterns`, `extra-spec-globs`, `extra-spec-ignore`.
 
 ### awa trace
 
@@ -315,6 +322,8 @@ Create `.awa.toml` in the project root. CLI arguments always override config val
     markers = ["@awa-impl", "@awa-test", "@awa-component"]
     spec-ignore = []
     code-ignore = ["node_modules/**", "dist/**", "vendor/**", "target/**", "build/**", "out/**", ".awa/**"]
+    extra-spec-globs = [".awa/**/*"]        # additional spec globs for schema validation
+    extra-spec-ignore = [".awa/.agent/**"]  # patterns to exclude from extra spec scanning
     ignore-markers = []
     id-pattern = "..."                      # regex for valid traceability IDs
     cross-ref-patterns = ["IMPLEMENTS:", "VALIDATES:"]

package/templates/awa/_tests/copilot/.github/prompts/awa.spec-deprecate.prompt.md

@@ -0,0 +1,88 @@
+---
+description: Deprecate requirements by retiring IDs to the tombstone file
+argument-hint: "<IDs or description of what to deprecate>"
+---
+
+# Deprecate Requirements
+
+## 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" />
+ <read path=".awa/.agent/schemas/DEPRECATED.schema.yaml" 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="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="true" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="deprecated" path=".awa/specs/deprecated/DEPRECATED.md" required="if exists" />
+
+## Action
+
+Deprecate (retire) the specified requirements, acceptance criteria, properties, or components by adding their IDs to the tombstone file and cleaning up references.
+
+## Process
+
+1. IDENTIFY IDS TO DEPRECATE
+   - From the user input, determine which IDs to retire (requirement IDs, AC IDs, property IDs, component names)
+   - Verify each ID exists in the current specs using `awa trace <ID>`
+   - List the IDs grouped by feature code for confirmation
+
+2. UPDATE TOMBSTONE FILE
+   - Open or create `.awa/specs/deprecated/DEPRECATED.md`
+   - For each feature code affected, find or create the `# {CODE}` heading
+   - Add the deprecated IDs under the appropriate heading, comma-separated per line
+   - Group logically: requirement IDs, then AC IDs, then property IDs, then component names
+   - Ensure the file conforms to `DEPRECATED.schema.yaml` — only bare IDs, no prose
+
+3. REMOVE FROM ACTIVE SPECS
+   - Remove deprecated requirements and their ACs from REQ files
+   - Remove deprecated components and properties from DESIGN files
+   - Remove IMPLEMENTS/VALIDATES references to deprecated IDs from remaining design components
+   - If an entire spec file becomes empty after removal, delete it
+
+4. CLEAN UP TASKS / PLANs
+   - In any TASK or PLAN files, mark tasks referencing deprecated IDs as complete or remove them
+   - Update task IMPLEMENTS/TESTS references that point to deprecated IDs
+
+5. VALIDATE
+   - Run `awa check` to verify:
+     - No orphaned markers reference deprecated IDs
+     - No active spec reuses a deprecated ID (`deprecated-id-conflict`)
+     - Traceability chain is intact for remaining requirements
+   - Run `awa check --deprecated` to surface any stale references as warnings
+   - Fix any errors found
+
+6. REPORT
+   - Summarize which IDs were deprecated
+   - Note any code that lost markers but was left in place
+   - Note any remaining `deprecated-ref` warnings from `--deprecated` output
+
+## Outputs
+
+<file path=".awa/specs/deprecated/DEPRECATED.md" />
+- Updated REQ, DESIGN, and TASK spec files (deprecated content removed)
+- Updated source and test files (stale markers removed)
+
+## Rules
+
+You SHALL verify each ID exists before deprecating it.
+You SHALL add every deprecated ID to the tombstone file — no ID may be lost silently.
+You SHALL NOT reuse a deprecated ID for new requirements.
+You SHALL NOT delete code that implements deprecated requirements — only remove traceability markers.
+You SHALL run `awa check` after deprecation to verify the traceability chain is clean.
+You SHALL confirm the list of IDs with the user before making changes if the scope is large (more than 5 IDs).
+You SHOULD deprecate an entire requirement and all its ACs together, not individual ACs in isolation, unless the user explicitly requests partial deprecation.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/copilot/.github/skills/awa-spec-deprecate/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: awa-deprecate
+description: Deprecate requirements by retiring IDs to the tombstone file. Use this when asked to deprecate, retire, or remove requirements, acceptance criteria, or components.
+---
+
+# Deprecate Requirements
+
+## 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" />
+ <read path=".awa/.agent/schemas/DEPRECATED.schema.yaml" 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="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="true" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="deprecated" path=".awa/specs/deprecated/DEPRECATED.md" required="if exists" />
+
+## Action
+
+Deprecate (retire) the specified requirements, acceptance criteria, properties, or components by adding their IDs to the tombstone file and cleaning up references.
+
+## Process
+
+1. IDENTIFY IDS TO DEPRECATE
+   - From the user input, determine which IDs to retire (requirement IDs, AC IDs, property IDs, component names)
+   - Verify each ID exists in the current specs using `awa trace <ID>`
+   - List the IDs grouped by feature code for confirmation
+
+2. UPDATE TOMBSTONE FILE
+   - Open or create `.awa/specs/deprecated/DEPRECATED.md`
+   - For each feature code affected, find or create the `# {CODE}` heading
+   - Add the deprecated IDs under the appropriate heading, comma-separated per line
+   - Group logically: requirement IDs, then AC IDs, then property IDs, then component names
+   - Ensure the file conforms to `DEPRECATED.schema.yaml` — only bare IDs, no prose
+
+3. REMOVE FROM ACTIVE SPECS
+   - Remove deprecated requirements and their ACs from REQ files
+   - Remove deprecated components and properties from DESIGN files
+   - Remove IMPLEMENTS/VALIDATES references to deprecated IDs from remaining design components
+   - If an entire spec file becomes empty after removal, delete it
+
+4. CLEAN UP TASKS / PLANs
+   - In any TASK or PLAN files, mark tasks referencing deprecated IDs as complete or remove them
+   - Update task IMPLEMENTS/TESTS references that point to deprecated IDs
+
+5. VALIDATE
+   - Run `awa check` to verify:
+     - No orphaned markers reference deprecated IDs
+     - No active spec reuses a deprecated ID (`deprecated-id-conflict`)
+     - Traceability chain is intact for remaining requirements
+   - Run `awa check --deprecated` to surface any stale references as warnings
+   - Fix any errors found
+
+6. REPORT
+   - Summarize which IDs were deprecated
+   - Note any code that lost markers but was left in place
+   - Note any remaining `deprecated-ref` warnings from `--deprecated` output
+
+## Outputs
+
+<file path=".awa/specs/deprecated/DEPRECATED.md" />
+- Updated REQ, DESIGN, and TASK spec files (deprecated content removed)
+- Updated source and test files (stale markers removed)
+
+## Rules
+
+You SHALL verify each ID exists before deprecating it.
+You SHALL add every deprecated ID to the tombstone file — no ID may be lost silently.
+You SHALL NOT reuse a deprecated ID for new requirements.
+You SHALL NOT delete code that implements deprecated requirements — only remove traceability markers.
+You SHALL run `awa check` after deprecation to verify the traceability chain is clean.
+You SHALL confirm the list of IDs with the user before making changes if the scope is large (more than 5 IDs).
+You SHOULD deprecate an entire requirement and all its ACs together, not individual ACs in isolation, unless the user explicitly requests partial deprecation.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/copilot/.github/skills/{spec-merge → awa-spec-merge}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: spec-merge
+name: awa-spec-merge
 description: Merge two feature codes into one. Use this when asked to combine, merge, or consolidate feature codes.
 ---
 

package/templates/awa/_tests/{claude/.claude/skills/spec-tidy → copilot/.github/skills/awa-spec-tidy}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: spec-tidy
+name: awa-spec-tidy
 description: Tidy and reorganise the specifications logically. Use this when asked to tidy or reorganise the specifications.
 ---
 

package/templates/awa/_tests/copilot/.github/skills/awa-usage/SKILL.md

@@ -32,6 +32,7 @@ All spec artifacts live in `.awa/`:
     │       ├── API.schema.yaml
     │       ├── TASK.schema.yaml
     │       ├── PLAN.schema.yaml
+    │       ├── DEPRECATED.schema.yaml
     │       ├── README.schema.yaml
     │       └── ALIGN_REPORT.schema.yaml
     ├── specs/
@@ -40,7 +41,9 @@ All spec artifacts live in `.awa/`:
     │   ├── EXAMPLE-{CODE}-*-{nnn}.md     # Usage examples per feature
     │   ├── REQ-{CODE}-*.md                # Requirements (EARS format)
     │   ├── DESIGN-{CODE}-*.md             # Design and components
-    │   └── API-{CODE}-*.tsp               # TypeSpec API definitions
+    │   ├── API-{CODE}-*.tsp               # TypeSpec API definitions
+    │   └── deprecated/
+    │       └── DEPRECATED.md              # Tombstone file for retired spec IDs
     ├── tasks/
     │   └── TASK-{CODE}-*-{nnn}.md         # Implementation steps
     ├── plans/
@@ -63,10 +66,13 @@ All spec artifacts live in `.awa/`:
 | Tasks | `TASK-{CODE}-*-{nnn}.md` | Step-by-step implementation work items |
 | Code & Tests | Source files | Implementation with traceability markers |
 | Documentation | `README.md`, `docs/` | User-facing docs |
+| *(lateral)* | `EXAMPLE-{CODE}-*-{nnn}.md` | Concrete usage examples for a feature |
+| *(lateral)* | `API-{CODE}-*.tsp` | TypeSpec API definitions |
+| *(lateral)* | `PLAN-{nnn}-*.md` | Ad-hoc plans for vibe coding |
+| *(lateral)* | `ALIGN-{x}-WITH-{y}-{nnn}.md` | Alignment reports comparing artifacts |
+| *(lateral)* | `deprecated/DEPRECATED.md` | Tombstone for retired spec IDs — prevents reuse, `--deprecated` flags stale refs |
 
-Lateral artifacts (produced at any stage): EXAMPLE, PLAN, ALIGN reports.
-
-The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans).
+The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans). Lateral artifacts can be produced at any stage.
 
 ## Traceability Chain
 
@@ -165,10 +171,11 @@ Check traceability chain integrity and spec schema conformance. Exit code 0 = cl
 | `--allow-warnings` | Allow warnings without failing |
 | `--spec-only` | Run only spec-level checks; skip code-to-spec traceability |
 | `--no-fix` | Skip auto-regeneration of Requirements Traceability sections and Feature Codes table |
+| `--deprecated` | Surface warnings for code markers and cross-references targeting deprecated IDs |
 
 Before running checks, `awa check` auto-regenerates Requirements Traceability sections in DESIGN and TASK files, and the Feature Codes table in ARCHITECTURE.md. Use `--no-fix` to skip this.
 
-Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `spec-only`, `id-pattern`, `cross-ref-patterns`.
+Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `id-pattern`, `cross-ref-patterns`, `extra-spec-globs`, `extra-spec-ignore`.
 
 ### awa trace
 
@@ -315,6 +322,8 @@ Create `.awa.toml` in the project root. CLI arguments always override config val
     markers = ["@awa-impl", "@awa-test", "@awa-component"]
     spec-ignore = []
     code-ignore = ["node_modules/**", "dist/**", "vendor/**", "target/**", "build/**", "out/**", ".awa/**"]
+    extra-spec-globs = [".awa/**/*"]        # additional spec globs for schema validation
+    extra-spec-ignore = [".awa/.agent/**"]  # patterns to exclude from extra spec scanning
     ignore-markers = []
     id-pattern = "..."                      # regex for valid traceability IDs
     cross-ref-patterns = ["IMPLEMENTS:", "VALIDATES:"]

package/templates/awa/.agent/skills/spec-merge/SKILL.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('agy')) { %>
-<%~ include('_partials/_skill.spec-merge.md', it) %>
-<% } %>

package/templates/awa/.agent/skills/spec-tidy/SKILL.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('agy')) { %>
-<%~ include('_partials/_skill.spec-tidy.md', it) %>
-<% } %>

package/templates/awa/.agent/workflows/spec-merge.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('agy')) { %>
-<%~ include('_partials/_cmd.spec-merge.md', it) %>
-<% } %>

package/templates/awa/.agent/workflows/spec-tidy.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('agy')) { %>
-<%~ include('_partials/_cmd.spec-tidy.md', it) %>
-<% } %>

package/templates/awa/.agents/skills/spec-merge/SKILL.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('codex')) { %>
-<%~ include('_partials/_skill.spec-merge.md', it) %>
-<% } %>

package/templates/awa/.agents/skills/spec-tidy/SKILL.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('codex')) { %>
-<%~ include('_partials/_skill.spec-tidy.md', it) %>
-<% } %>

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

@@ -1,3 +0,0 @@
-<% if (it.features.includes('claude')) { %>
-<%~ include('_partials/_skill.spec-merge.md', it) %>
-<% } %>

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

@@ -1,3 +0,0 @@
-<% if (it.features.includes('claude')) { %>
-<%~ include('_partials/_skill.spec-tidy.md', it) %>
-<% } %>

package/templates/awa/.gemini/commands/spec-merge.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('gemini')) { %>
-<%~ include('_partials/_cmd.spec-merge.md', it) %>
-<% } %>

package/templates/awa/.gemini/commands/spec-tidy.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('gemini')) { %>
-<%~ include('_partials/_cmd.spec-tidy.md', it) %>
-<% } %>

package/templates/awa/.gemini/skills/spec-merge/SKILL.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('gemini')) { %>
-<%~ include('_partials/_skill.spec-merge.md', it) %>
-<% } %>