aped-method 1.8.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aped-method",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Scaffold the APED pipeline (Analyze, PRD, Epics, Dev, Review) into any Claude Code project",
   "bin": {

package/src/templates/references.js

@@ -50,6 +50,26 @@ export function references(c) {
       path: `${a}/aped-ux/references/ux-patterns.md`,
       content: UX_PATTERNS,
     },
+    {
+      path: `${a}/aped-s/references/status-format.md`,
+      content: STATUS_FORMAT,
+    },
+    {
+      path: `${a}/aped-c/references/scope-change-guide.md`,
+      content: SCOPE_CHANGE_GUIDE,
+    },
+    {
+      path: `${a}/aped-ctx/references/analysis-checklist.md`,
+      content: ANALYSIS_CHECKLIST,
+    },
+    {
+      path: `${a}/aped-qa/references/test-patterns.md`,
+      content: TEST_PATTERNS,
+    },
+    {
+      path: `${a}/aped-d/references/ticket-git-workflow.md`,
+      content: TICKET_GIT_WORKFLOW,
+    },
   ];
 }
 
@@ -799,3 +819,488 @@ Rules ranked by impact. Apply in order — never skip a higher-priority rule for
 - [ ] Reduced motion and dynamic text size supported
 - [ ] ARIA roles/states announced correctly
 `;
+
+const STATUS_FORMAT = `# Sprint Status Dashboard Format
+
+## Pipeline Progress Bar
+
+Display format:
+\`\`\`
+Pipeline: A[✓] → P[✓] → UX[✓] → E[✓] → D[▶] → R[ ]
+\`\`\`
+
+Symbols:
+- \`✓\` = phase done
+- \`▶\` = phase in-progress
+- \` \` = phase not started
+- \`—\` = phase skipped
+
+## Epic Progress Bar
+
+\`\`\`
+Epic 1: {{title}}  [████████░░] 80% (4/5 stories)
+\`\`\`
+
+- Bar: 10 chars wide, \`█\` for done, \`░\` for remaining
+- Show fraction and percentage
+
+## Story Status Icons
+
+| Status | Icon | Meaning |
+|--------|------|---------|
+| done | ✓ | Story completed and reviewed |
+| review | ⟳ | Waiting for adversarial review |
+| in-progress | ▶ | Currently being implemented |
+| ready-for-dev | ○ | Ready to start |
+| backlog | · | Not yet planned |
+| blocked | ✗ | Blocked by issue |
+
+## Blocker Categories
+
+- **[AI-Review]** items — review findings not yet addressed
+- **HALT** — dev stopped due to missing config/dependency/ambiguity
+- **Stuck** — in-progress for multiple sessions without progress
+- **Dependency** — blocked by another story
+
+## Next Action Logic
+
+| Current State | Suggestion |
+|---------------|------------|
+| Stories ready-for-dev | "Run /aped-d to implement next story" |
+| Stories in review | "Run /aped-r to review completed story" |
+| All stories done | "Pipeline complete! Run /aped-qa for E2E tests" |
+| Blockers found | Describe each blocker and resolution path |
+| No state file | "Run /aped-a to start the pipeline" |
+`;
+
+const SCOPE_CHANGE_GUIDE = `# Scope Change Management Guide
+
+## Impact Assessment Matrix
+
+| Change Type | PRD | UX | Epics | Stories | Code | Severity |
+|-------------|-----|-----|-------|---------|------|----------|
+| New feature added | Add FRs | Add screens | New stories | Create | None | Minor |
+| Feature removed | Remove FRs | Remove screens | Archive stories | Archive | May delete | Minor |
+| FR modified | Update FR | May update | Update story ACs | Update | May refactor | Medium |
+| Architecture change | Update NFRs | May rebuild | Update all Dev Notes | Reset | May rewrite | Major |
+| Priority reorder | No change | No change | Reorder | Reset status | None | Minor |
+| Complete pivot | Restart | Restart | Restart | Restart | Archive | Critical |
+
+## Change Process
+
+### Step 1: Document the Change
+- What changed and why
+- Who requested it (user, stakeholder, technical discovery)
+- Date of change
+
+### Step 2: Impact Analysis
+- List all affected artifacts (PRD sections, stories, code files)
+- Classify severity (minor/medium/major/critical)
+- Estimate effort to apply change
+
+### Step 3: User Confirmation
+- Present impact summary to user
+- Get explicit "proceed" before making changes
+- For major/critical: warn about in-progress work loss
+
+### Step 4: Execute Change
+- Archive affected artifacts to \`{output}/archive/{date}/\`
+- Apply changes top-down (PRD → UX → Epics → Stories)
+- Re-validate at each level (scripts)
+- Update state.yaml
+
+### Step 5: Verify Consistency
+- FR coverage still 100%
+- No orphan stories
+- No broken dependencies
+- State reflects new reality
+
+## Scope Creep Detection
+
+Warning signs:
+- Total FRs grew >20% from original PRD
+- Epic count increased
+- Stories consistently exceed single-session size
+- "Just one more thing" pattern repeating
+
+Response:
+- Flag to user with metrics
+- Suggest moving additions to Growth phase
+- Enforce MVP discipline
+`;
+
+const ANALYSIS_CHECKLIST = `# Brownfield Project Analysis Checklist
+
+## Phase 1: Structure Discovery
+
+- [ ] Identify primary language(s) from config files
+- [ ] Map directory structure (max 3 levels)
+- [ ] Find entry points (main, index, app, server)
+- [ ] Count: files, LOC, languages
+- [ ] Identify package manager (npm, yarn, pnpm, cargo, pip, go mod)
+- [ ] Check for monorepo structure (workspaces, packages/)
+
+## Phase 2: Architecture Mapping
+
+- [ ] Identify pattern (MVC, hexagonal, microservices, monolith, serverless)
+- [ ] Map data flow: entry → processing → storage → response
+- [ ] List databases and data stores
+- [ ] List external API integrations
+- [ ] List message queues/event systems
+- [ ] Identify caching layer
+- [ ] Map authentication/authorization flow
+
+## Phase 3: Convention Extraction
+
+- [ ] File naming convention (camelCase, kebab-case, PascalCase)
+- [ ] Function/method naming convention
+- [ ] Code organization (feature-based, layer-based, domain-based)
+- [ ] Error handling pattern (try/catch, Result type, error codes)
+- [ ] Logging approach (structured, unstructured, library used)
+- [ ] Config management (env vars, .env files, config files, vault)
+- [ ] Linting/formatting (ESLint, Prettier, Biome, rustfmt)
+
+## Phase 4: Dependency Audit
+
+- [ ] List production dependencies with versions
+- [ ] Flag outdated packages (major versions behind)
+- [ ] Check for known security advisories
+- [ ] Identify lock file type
+- [ ] Note any vendored/bundled dependencies
+- [ ] Check for deprecated packages
+
+## Phase 5: Testing
+
+- [ ] Identify test framework(s)
+- [ ] Estimate test coverage (file count, coverage reports)
+- [ ] Check for CI/CD pipeline config
+- [ ] Identify test types present (unit, integration, E2E)
+- [ ] Check for test fixtures/factories/mocks
+
+## Output Format
+
+\`\`\`markdown
+# Project Context: {name}
+
+## Tech Stack
+- Language: {lang} {version}
+- Framework: {framework} {version}
+- Database: {db}
+- Test Framework: {test_fw}
+
+## Architecture
+- Pattern: {pattern}
+- Entry: {entry_point}
+- Modules: {key_modules}
+
+## Conventions
+- Files: {naming}
+- Code style: {linter}
+- Error handling: {pattern}
+
+## Dependencies ({count} total)
+| Package | Version | Purpose | Status |
+|---------|---------|---------|--------|
+
+## Integration Points
+| Service | Purpose | Protocol |
+|---------|---------|----------|
+
+## Notes
+- {important_context_for_dev}
+\`\`\`
+`;
+
+const TEST_PATTERNS = `# E2E & Integration Test Patterns
+
+## Framework Selection
+
+| Project Type | E2E Framework | Integration Framework |
+|-------------|---------------|----------------------|
+| Node.js + React | Playwright or Cypress | Supertest + Vitest |
+| Node.js + API only | - | Supertest + Jest/Vitest |
+| Next.js | Playwright | Next.js test utils |
+| Python + Django/Flask | Playwright | pytest + httpx |
+| Python + FastAPI | Playwright | pytest + httpx |
+| Go | - | go test + httptest |
+| Rust | - | reqwest + tokio::test |
+
+## E2E Test Structure
+
+\`\`\`
+tests/e2e/
+  {journey-name}.test.{ext}     # One file per user journey
+  fixtures/                      # Test data
+  helpers/                       # Page objects, utilities
+\`\`\`
+
+### User Journey Test Template
+
+\`\`\`
+describe("{Journey Name}", () => {
+  test("happy path: {description}", async () => {
+    // Given: {precondition from AC}
+    // When: {action from AC}
+    // Then: {outcome from AC}
+  });
+
+  test("error: {error scenario}", async () => {
+    // Given: {invalid state}
+    // When: {action}
+    // Then: {error handling}
+  });
+
+  test("edge: {edge case}", async () => {
+    // Given: {boundary condition}
+    // When: {action}
+    // Then: {expected behavior}
+  });
+});
+\`\`\`
+
+## Integration Test Structure
+
+\`\`\`
+tests/integration/
+  {endpoint-or-service}.test.{ext}
+  fixtures/
+  helpers/
+\`\`\`
+
+### API Test Template
+
+\`\`\`
+describe("{Endpoint/Service}", () => {
+  test("POST /api/resource - creates resource", async () => {
+    // Arrange: valid payload
+    // Act: POST request
+    // Assert: 201, response body, DB state
+  });
+
+  test("POST /api/resource - 400 on invalid input", async () => {
+    // Arrange: invalid payload
+    // Act: POST request
+    // Assert: 400, error message
+  });
+
+  test("GET /api/resource/:id - 404 on missing", async () => {
+    // Arrange: non-existent ID
+    // Act: GET request
+    // Assert: 404
+  });
+
+  test("auth: rejects unauthenticated requests", async () => {
+    // Arrange: no auth header
+    // Act: request
+    // Assert: 401
+  });
+});
+\`\`\`
+
+## Test Coverage Goals
+
+| Category | Target | How to verify |
+|----------|--------|---------------|
+| AC coverage | 100% of ACs have tests | Map each AC → test |
+| Happy paths | Every user journey | 1 E2E test per journey |
+| Error paths | All error states | 1 test per error scenario |
+| Auth boundaries | All protected routes | Unauthorized + forbidden |
+| Edge cases | Empty, null, max values | Boundary value analysis |
+
+## Anti-Patterns
+
+- **Flaky tests**: Don't depend on timing. Use waitFor, retries, explicit waits.
+- **Shared state**: Each test must be independent. Reset DB/state before each.
+- **Hardcoded selectors**: Use data-testid or accessible roles, not CSS classes.
+- **Testing implementation**: Test behavior, not internal structure.
+- **No assertions**: Every test must assert something. \`expect(true).toBe(true)\` is not a test.
+`;
+
+const TICKET_GIT_WORKFLOW = `# Ticket System & Git Provider Integration
+
+Read \`ticket_system\` and \`git_provider\` from config.yaml to adapt all instructions below.
+
+---
+
+## Ticket System Sync Rules
+
+### If ticket_system = "none"
+Skip all ticket references. Use plain commit messages without ticket IDs.
+
+### If ticket_system = "linear"
+
+**BEFORE starting a story:**
+1. Find the corresponding Linear issue
+2. Move issue status to **In Progress**
+3. Use the **Linear-suggested git branch name** (from Linear UI: "Copy git branch name")
+4. Add a comment on the issue: what you're about to implement
+
+**DURING development:**
+- Reference the Linear issue ID in EVERY commit message
+- Use **Linear magic words** for auto-linking:
+  - \`Part of TEAM-XX\` — links without closing (use in intermediate commits)
+  - \`Fixes TEAM-XX\` — links and auto-closes issue on merge
+- Commit format: \`type(TEAM-XX): description\\n\\nPart of TEAM-XX\`
+
+**AFTER completing:**
+1. Create PR with issue ID: \`gh pr create --title "feat(TEAM-XX): Story X.Y - Description" --body "Fixes TEAM-XX"\`
+2. Move issue to **In Review**
+3. After merge: move to **Done**
+4. Update state.yaml to match
+
+### If ticket_system = "jira"
+
+**BEFORE:** Find JIRA issue (PROJ-XX), move to In Progress, use branch: \`feature/PROJ-XX-description\`
+
+**DURING:**
+- Reference JIRA issue ID in every commit: \`type(PROJ-XX): description\`
+- JIRA smart commits: \`PROJ-XX #in-progress\`, \`PROJ-XX #done\`
+
+**AFTER:**
+- PR title: \`feat(PROJ-XX): Story X.Y - Description\`
+- JIRA auto-links PRs via issue ID in branch name or commit
+
+### If ticket_system = "github-issues"
+
+**BEFORE:** Find GitHub issue #XX, assign yourself
+
+**DURING:**
+- Reference in commits: \`type(#XX): description\`
+- Use \`Closes #XX\` or \`Fixes #XX\` in final commit/PR body
+
+**AFTER:**
+- \`gh pr create --title "feat: Story X.Y" --body "Closes #XX"\`
+- Issue auto-closes when PR merges
+
+### If ticket_system = "gitlab-issues"
+
+**BEFORE:** Find GitLab issue #XX, assign yourself
+
+**DURING:**
+- Reference: \`type(#XX): description\`
+- Use \`Closes #XX\` in commit/MR body
+
+**AFTER:**
+- \`glab mr create --title "feat: Story X.Y" --description "Closes #XX"\`
+- Issue auto-closes when MR merges
+
+---
+
+## Git Provider Workflow
+
+### If git_provider = "github"
+
+**Branch strategy:**
+\`\`\`
+main (production)
+  └── develop (integration, if configured)
+        └── feature/{ticket-id}-description
+\`\`\`
+
+**Commands:**
+\`\`\`bash
+# Start story
+git checkout main  # or develop if exists
+git pull
+git checkout -b feature/{ticket-id}-description
+
+# During dev
+git add <specific-files>  # NEVER git add . or git add -A
+git commit -m "type({ticket-id}): description"
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+gh pr create --base main --title "type({ticket-id}): Story X.Y - Title" --body "Fixes {ticket-id}"
+
+# After merge
+git checkout main && git pull
+git branch -d feature/{ticket-id}-description
+\`\`\`
+
+### If git_provider = "gitlab"
+
+**Commands:**
+\`\`\`bash
+# Start
+git checkout main && git pull
+git checkout -b feature/{ticket-id}-description
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+glab mr create --base main --title "type({ticket-id}): Story X.Y" --description "Closes {ticket-id}"
+
+# After merge
+git checkout main && git pull
+git branch -d feature/{ticket-id}-description
+\`\`\`
+
+### If git_provider = "bitbucket"
+
+**Commands:**
+\`\`\`bash
+# Start
+git checkout main && git pull
+git checkout -b feature/{ticket-id}-description
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+# Create PR via Bitbucket web UI or API
+\`\`\`
+
+---
+
+## Commit Message Format
+
+\`\`\`
+type({ticket-id}): short description
+
+[Optional body]
+
+{Magic word} {ticket-id}
+\`\`\`
+
+| Prefix | Usage |
+|--------|-------|
+| feat | New feature / story implementation |
+| fix | Bug fix |
+| refactor | Code restructuring (no behavior change) |
+| test | Adding or updating tests |
+| docs | Documentation changes |
+| chore | Build, config, tooling changes |
+
+---
+
+## State Sync
+
+Local state.yaml and ticket system MUST agree:
+
+| state.yaml | Linear | Jira | GitHub/GitLab Issues |
+|------------|--------|------|---------------------|
+| backlog | Backlog | Backlog | No label |
+| ready-for-dev | Todo | To Do | "ready" label |
+| in-progress | In Progress | In Progress | "in progress" label |
+| review | In Review | In Review | PR linked |
+| done | Done | Done | Closed |
+
+**If they diverge, the ticket system is the authority.** Update state.yaml to match.
+
+---
+
+## Epic/Milestone Tracking
+
+- When first story of an epic moves to In Progress → update epic/milestone status
+- When ALL stories in an epic are Done → mark milestone complete
+- Keep milestone descriptions updated if scope changes
+
+---
+
+## Critical Rules
+
+1. NEVER commit directly to main
+2. ALWAYS create feature branch before starting
+3. ALWAYS include ticket ID in every commit message
+4. ALWAYS update ticket status: In Progress → In Review → Done
+5. ALWAYS stage specific files — never \`git add .\` or \`git add -A\`
+6. ALWAYS use ticket system's suggested branch name when available
+7. NEVER commit secrets (.env, API keys, settings.local.json)
+`;

package/src/templates/scripts.js

@@ -338,6 +338,105 @@ if [[ \${#IN_STORY_NOT_GIT[@]} -gt 0 ]]; then
   exit 1
 fi
 
+exit 0
+`,
+    },
+    {
+      path: `${a}/aped-ux/scripts/validate-ux.sh`,
+      executable: true,
+      content: `#!/usr/bin/env bash
+# Validate UX design spec completeness
+# Usage: validate-ux.sh <ux-dir>
+# Exit 0 if valid, exit 1 with missing items listed
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 <ux-directory>"
+  exit 1
+fi
+
+UX_DIR="$1"
+
+if [[ ! -d "$UX_DIR" ]]; then
+  echo "ERROR: Directory not found: $UX_DIR"
+  exit 1
+fi
+
+ISSUES=()
+
+# Check required output files
+REQUIRED_FILES=(
+  "design-spec.md"
+  "screen-inventory.md"
+  "components.md"
+  "flows.md"
+)
+
+for file in "\${REQUIRED_FILES[@]}"; do
+  if [[ ! -f "$UX_DIR/$file" ]]; then
+    ISSUES+=("MISSING FILE: $UX_DIR/$file")
+  fi
+done
+
+# Check design-spec.md has required sections
+if [[ -f "$UX_DIR/design-spec.md" ]]; then
+  SPEC_SECTIONS=(
+    "## Tech Stack"
+    "## Architecture"
+    "## Conventions"
+    "## Dependencies"
+  )
+
+  # Reuse pattern: check for sections about design tokens and UI library
+  if ! grep -q "color\\|Color\\|palette\\|token" "$UX_DIR/design-spec.md" 2>/dev/null; then
+    ISSUES+=("MISSING CONTENT: design-spec.md has no color/token definitions")
+  fi
+
+  if ! grep -q "typography\\|Typography\\|font\\|Font" "$UX_DIR/design-spec.md" 2>/dev/null; then
+    ISSUES+=("MISSING CONTENT: design-spec.md has no typography definitions")
+  fi
+fi
+
+# Check screen-inventory.md has content
+if [[ -f "$UX_DIR/screen-inventory.md" ]]; then
+  SCREEN_COUNT=$(grep -cE '^\\|.*\\|.*\\|' "$UX_DIR/screen-inventory.md" 2>/dev/null || echo 0)
+  if [[ "$SCREEN_COUNT" -lt 3 ]]; then
+    ISSUES+=("LOW SCREEN COUNT: Found $SCREEN_COUNT screens (expected at least 3)")
+  fi
+fi
+
+# Check components.md has component entries
+if [[ -f "$UX_DIR/components.md" ]]; then
+  COMP_COUNT=$(grep -cE '^#{2,3} ' "$UX_DIR/components.md" 2>/dev/null || echo 0)
+  if [[ "$COMP_COUNT" -lt 3 ]]; then
+    ISSUES+=("LOW COMPONENT COUNT: Found $COMP_COUNT components (expected at least 3)")
+  fi
+fi
+
+# Check preview app exists
+PREVIEW_DIR="\${UX_DIR}-preview"
+if [[ -d "$PREVIEW_DIR" ]]; then
+  if [[ ! -f "$PREVIEW_DIR/package.json" ]]; then
+    ISSUES+=("MISSING: Preview app has no package.json")
+  fi
+  if [[ ! -d "$PREVIEW_DIR/src" ]]; then
+    ISSUES+=("MISSING: Preview app has no src/ directory")
+  fi
+else
+  ISSUES+=("WARNING: No preview app at $PREVIEW_DIR (optional but recommended)")
+fi
+
+# Report
+if [[ \${#ISSUES[@]} -gt 0 ]]; then
+  echo "UX VALIDATION FAILED — Issues found:"
+  for issue in "\${ISSUES[@]}"; do
+    echo "  - $issue"
+  done
+  exit 1
+fi
+
+echo "UX VALIDATION PASSED — All required files and content present"
 exit 0
 `,
     },

package/src/templates/skills.js

@@ -335,13 +335,18 @@ Story files: \`${o}/stories/{story-key}.md\`
 
 ## Ticket System Integration
 
-Read \`ticket_system\` from config. If not \`none\`:
+Read \`ticket_system\` from config. Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full guide.
+
+If \`ticket_system\` is not \`none\`:
 - Add ticket reference in each story header: \`**Ticket:** {{ticket_id}}\`
-- If \`jira\`: format as \`PROJ-###\` placeholder
-- If \`linear\`: format as \`TEAM-###\` placeholder
-- If \`github-issues\`: format as \`#issue_number\` placeholder
-- If \`gitlab-issues\`: format as \`#issue_number\` placeholder
+- Add suggested branch name: \`**Branch:** feature/{{ticket_id}}-{{story-slug}}\`
+- Format ticket ID per provider:
+  - \`linear\`: \`TEAM-###\` (e.g., \`KON-10\`)
+  - \`jira\`: \`PROJ-###\` (e.g., \`PROJ-42\`)
+  - \`github-issues\`: \`#issue_number\` (e.g., \`#10\`)
+  - \`gitlab-issues\`: \`#issue_number\` (e.g., \`#10\`)
 - Note: actual ticket creation is manual — these are reference placeholders
+- In Dev Notes, add: "Commit prefix: \`feat({{ticket_id}})\`"
 
 ## FR Coverage Map
 
@@ -469,11 +474,32 @@ Mark \`[x]\` ONLY when: tests exist, pass 100%, implementation matches, ACs sati
 
 **STOP and ask user if:** new dependency, 3 consecutive failures, missing config, ambiguity.
 
-## Git Commit Convention
+## Git & Ticket Workflow
+
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full integration guide.
+
+Read \`ticket_system\` and \`git_provider\` from \`${a}/config.yaml\`.
+
+### Before Implementation
+If \`ticket_system\` is not \`none\`:
+1. Find the corresponding ticket/issue for this story
+2. Move ticket status to **In Progress**
+3. Create feature branch using ticket system's suggested name
+4. Add a comment on the ticket: implementation plan
+
+If \`ticket_system\` is \`none\`:
+1. Create branch: \`feature/{story-key}\`
+
+### During Implementation
+- Include ticket ID in EVERY commit: \`type({ticket-id}): description\`
+- Use magic words for auto-linking (see reference doc)
+- NEVER use \`git add .\` — stage specific files only
 
-Read \`git_provider\` and \`ticket_system\` from config:
-- Commit message format: \`type(scope): description\`
-- If ticket system configured, append ticket ref: \`type(scope): description [TICKET-ID]\`
+### After Implementation
+1. Push branch and create PR/MR (adapt to \`git_provider\`):
+   - \`github\`: \`gh pr create --title "feat({ticket-id}): Story X.Y" --body "Fixes {ticket-id}"\`
+   - \`gitlab\`: \`glab mr create --title "feat({ticket-id}): Story X.Y" --description "Closes {ticket-id}"\`
+2. Move ticket to **In Review**
 
 ## Completion
 
@@ -572,6 +598,20 @@ Severity: CRITICAL > HIGH > MEDIUM > LOW. Format: \`[Severity] Description [file
 - MEDIUM/LOW only: fix automatically, story — \`done\`
 - HIGH+: fix or add \`[AI-Review]\` items, story — \`in-progress\`
 
+## Ticket & Git Update
+
+Read \`ticket_system\` and \`git_provider\` from \`${a}/config.yaml\`.
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for details.
+
+If story → \`done\`:
+1. If PR exists: approve/merge (adapt to \`git_provider\`)
+2. If \`ticket_system\` is not \`none\`: move ticket to **Done**
+3. Cleanup: delete feature branch after merge
+
+If story → \`in-progress\` (review found HIGH+ issues):
+1. Add [AI-Review] items as comments on the PR
+2. Ticket stays in **In Review**
+
 ## State Update
 
 Update \`${o}/state.yaml\`. If more stories remain: invoke Skill tool with \`skill: "aped-d"\`. If all stories done: report pipeline completion.
@@ -860,6 +900,14 @@ mkdir -p ${o}/ux
 5. Write \`${o}/ux/flows.md\` — navigation flow diagrams
 6. Take **screenshots** of each screen at desktop resolution → \`${o}/ux/screenshots/\`
 
+## Validation
+
+\`\`\`bash
+bash ${a}/aped-ux/scripts/validate-ux.sh ${o}/ux
+\`\`\`
+
+If validation fails: fix missing files or content and re-validate.
+
 ## State Update
 
 Update \`${o}/state.yaml\`:
@@ -913,6 +961,7 @@ metadata:
 
 1. Read \`${a}/config.yaml\` — extract \`communication_language\`, \`ticket_system\`
 2. Read \`${o}/state.yaml\` — load full pipeline and sprint state
+3. Read \`${a}/aped-s/references/status-format.md\` for display conventions
 
 ## Pipeline Overview
 
@@ -957,11 +1006,20 @@ Based on current state, suggest the next logical command:
 - If all stories \`done\`: suggest pipeline complete
 - If blockers found: describe resolution path
 
-## Ticket System Integration
+## Ticket System Sync
+
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for status mapping.
 
 If \`ticket_system\` is not \`none\`:
-- Show ticket references alongside story statuses
-- Note any stories without ticket references
+- Show ticket ID alongside each story status
+- Flag any stories without ticket references
+- Check sync: compare state.yaml statuses with expected ticket statuses
+- If divergence detected: warn user — "state.yaml says X, ticket system should be Y"
+- Display mapping table:
+  - \`backlog\` → Backlog/Todo
+  - \`in-progress\` → In Progress
+  - \`review\` → In Review
+  - \`done\` → Done
 
 ## Output
 
@@ -1004,6 +1062,7 @@ Use when requirements change, priorities shift, or the current approach needs re
 1. Read \`${a}/config.yaml\` — extract config
 2. Read \`${o}/state.yaml\` — understand current pipeline state
 3. Read existing artifacts: brief, PRD, epics, stories
+4. Read \`${a}/aped-c/references/scope-change-guide.md\` for impact matrix and process
 
 ## Impact Assessment
 
@@ -1105,6 +1164,7 @@ Use on existing codebases to generate project context before running the APED pi
 
 1. Read \`${a}/config.yaml\` — extract config
 2. Verify this is a brownfield project (existing code, not greenfield)
+3. Read \`${a}/aped-ctx/references/analysis-checklist.md\` for the full analysis checklist
 
 ## Codebase Analysis
 
@@ -1223,6 +1283,7 @@ Generate comprehensive end-to-end and integration tests for completed stories or
 
 1. Read \`${a}/config.yaml\` — extract config
 2. Read \`${o}/state.yaml\` — find completed stories/epics
+3. Read \`${a}/aped-qa/references/test-patterns.md\` for framework selection and test templates
 
 ## Scope Selection
 
@@ -1390,13 +1451,18 @@ Quick checklist — no full adversarial review:
 - [ ] No regressions in existing tests
 - [ ] AC from quick spec satisfied
 
-## Git Commit
+## Git & Ticket Workflow
 
 Read \`ticket_system\` and \`git_provider\` from config.
-- Format: \`type(scope): description\`
-- Append ticket ref if configured
-- If \`git_provider\` is \`github\`: suggest PR creation with \`gh pr create\`
-- If \`git_provider\` is \`gitlab\`: suggest MR creation with \`glab mr create\`
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full guide.
+
+1. **Branch**: create \`fix/{ticket-id}-{slug}\` or \`feature/{ticket-id}-{slug}\`
+2. **Commits**: \`type({ticket-id}): description\` — include magic words per ticket provider
+3. **PR/MR**:
+   - \`github\`: \`gh pr create --title "fix({ticket-id}): description" --body "Fixes {ticket-id}"\`
+   - \`gitlab\`: \`glab mr create --title "fix({ticket-id}): description" --description "Closes {ticket-id}"\`
+   - \`bitbucket\`: push branch, create PR via web
+4. **Ticket**: move to Done after merge
 
 ## Output