@ancleto/spec 0.6.7 → 0.6.10

package/skills/ancleto-upgrade/references/templates.md

@@ -1,9 +1,5 @@
 # Templates — aspec artifacts
 
-Exact templates for the four generated artifacts; fill each `{...}` placeholder.
-
----
-
 ## proposal.md
 
 ```markdown
@@ -11,37 +7,27 @@ Exact templates for the four generated artifacts; fill each `{...}` placeholder.
 
 ## Context
 
-{Installed version + migration reason (EOL, perf, compatibility, features); key changelog
-points if docs exist.}
+{Installed version, reason, key changelog points.}
 
 ## Analysis coverage
 
-- source files analyzed: {source_files_scanned}
-- test files analyzed: {test_files_scanned}
-- config files analyzed: {config_files_scanned}
-- files with matches: {files_with_matches}
-- files without matches: {files_without_matches}
+- analyzed: {source_files_scanned} source / {test_files_scanned} tests / {config_files_scanned} config
+- with/without matches: {files_with_matches}/{files_without_matches}
 
 ## Change scope
 
-### Affected dependencies — {N} packages in {M} package.json
+**Dependencies** — {N} in {M} package.json:
 
 | package.json | Package | Current version | Target version |
 | ------------ | ------- | --------------- | -------------- |
 
 {One row per DEPENDENCY_CHANGES[]}
 
-### Config files to modify — {N} files
-
-{Change per file; if none: "None."}
+**Config files** — {N}: {change per file; if none: "None."}
 
-### Source code with breaking changes — {N} files
+**Source** — {N}: {files + breaking change; if none: "None."}
 
-{Affected files + breaking change; if none: "None."}
-
-### Tests with breaking changes — {N} files
-
-{Affected test files; if none: "None."}
+**Tests** — {N}: {files; if none: "None."}
 
 ## Breaking-change assessment
 
@@ -77,28 +63,28 @@ Source: {DOCS_URL | "Web search: {query}" | "Internal knowledge base"}
 
 #### Scenario: dependencies installed
 
-- **WHEN** dependencies are installed for the affected package
+- **WHEN** dependencies are installed
 - **THEN** `{package_name}` resolves to `^{TARGET_VERSION}.0.0`
 
 ### Requirement: Configuration
 
 - REQ-C-{N}: The system SHALL {required change} in `{file}`
 
-{Per CONFIG_CHANGES[]; empty → "No configuration requirements."}
+{Per CONFIG_CHANGES[]; empty → "None."}
 
 ### Requirement: Source code
 
 - REQ-S-{N} [{break_id}]: The system SHALL {required code change}
   Evidence: `{file}:{line_number}` ({confidence})
 
-{Per BREAKING_CHANGES_IN_CODE[]; empty → "No source-code requirements."}
+{Per BREAKING_CHANGES_IN_CODE[]; empty → "None."}
 
 ### Requirement: Tests
 
 - REQ-T-{N} [{break_id}]: The system SHALL {required test change}
   Evidence: `{file}:{line_number}` ({confidence})
 
-{Per BREAKING_CHANGES_IN_TESTS[]; empty → "No test requirements."}
+{Per BREAKING_CHANGES_IN_TESTS[]; empty → "None."}
 
 ### Requirement: Verification
 
@@ -110,7 +96,7 @@ Source: {DOCS_URL | "Web search: {query}" | "Internal knowledge base"}
 
 ### Requirement: Analysis coverage
 
-- REQ-X-001: The analysis SHALL include every eligible source file (`.ts`, `.tsx`, `.js`), excluding `node_modules`, `dist` and generated artifacts
+- REQ-X-001: The analysis SHALL include every eligible source file (`.ts`, `.tsx`, `.js`) except `node_modules` and `dist`
 - REQ-X-002: The analysis SHALL include every eligible test file (`*.spec.*`, `*.test.*`)
 - REQ-X-003: The result SHALL report coverage metrics (`source_files_scanned`, `test_files_scanned`, `config_files_scanned`)
 ```
@@ -132,16 +118,13 @@ Source: {DOCS_URL | "Web search: {query}" | "Internal knowledge base"}
   ```bash
   npm install
   ```
-````
 
 ## Phase 2: Infrastructure and runtime
 
-{Only if IS_RUNTIME = true; one T-I task per file found}
+{IS_RUNTIME = true only; repeat per file}
 
 - [ ] **T-I-001** {Create | Update} `.nvmrc` with value `{TARGET_VERSION}`
-
-- [ ] **T-I-002** Update `nodeVersion` in `{CI_FILE}` from `{current}` to `{TARGET_VERSION}.x`
-
+- [ ] **T-I-002** Update `nodeVersion` in `{CI_FILE}`: `{current}` → `{TARGET_VERSION}.x`
 - [ ] **T-I-003** Update the base image in `{Dockerfile}`:
   ```dockerfile
   # Before
@@ -149,17 +132,14 @@ Source: {DOCS_URL | "Web search: {query}" | "Internal knowledge base"}
   # After
   FROM node:{TARGET_VERSION}-alpine
   ```
-  _(Match the existing variant: alpine, slim, bullseye, etc.)_
-
+  _(Match the existing variant: alpine, slim, bullseye.)_
 - [ ] **T-I-004** Update `Runtime` in `{appSettings.json}` to `NODEJS_{TARGET_VERSION}_X`
 
-{If IS_RUNTIME = false:}
-_(Not applicable to library migrations)_
+{IS_RUNTIME = false → _(Not applicable)_}
 
 ## Phase 3: Build and test configuration
 
-- [ ] **T-C-{N}** {Concrete change description}
-      File: `{file}`
+- [ ] **T-C-{N}** {Concrete change} — `{file}`
   ```
   // Before
   {current_value}
@@ -167,8 +147,7 @@ _(Not applicable to library migrations)_
   {target_value}
   ```
 
-{Per CONFIG_CHANGES[]; empty →}
-_(No configuration changes detected)_
+{Per CONFIG_CHANGES[]; empty → _(none detected)_}
 
 ## Phase 4: Breaking changes in source code
 
@@ -177,8 +156,7 @@ _(No configuration changes detected)_
       Affected files:
   - `{file}:{line_number}` ({confidence}) — `{snippet}`
 
-{Per BREAKING_CHANGES_IN_CODE[], one sub-bullet per file; empty →}
-_(No breaking changes detected in source code for this migration)_
+{Per BREAKING_CHANGES_IN_CODE[]; empty → _(none detected)_}
 
 ## Phase 5: Breaking changes in tests
 
@@ -187,46 +165,37 @@ _(No breaking changes detected in source code for this migration)_
       Affected files:
   - `{file}:{line_number}` ({confidence}) — `{snippet}`
 
-{Per BREAKING_CHANGES_IN_TESTS[], one sub-bullet per file; empty →}
-_(No breaking changes detected in tests for this migration)_
+{Per BREAKING_CHANGES_IN_TESTS[]; empty → _(none detected)_}
 
 ## Phase 6: Verification
 
-- [ ] **T-V-001** Verify TypeScript compilation:
+- [ ] **T-V-001** TypeScript compiles:
   ```bash
   npx tsc --noEmit
   # Nx monorepos: npx nx affected --target=typecheck
   ```
-
-- [ ] **T-V-002** Verify build:
+- [ ] **T-V-002** Build passes:
   ```bash
   npm run build
   # Nx monorepos: npx nx affected --target=build
   ```
-
-- [ ] **T-V-003** Run the linter:
+- [ ] **T-V-003** Lint passes:
   ```bash
   npm run lint
   # Nx monorepos: npx nx affected:lint
   ```
-
-- [ ] **T-V-004** Run the test suite:
+- [ ] **T-V-004** Tests pass:
   ```bash
   npm test
   # Nx monorepos: npx nx affected --target=test
   ```
-
-- [ ] **T-V-005** Run tests in CI mode:
-
+- [ ] **T-V-005** CI tests:
   ```bash
   npm run test:ci
   ```
+- [ ] **T-V-900** Coverage: confirm file counts; classify `UNSURE_MATCHES[]`.
 
-- [ ] **T-V-900** Validate scan coverage:
-  - confirm scanned file counts (source/tests/config)
-  - review `UNSURE_MATCHES[]` and classify each case
-
-{T-V-002..T-V-005 only when the matching script exists in SCRIPTS_AVAILABLE[]}
+{T-V-002..T-V-005 only when the script exists}
 
 ````
 
@@ -239,49 +208,41 @@ _(No breaking changes detected in tests for this migration)_
 
 ## Migration strategy
 
-{Phase order: dependencies first (surface compilation errors before touching code), then
-infrastructure, config, code. Main risk and mitigation.}
+{Phase order + main risk/mitigation.}
 
 ## Technical decisions
 
 ### Version range — `^{TARGET_VERSION}.0.0`
 
-Caret (`^`) instead of an exact pin receives patches and minors automatically while keeping
-major stability. `>=` is avoided so the next major is not accepted by accident.
+Caret keeps major stability while taking patches/minors; `>=` avoided to reject the next major.
 
 ### Configuration changes
 
-{Per CONFIG_CHANGE: technical reasoning. E.g. MIDDY7-001: "Jest needs transformIgnorePatterns
-because @middy v7 ships pure ESM and does not transpile node_modules; without it, tests fail
-with a SyntaxError on import."}
+{Per CONFIG_CHANGE: technical reasoning.}
 
 ### Breaking changes — impact analysis
 
-{Per breaking change: technical impact and why the fix is correct, not a workaround.}
-{If none: "No breaking changes were detected in this repository for this migration. Risk is low."}
+{Per breaking change: impact + why the fix is correct. If none: "None detected."}
 
 ### Ecosystem compatibility
 
-{Related dependencies that may be affected (e.g. Middy v7 third-party middlewares). If none:
-"No ecosystem dependencies with incompatibility risk were identified."}
+{Related dependencies at risk. If none: "None identified."}
 
 ### Analysis quality
 
-- Coverage: {source_files_scanned} source, {test_files_scanned} tests, {config_files_scanned} config
-- High-confidence matches: {N}
-- Medium-confidence matches: {N}
-- Low-confidence matches: {N}
-- Manual review strategy for low confidence: {criterion applied}
+- Coverage: {source_files_scanned}/{test_files_scanned}/{config_files_scanned}
+- Matches: {N} high / {N} medium / {N} low
+- Low-confidence review: {criterion}
 
 ## Change table
 
 | File | Field / Pattern | Before | After |
 |------|-----------------|--------|-------|
-{One row per change in DEPENDENCY_CHANGES[], CONFIG_CHANGES[], BREAKING_CHANGES_IN_CODE[], BREAKING_CHANGES_IN_TESTS[]}
+{Per change: DEPENDENCY_CHANGES[], CONFIG_CHANGES[], BREAKING_CHANGES_IN_CODE[], BREAKING_CHANGES_IN_TESTS[]}
 
 ## References
 
-- {DOCS_URL if available}
-- {Additional links found during the analysis}
-- Internal knowledge base consulted: {relevant break_ids from known-breaks.md}
+- {DOCS_URL}
+- {Additional links}
+- Knowledge base: {break_ids from known-breaks.md}
 ```

package/skills/ancleto-verify/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 # aspec Verify
 
-Verify an implementation against its change artifacts (proposal, design, tasks, delta specs) by reading files. No external binaries.
+Verify an implementation against its change artifacts. No external binaries.
 
 **Input**: Optionally a change name (e.g., `add-auth`); if omitted, infer from context. If ambiguous, list `aspec/changes/` dirs containing `tasks.md` and ask the user to select. Mark incomplete-task changes "(In Progress)".
 
@@ -20,29 +20,25 @@ Verify an implementation against its change artifacts (proposal, design, tasks,
 
 ### 1. Load change artifacts
 
-Read under `aspec/changes/<name>/`:
-
-- `tasks.md` — checklist (required)
-- `proposal.md`, `design.md` — intent/decisions (if present)
-- `specs/` — delta requirements (if present)
+Read under `aspec/changes/<name>/`: `tasks.md` (required), plus `proposal.md`, `design.md`, `specs/` when present.
 
 ### 2. Completeness
 
-**Tasks:** parse checkboxes (`- [ ]` incomplete vs `- [x]` complete); count. Each incomplete → CRITICAL: "Complete task: `<description>`" or "Mark as done if already implemented".
+**Tasks:** parse checkboxes (`- [ ]` incomplete vs `- [x]` complete) and count. Each incomplete → CRITICAL: "Complete task: `<description>`" or "Mark as done if already implemented".
 
-**Spec coverage:** for each requirement (`### Requirement:`) in `specs/`, search the codebase for related keywords. Unimplemented → CRITICAL: "Requirement not found: `<requirement name>`" + "Implement requirement: `<description>`".
+**Spec coverage:** for each `### Requirement:` in `specs/`, search the codebase for related keywords. Unimplemented → CRITICAL: "Requirement not found: `<requirement name>`" + "Implement requirement: `<description>`".
 
 ### 3. Correctness
 
 **Mapping:** for each requirement, find implementation evidence; note file paths and lines. Divergence → WARNING: "Implementation may diverge from spec: `<details>`" + "Review `<file>:<lines>` against requirement X".
 
-**Scenarios:** for each `#### Scenario:`, check code handles conditions and tests cover it. Uncovered → WARNING: "Scenario not covered: `<scenario name>`" + "Add test or implementation for scenario: `<description>`".
+**Scenarios:** for each `#### Scenario:`, check the code handles the conditions and tests cover it. Uncovered → WARNING: "Scenario not covered: `<scenario name>`" + "Add test or implementation for scenario: `<description>`".
 
 ### 4. Coherence
 
-**Design:** if `design.md` exists, extract key decisions ("Decision:", "Approach:", "Architecture:") and verify adherence. Contradiction → WARNING: "Design decision not followed: `<decision>`" + "Update implementation or revise design.md to match reality". If absent, note "No design.md to verify against".
+**Design:** if `design.md` exists, extract key decisions ("Decision:", "Approach:", "Architecture:") and verify adherence. Contradiction → WARNING: "Design decision not followed: `<decision>`" + "Update implementation or revise design.md". If absent, note "No design.md to verify against".
 
-**Patterns:** review new code against project patterns (file naming, dirs, style). Significant deviation → SUGGESTION: "Code pattern deviation: `<details>`" + "Consider following project pattern: `<example>`".
+**Patterns:** review new code against project patterns (naming, dirs, style). Significant deviation → SUGGESTION: "Code pattern deviation: `<details>`" + "Consider following project pattern: `<example>`".
 
 ### 5. Capture findings into persistent memory
 
@@ -57,7 +53,7 @@ For every WARNING/CRITICAL revealing an architectural decision, standing rule, o
   recordDecision({ memory_key: "<kebab-topic>", content: "<the decision>", justification: "<reason>" })
   ```
 
-Record only what saves future investigation; not the verification outcome. If nothing meets the bar, record nothing and say so.
+Record only what saves future investigation, not the outcome. If nothing meets the bar, record nothing and say so.
 
 ### 6. Verification Report
 
@@ -72,18 +68,18 @@ Record only what saves future investigation; not the verification outcome. If no
 | Coherence    | Followed/Issues  |
 ```
 
-**Issues by priority** — each needs a specific, actionable recommendation:
+**Issues by priority**, each with a specific recommendation:
 
 1. **CRITICAL** (block archive): incomplete tasks, missing requirement implementations.
 2. **WARNING** (should fix): spec/design divergences, missing scenario coverage.
 3. **SUGGESTION** (nice to fix): pattern inconsistencies, minor improvements.
 
-**Assessment:** CRITICAL → "X critical issue(s) found. Fix before archiving."; only warnings → "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."; clean → "All checks passed. Ready for archive." Plus which memories were recorded in step 5 (or "No findings recorded").
+**Assessment:** CRITICAL → "X critical issue(s) found. Fix before archiving."; warnings only → "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."; clean → "All checks passed. Ready for archive." Note memories recorded in step 5 (or "No findings recorded").
 
 ## Heuristics
 
 - **Completeness**: objective checklist items only.
-- **Correctness**: keyword search, path analysis, reasonable inference — no perfect certainty required.
+- **Correctness**: keyword search, path analysis, inference — no certainty required.
 - **Coherence**: glaring inconsistencies only; don't nitpick style.
 - **False positives**: when uncertain, prefer SUGGESTION > WARNING > CRITICAL.
 - **Actionability**: every issue carries a specific recommendation with file/line refs.

package/skills/triage-clarifier/SKILL.md

@@ -7,73 +7,66 @@ description: Clarification-needed triage helper. Use when the request sits betwe
 
 ## Goal
 
-Reduce ambiguity during triage without replacing the orchestrator or starting a spec workflow.
+Reduce triage ambiguity; don't replace the orchestrator or start a spec workflow.
 
 ## Use only when
 
-- the request is not clearly `direct-implementation`, `direct-test-only`, or `spec-required`
-- it is unclear whether the change affects visible behavior, acceptance criteria, or product code
-- a single high-value clarification can materially improve classification confidence
+- the request isn't clearly `direct-implementation`, `direct-test-only`, or `spec-required`
+- unclear whether it affects visible behavior, acceptance criteria, or product code
+- one high-value clarification could materially improve confidence
 
 ## Do not use when
 
-- the request already fits one category clearly
-- the request is already clearly large enough for `spec-required`
-- the user explicitly asked to open the structured/spec path
+- the request already fits one category
+- already clearly large enough for `spec-required`
+- the user explicitly asked for the structured/spec path
 
 ## Inputs to preserve
 
 - the user's original wording
-- any repo-specific context already gathered by the orchestrator
-- any existing constraints, references, or acceptance criteria already present in the request
+- repo context already gathered by the orchestrator
+- existing constraints, references, or acceptance criteria in the request
 
 ## Repository-context boundary
 
 Triage classifies the request; it does not reconstruct the repository.
 
-If repository context is needed to classify safely, do not sweep source files, broaden a
-search, or inspect the implementation yourself. Ask the orchestrator to delegate one focused
-question to `@technical-discovery`. That subagent reads the repository's technical-discovery
-documents and returns the relevant, cited context for triage.
+If repository context is needed to classify safely, don't sweep source files or inspect the implementation. Ask the orchestrator to delegate one focused question to `@technical-discovery`, which reads the repository's technical-discovery documents and returns cited context.
 
-Never replace unavailable technical-discovery documents with a manual repository scan. Use the
-context already provided, ask the one permitted clarification question when it resolves the
-dominant ambiguity, or favor `spec-required` when material uncertainty remains.
+Never replace unavailable technical-discovery documents with a manual repository scan. Use provided context, ask the one permitted clarification question when it resolves the dominant ambiguity, or favor `spec-required` when material uncertainty remains.
 
 ## Internal evaluation
 
-Before asking anything, evaluate these questions silently:
+Evaluate silently before asking:
 
-1. Is the request strictly about tests, or is product code likely to change?
-2. Is the expected behavior already clear, or would implementation require assumptions?
-3. Could the change alter visible behavior, business rules, contracts, shared types, architecture, or integrations?
-4. Is the request small and local, or does it risk expanding once implementation starts?
-5. If the team guessed wrong and under-classified it, would that create rework or architecture risk?
-6. Is the change low-risk, or does its small size hide a behavior change or high-stakes logic (auth, payments, data integrity, security, shared contracts)? If small but high-risk, prefer `spec-required`.
+1. Strictly tests, or product code likely to change?
+2. Expected behavior clear, or implementation needs assumptions?
+3. Could it alter visible behavior, business rules, contracts, shared types, architecture, or integrations?
+4. Small and local, or at risk of expanding once implementation starts?
+5. If under-classified, would that create rework or architecture risk?
+6. Low-risk, or does small size hide a behavior change or high-stakes logic (auth, payments, data integrity, security, shared contracts)? If small but high-risk, prefer `spec-required`.
 
 ## Classification rules
 
-Classify without asking a question whenever possible:
+Classify without asking whenever possible:
 
-- choose `direct-test-only` when the request is clearly limited to tests for existing behavior
-- choose `direct-implementation` when the change is small, local, and the expected result is already clear
-- choose `spec-required` when the request affects visible behavior, business rules, shared contracts, architecture, or scope is already meaningfully broad
+- choose `direct-test-only` when the request is limited to tests for existing behavior
+- choose `direct-implementation` when the change is small, local, and its expected result is clear
+- choose `spec-required` when the request affects visible behavior, business rules, shared contracts, architecture, or is already broad
 
 ## Single-question policy
 
-Ask at most one question.
-
-That question must:
+Ask at most one question. It must:
 
 - target the highest-value ambiguity only
 - be short and concrete
-- help separate exactly one boundary, such as:
+- separate exactly one boundary, such as:
   - test-only vs product change
   - local bugfix vs behavior change
   - small direct change vs structured/spec change
 
 Do not ask multi-part questions.
-Do not ask for implementation details unless they are required to classify safely.
+Do not ask for implementation details unless required to classify safely.
 Do not start an interview.
 
 ## Fallback policy
@@ -84,18 +77,18 @@ When in doubt, prefer the safer classification over an under-scoped direct path.
 
 ## Expected outcome
 
-After applying this skill, the orchestrator should do exactly one of these:
+After applying this skill, the orchestrator should do exactly one of:
 
 1. classify directly as `direct-test-only`
 2. classify directly as `direct-implementation`
 3. classify directly as `spec-required`
 4. ask one concise clarification question
 
-If option 4 happened and the answer still does not remove the main ambiguity, classify as `spec-required`.
+If option 4 happened and the answer still leaves the main ambiguity, classify as `spec-required`.
 
 ## What not to do
 
 - do not create specs, design, tasks, or proposals
 - do not trigger cleto or any workflow handoff
 - do not ask more than one clarification question
-- do not replace the orchestrator's final responsibility for classification
+- do not replace the orchestrator's final responsibility for classification