diff --git a/.claude/skills/pair-process-bootstrap/SKILL.md b/.claude/skills/pair-process-bootstrap/SKILL.md index 6a23dbcd..ef0de344 100644 --- a/.claude/skills/pair-process-bootstrap/SKILL.md +++ b/.claude/skills/pair-process-bootstrap/SKILL.md @@ -99,38 +99,7 @@ Orchestrate the complete project setup sequence. Transforms a PRD into a fully c ### Step 2.2: Assessment Phase (Optional) 1. **Check**: Are assess-\* skills installed? Scan installed skills directory for `assess-*` skills. -2. **Act** (installed): Compose assess-\* skills in recommended sequence. Each skill checks its own adoption file first — already-decided domains are skipped automatically (resolution cascade). **assess-\* skills are output-only**: each returns a proposal `{ content, target, decision-metadata }` and writes nothing. For each accepted proposal, `/pair-process-bootstrap` composes `/pair-capability-record-decision(content, target, decision-metadata)` — the **sole adoption writer** — to persist it. Never let an assess-\* skill write adoption directly. - - **Recommended sequence** (respects adoption file dependencies): - 1. `/pair-capability-assess-architecture` → proposes `architecture.md` content (needed by stack and infrastructure) - 2. `/pair-capability-assess-stack` → proposes core sections of `tech-stack.md` (needed by testing and AI) - 3. `/pair-capability-assess-testing` → proposes testing section of `tech-stack.md` - 4. `/pair-capability-assess-ai` → proposes AI section of `tech-stack.md` - 5. `/pair-capability-assess-infrastructure` → proposes `infrastructure.md` content (needed by observability) - 6. `/pair-capability-assess-observability` → proposes observability section of `infrastructure.md` - 7. `/pair-capability-assess-methodology` → proposes methodology section of `way-of-working.md` - 8. `/pair-capability-assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/pair-capability-setup-pm` when installed) - - After each assessment (or after collecting the batch), compose `/pair-capability-record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/pair-capability-assess-pm` persists via `/pair-capability-setup-pm` when that skill is installed; otherwise `/pair-process-bootstrap` persists its proposal via `/pair-capability-record-decision` like the others. - - **Section ownership** (each assess-\* proposal owns its section; `/pair-capability-record-decision` preserves the rest on write): - - | Adoption File | Section | Owner Skill | - | -------------------- | ------------------ | ---------------------- | - | `architecture.md` | Full file | `/pair-capability-assess-architecture` | - | `tech-stack.md` | Core sections | `/pair-capability-assess-stack` | - | `tech-stack.md` | Testing section | `/pair-capability-assess-testing` | - | `tech-stack.md` | AI section | `/pair-capability-assess-ai` | - | `infrastructure.md` | Core sections | `/pair-capability-assess-infrastructure` | - | `infrastructure.md` | Observability | `/pair-capability-assess-observability`| - | `way-of-working.md` | Methodology | `/pair-capability-assess-methodology` | - | `way-of-working.md` | PM tool | `/pair-capability-assess-pm` | - | `way-of-working.md` | Quality gates | `/pair-process-bootstrap` (Step 3.2)| - - **Parallel safety**: Because assess-\* skills only produce proposals (no writes), they can run in parallel freely. The actual writes happen serially through `/pair-capability-record-decision` (the sole writer), which preserves sections it does not own. The recommended sequence orders the proposals by adoption-file dependency. - - **Partial installation**: If only some assess-\* skills are installed, compose those and skip the rest with a warning. Each assess-\* skill is independent — partial installation is supported. - +2. **Act** (installed): Compose assess-\* skills in recommended sequence — see [assess-orchestration.md](assess-orchestration.md) for the sequence, each skill's owned adoption-file section, and the parallel-safety/partial-installation rules. Each skill checks its own adoption file first — already-decided domains are skipped automatically (resolution cascade). **assess-\* skills are output-only**: each returns a proposal `{ content, target, decision-metadata }` and writes nothing. For each accepted proposal, `/pair-process-bootstrap` composes `/pair-capability-record-decision(content, target, decision-metadata)` — the **sole adoption writer** — to persist it. Never let an assess-\* skill write adoption directly. 3. **Act** (not installed): Warn and proceed with manual assessment: > assess-\* skills are not yet installed. Proceeding with manual assessment. diff --git a/.claude/skills/pair-process-bootstrap/assess-orchestration.md b/.claude/skills/pair-process-bootstrap/assess-orchestration.md new file mode 100644 index 00000000..e8745889 --- /dev/null +++ b/.claude/skills/pair-process-bootstrap/assess-orchestration.md @@ -0,0 +1,34 @@ +# Phase 2, Step 2.2: Assess-\* Orchestration — Detail + +Disclosed from [SKILL.md](SKILL.md) Step 2.2 — only reached when at least one `assess-*` skill is installed. + +**Recommended sequence** (respects adoption file dependencies): + +1. `/pair-capability-assess-architecture` → proposes `architecture.md` content (needed by stack and infrastructure) +2. `/pair-capability-assess-stack` → proposes core sections of `tech-stack.md` (needed by testing and AI) +3. `/pair-capability-assess-testing` → proposes testing section of `tech-stack.md` +4. `/pair-capability-assess-ai` → proposes AI section of `tech-stack.md` +5. `/pair-capability-assess-infrastructure` → proposes `infrastructure.md` content (needed by observability) +6. `/pair-capability-assess-observability` → proposes observability section of `infrastructure.md` +7. `/pair-capability-assess-methodology` → proposes methodology section of `way-of-working.md` +8. `/pair-capability-assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/pair-capability-setup-pm` when installed) + +After each assessment (or after collecting the batch), compose `/pair-capability-record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/pair-capability-assess-pm` persists via `/pair-capability-setup-pm` when that skill is installed; otherwise `/pair-process-bootstrap` persists its proposal via `/pair-capability-record-decision` like the others. + +**Section ownership** (each assess-\* proposal owns its section; `/pair-capability-record-decision` preserves the rest on write): + +| Adoption File | Section | Owner Skill | +| --------------------- | ------------------ | ---------------------- | +| `architecture.md` | Full file | `/pair-capability-assess-architecture` | +| `tech-stack.md` | Core sections | `/pair-capability-assess-stack` | +| `tech-stack.md` | Testing section | `/pair-capability-assess-testing` | +| `tech-stack.md` | AI section | `/pair-capability-assess-ai` | +| `infrastructure.md` | Core sections | `/pair-capability-assess-infrastructure` | +| `infrastructure.md` | Observability | `/pair-capability-assess-observability`| +| `way-of-working.md` | Methodology | `/pair-capability-assess-methodology` | +| `way-of-working.md` | PM tool | `/pair-capability-assess-pm` | +| `way-of-working.md` | Quality gates | `/pair-process-bootstrap` (Step 3.2)| + +**Parallel safety**: Because assess-\* skills only produce proposals (no writes), they can run in parallel freely. The actual writes happen serially through `/pair-capability-record-decision` (the sole writer), which preserves sections it does not own. The recommended sequence orders the proposals by adoption-file dependency. + +**Partial installation**: If only some assess-\* skills are installed, compose those and skip the rest with a warning. Each assess-\* skill is independent — partial installation is supported. diff --git a/.claude/skills/pair-process-implement/SKILL.md b/.claude/skills/pair-process-implement/SKILL.md index 461b4540..f6850ea4 100644 --- a/.claude/skills/pair-process-implement/SKILL.md +++ b/.claude/skills/pair-process-implement/SKILL.md @@ -307,48 +307,7 @@ Follow the TDD discipline rules strictly: ## Phase 4: Post-Review Merge -After code review approval (typically via `/pair-process-review`), re-invoke `/pair-process-implement` to merge and close. - -### Step 4.1: Verify Review Approval - -1. **Check**: Is the PR approved by the reviewer? -2. **Skip**: If not approved → **HALT**. Wait for review completion. -3. **Verify**: PR has at least one approval. - -### Step 4.2: Prepare Merge Commit Message - -1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase). -2. **Act**: Draft the final commit message: - - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md). - - **If merge or rebase**: use the default merge/rebase message. -3. **Act** (BLOCKING): Present the commit message to the developer for confirmation: - - > **Merge commit message:** - > - > ```text - > [#] feat: - > - > - - > - Tasks: T-1, T-2, ..., T-N - > - > Refs: # - > ``` - > - > Confirm or edit? - -4. **Verify**: Developer confirms the commit message. - -### Step 4.3: Merge PR - -1. **Act**: Merge the PR with the confirmed commit message and the configured merge strategy. -2. **Verify**: PR merged and closed. - -### Step 4.4: Update Story & Parents - -1. **Act**: Update user story status to "Done" in the PM tool. -2. **Act**: Check parent epic — if ALL stories in the epic are Done, update epic status to "Done". -3. **Act**: Check parent initiative — if ALL epics in the initiative are Done, update initiative status to "Done". -4. **Verify**: Story and parent hierarchy updated recursively. +After code review approval (typically via `/pair-process-review`), re-invoke `/pair-process-implement` to merge and close — see [post-review-merge.md](post-review-merge.md) for the verify-approval, merge-commit, merge, and parent-cascade steps (Steps 4.1–4.4) plus the completion output. ## Output Format @@ -365,17 +324,7 @@ IMPLEMENTATION COMPLETE: └── Quality: [All gates passing] ``` -At merge (Phase 4): - -```text -STORY DONE: -├── Story: [#ID: Title] -├── PR: [#PR-number — merged] -├── Merge: [squash | merge | rebase] -├── Story: Done -├── Epic: [#ID — Done | In Progress (X/Y stories done)] -└── Initiative: [#ID — Done | In Progress (X/Y epics done)] -``` +At merge (Phase 4): see [post-review-merge.md](post-review-merge.md). ## HALT Conditions diff --git a/.claude/skills/pair-process-implement/post-review-merge.md b/.claude/skills/pair-process-implement/post-review-merge.md new file mode 100644 index 00000000..9d32c528 --- /dev/null +++ b/.claude/skills/pair-process-implement/post-review-merge.md @@ -0,0 +1,56 @@ +# Phase 4: Post-Review Merge — Detail + +Disclosed from [SKILL.md](SKILL.md) Phase 4 — only reached when `/pair-process-implement` is re-invoked after code review approval (typically via `/pair-process-review`), to merge and close the story. + +### Step 4.1: Verify Review Approval + +1. **Check**: Is the PR approved by the reviewer? +2. **Skip**: If not approved → **HALT**. Wait for review completion. +3. **Verify**: PR has at least one approval. + +### Step 4.2: Prepare Merge Commit Message + +1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase). +2. **Act**: Draft the final commit message: + - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md). + - **If merge or rebase**: use the default merge/rebase message. +3. **Act** (BLOCKING): Present the commit message to the developer for confirmation: + + > **Merge commit message:** + > + > ```text + > [#] feat: + > + > - + > - Tasks: T-1, T-2, ..., T-N + > + > Refs: # + > ``` + > + > Confirm or edit? + +4. **Verify**: Developer confirms the commit message. + +### Step 4.3: Merge PR + +1. **Act**: Merge the PR with the confirmed commit message and the configured merge strategy. +2. **Verify**: PR merged and closed. + +### Step 4.4: Update Story & Parents + +1. **Act**: Update user story status to "Done" in the PM tool. +2. **Act**: Check parent epic — if ALL stories in the epic are Done, update epic status to "Done". +3. **Act**: Check parent initiative — if ALL epics in the initiative are Done, update initiative status to "Done". +4. **Verify**: Story and parent hierarchy updated recursively. + +## Output Format (merge) + +```text +STORY DONE: +├── Story: [#ID: Title] +├── PR: [#PR-number — merged] +├── Merge: [squash | merge | rebase] +├── Story: Done +├── Epic: [#ID — Done | In Progress (X/Y stories done)] +└── Initiative: [#ID — Done | In Progress (X/Y epics done)] +``` diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md index 2fd5c97f..1811a519 100644 --- a/.claude/skills/pair-process-review/SKILL.md +++ b/.claude/skills/pair-process-review/SKILL.md @@ -142,36 +142,7 @@ This phase uses a **4-level graceful degradation cascade** depending on which op ### Step 3.2: Run Adoption Check -**Level 1** (/pair-capability-verify-adoption + /pair-capability-assess-stack): - -1. Compose `/pair-capability-verify-adoption` with `$scope = all`. -2. For each non-conformity: - - **Tech-stack**: compose `/pair-capability-assess-stack` (output-only — returns a proposal) → on developer approval, `/pair-process-review` persists the entry via `/pair-capability-record-decision(content, target)` (the sole writer); on rejection → CHANGES-REQUESTED. - - **Architecture**: report to developer for resolution. Missing ADR → HALT via `/pair-capability-record-decision`. - - **Other** (security, coding-standards, infrastructure): report findings. -3. Record all results. - -**Level 2** (/pair-capability-verify-adoption only): - -1. Compose `/pair-capability-verify-adoption` with `$scope = all`. -2. For tech-stack non-conformities: report as findings for manual resolution. -3. For other non-conformities: same as Level 1. -4. Record results. - -**Level 3** (/pair-capability-assess-stack only): - -1. Inline check: scan PR diff for new dependencies not in [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md). -2. For unlisted dependencies: compose `/pair-capability-assess-stack` (output-only — returns a proposal) → on approval, `/pair-process-review` persists via `/pair-capability-record-decision`; on rejection, flag as CHANGES-REQUESTED. -3. No broader adoption compliance check (security, architecture, etc. — covered partially by Phase 2). -4. Record results. - -**Level 4** (neither installed): - -1. Warn: - - > `/pair-capability-verify-adoption` and `/pair-capability-assess-stack` are not installed — skipping automated adoption compliance. Please manually verify code against adoption files. - -2. Move to Phase 4. +Run the procedure for the level determined in Step 3.1 — see [degradation-levels.md](degradation-levels.md) for the exact steps of each of the 4 levels. ### Step 3.3: Verify Adoption Results @@ -246,77 +217,9 @@ Based on compiled findings: 4. **Verify**: If "Merge now" selected → proceed to Phase 6. Otherwise → output and stop. -## Phase 6: Merge & Close (APPROVED only) - -### Step 6.1: Read Merge Strategy - -1. **Check**: Is merge strategy specified in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)? -2. **Skip**: If not specified, default to `squash`. -3. **Act**: Read the adopted merge strategy (`squash`, `merge`, or `rebase`). -4. **Verify**: Strategy determined. - -### Step 6.2: Prepare Merge Commit - -1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md): - - ```text - [#] feat: - - - - - Tasks: T-1, T-2, ..., T-N +## Phase 6: Merge & Close (APPROVED only, optional) - Refs: # - ``` - -2. **Act** (BLOCKING): Present to reviewer for confirmation: - - > **Merge commit message:** - > - > ```text - > [commit message] - > ``` - > - > Confirm or edit? - -3. **Verify**: Reviewer confirms message. - -### Step 6.3: Merge PR - -1. **Act**: Merge the PR using the adopted strategy (per [github-implementation.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/github-implementation.md)): - - MCP-first: use `merge_pull_request` with `merge_method` and `commit_title` + `commit_message`. - - CLI fallback: `gh pr merge --squash --subject "" --body "<body>"`. -2. **Verify**: PR merged and closed. - -### Step 6.4: Update Story & Parent Cascade - -1. **Act**: Close the user story issue in the PM tool: - - MCP: `issue_write` with `method = update`, `state = closed`, `state_reason = completed`. - - CLI: `gh issue close <story-number> --reason completed`. -2. **Act**: Check parent epic — read sub-issues to determine if ALL stories are Done: - - MCP: `issue_read` with `method = get_sub_issues` on the epic. - - If all sub-issues closed → close the epic with `state_reason = completed`. - - If not all closed → leave epic open. -3. **Act**: Check parent initiative — same cascade logic: - - If all epics closed → close the initiative. - - If not all closed → leave initiative open. -4. **Verify**: Story closed. Epic and initiative updated if applicable. - -### Step 6.5: Branch Cleanup - -1. **Act**: Delete the feature branch (remote): - - CLI: `git push origin --delete <branch>`. -2. **Act**: Remove the story's checkpoint if one exists — `.pair/working/checkpoints/<story-id>.md` — so completed-story state does not linger as stale context (per the task-scoped cleanup rule; see `/pair-capability-checkpoint`). -3. **Verify**: Feature branch deleted and story checkpoint removed (if any existed). - -### Step 6.6: Post-Merge Manual Test Validation (Optional) - -1. **Check**: Is `/pair-capability-execute-manual-tests` installed? Does the project have a manual test suite (`qa/` directory)? -2. **Skip**: If skill not installed or no test suite found → skip. Log: "Manual test validation skipped — no suite or skill not installed." -3. **Act**: Compose `/pair-capability-execute-manual-tests` with `$scope = all`, `$priority = P0` (blockers only for fast validation). -4. **Verify**: If PASS → note in review output. If FAIL → do NOT revert the merge. Instead: - - Create a GitHub issue for each Critical/Major failure. - - Append manual test results as addendum to the review report (PR comment). - - Warn: "Post-merge manual tests found failures. Issues created." +Only reached when the reviewer picked "Merge now" in Step 5.4 — see [merge-and-cascade.md](merge-and-cascade.md) for the merge-strategy, merge-commit, merge, parent-cascade, branch-cleanup, and post-merge-manual-test steps (Steps 6.1–6.6) plus the completion output. ## Output Format @@ -335,18 +238,7 @@ REVIEW COMPLETE: └── Report: [Posted as PR comment] ``` -At merge (Phase 6): - -```text -STORY DONE: -├── Story: [#ID: Title] -├── PR: [#PR-number — merged] -├── Merge: [squash | merge | rebase] -├── Story: Done -├── Epic: [#ID — Done | In Progress (X/Y stories done)] -├── Initiative: [#ID — Done | In Progress (X/Y epics done)] -└── Manual Tests: [PASS | FAIL — N issues created | SKIPPED — no suite] -``` +At merge (Phase 6): see [merge-and-cascade.md](merge-and-cascade.md). ## HALT Conditions diff --git a/.claude/skills/pair-process-review/degradation-levels.md b/.claude/skills/pair-process-review/degradation-levels.md new file mode 100644 index 00000000..7f42662f --- /dev/null +++ b/.claude/skills/pair-process-review/degradation-levels.md @@ -0,0 +1,34 @@ +# Phase 3, Step 3.2: Adoption Compliance Levels — Detail + +Disclosed from [SKILL.md](SKILL.md) Step 3.2. Run only the procedure matching the level determined in Step 3.1 — the other three never apply on this run. + +**Level 1** (/pair-capability-verify-adoption + /pair-capability-assess-stack): + +1. Compose `/pair-capability-verify-adoption` with `$scope = all`. +2. For each non-conformity: + - **Tech-stack**: compose `/pair-capability-assess-stack` (output-only — returns a proposal) → on developer approval, `/pair-process-review` persists the entry via `/pair-capability-record-decision(content, target)` (the sole writer); on rejection → CHANGES-REQUESTED. + - **Architecture**: report to developer for resolution. Missing ADR → HALT via `/pair-capability-record-decision`. + - **Other** (security, coding-standards, infrastructure): report findings. +3. Record all results. + +**Level 2** (/pair-capability-verify-adoption only): + +1. Compose `/pair-capability-verify-adoption` with `$scope = all`. +2. For tech-stack non-conformities: report as findings for manual resolution. +3. For other non-conformities: same as Level 1. +4. Record results. + +**Level 3** (/pair-capability-assess-stack only): + +1. Inline check: scan PR diff for new dependencies not in [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md). +2. For unlisted dependencies: compose `/pair-capability-assess-stack` (output-only — returns a proposal) → on approval, `/pair-process-review` persists via `/pair-capability-record-decision`; on rejection, flag as CHANGES-REQUESTED. +3. No broader adoption compliance check (security, architecture, etc. — covered partially by Phase 2). +4. Record results. + +**Level 4** (neither installed): + +1. Warn: + + > `/pair-capability-verify-adoption` and `/pair-capability-assess-stack` are not installed — skipping automated adoption compliance. Please manually verify code against adoption files. + +2. Move to Phase 4. diff --git a/.claude/skills/pair-process-review/merge-and-cascade.md b/.claude/skills/pair-process-review/merge-and-cascade.md new file mode 100644 index 00000000..9a7fb4be --- /dev/null +++ b/.claude/skills/pair-process-review/merge-and-cascade.md @@ -0,0 +1,86 @@ +# Phase 6: Merge & Close — Detail + +Disclosed from [SKILL.md](SKILL.md) Phase 6 — only reached when the reviewer picked "Merge now" in Step 5.4. + +### Step 6.1: Read Merge Strategy + +1. **Check**: Is merge strategy specified in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)? +2. **Skip**: If not specified, default to `squash`. +3. **Act**: Read the adopted merge strategy (`squash`, `merge`, or `rebase`). +4. **Verify**: Strategy determined. + +### Step 6.2: Prepare Merge Commit + +1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md): + + ```text + [#<story-id>] feat: <story description> + + - <summary of changes> + - Tasks: T-1, T-2, ..., T-N + + Refs: #<story-id> + ``` + +2. **Act** (BLOCKING): Present to reviewer for confirmation: + + > **Merge commit message:** + > + > ```text + > [commit message] + > ``` + > + > Confirm or edit? + +3. **Verify**: Reviewer confirms message. + +### Step 6.3: Merge PR + +1. **Act**: Merge the PR using the adopted strategy (per [github-implementation.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/github-implementation.md)): + - MCP-first: use `merge_pull_request` with `merge_method` and `commit_title` + `commit_message`. + - CLI fallback: `gh pr merge <number> --squash --subject "<title>" --body "<body>"`. +2. **Verify**: PR merged and closed. + +### Step 6.4: Update Story & Parent Cascade + +1. **Act**: Close the user story issue in the PM tool: + - MCP: `issue_write` with `method = update`, `state = closed`, `state_reason = completed`. + - CLI: `gh issue close <story-number> --reason completed`. +2. **Act**: Check parent epic — read sub-issues to determine if ALL stories are Done: + - MCP: `issue_read` with `method = get_sub_issues` on the epic. + - If all sub-issues closed → close the epic with `state_reason = completed`. + - If not all closed → leave epic open. +3. **Act**: Check parent initiative — same cascade logic: + - If all epics closed → close the initiative. + - If not all closed → leave initiative open. +4. **Verify**: Story closed. Epic and initiative updated if applicable. + +### Step 6.5: Branch Cleanup + +1. **Act**: Delete the feature branch (remote): + - CLI: `git push origin --delete <branch>`. +2. **Act**: Remove the story's checkpoint if one exists — `.pair/working/checkpoints/<story-id>.md` — so completed-story state does not linger as stale context (per the task-scoped cleanup rule; see `/pair-capability-checkpoint`). +3. **Verify**: Feature branch deleted and story checkpoint removed (if any existed). + +### Step 6.6: Post-Merge Manual Test Validation (Optional) + +1. **Check**: Is `/pair-capability-execute-manual-tests` installed? Does the project have a manual test suite (`qa/` directory)? +2. **Skip**: If skill not installed or no test suite found → skip. Log: "Manual test validation skipped — no suite or skill not installed." +3. **Act**: Compose `/pair-capability-execute-manual-tests` with `$scope = all`, `$priority = P0` (blockers only for fast validation). +4. **Verify**: If PASS → note in review output. If FAIL → do NOT revert the merge. Instead: + - Create a GitHub issue for each Critical/Major failure. + - Append manual test results as addendum to the review report (PR comment). + - Warn: "Post-merge manual tests found failures. Issues created." + +## Output Format (merge) + +```text +STORY DONE: +├── Story: [#ID: Title] +├── PR: [#PR-number — merged] +├── Merge: [squash | merge | rebase] +├── Story: Done +├── Epic: [#ID — Done | In Progress (X/Y stories done)] +├── Initiative: [#ID — Done | In Progress (X/Y epics done)] +└── Manual Tests: [PASS | FAIL — N issues created | SKIPPED — no suite] +``` diff --git a/apps/pair-cli/src/commands/install/handler.test.ts b/apps/pair-cli/src/commands/install/handler.test.ts index b67cdfef..41621c44 100644 --- a/apps/pair-cli/src/commands/install/handler.test.ts +++ b/apps/pair-cli/src/commands/install/handler.test.ts @@ -454,6 +454,64 @@ describe('install — KB distribution pipeline bug regression', () => { }) }) + describe('#313 T5 prerequisite: multi-file skill dir with deep datasetRoot', () => { + test('ships sibling files and their cross-references resolve post-install', async () => { + const moduleDir = '/project/apps/pair-cli' + const datasetSrc = `${moduleDir}/node_modules/@pair/knowledge-hub/dataset` + + const skillsConfig = { + asset_registries: { + skills: { + source: '.skills', + behavior: 'mirror', + flatten: true, + prefix: 'pair', + description: 'Agent skills', + targets: [{ path: '.claude/skills/', mode: 'canonical' }], + }, + }, + } + + const fs = new InMemoryFileSystemService( + { + [`${moduleDir}/package.json`]: JSON.stringify({ + name: '@pair/pair-cli', + version: '0.1.0', + }), + [`${moduleDir}/node_modules/@pair/knowledge-hub/package.json`]: JSON.stringify({ + name: '@pair/knowledge-hub', + }), + [`${moduleDir}/config.json`]: JSON.stringify(skillsConfig), + [`${datasetSrc}/.skills/process/implement/SKILL.md`]: + '# /implement\n\nSee [edge cases](./edge-cases.md) when a step fails.', + [`${datasetSrc}/.skills/process/implement/edge-cases.md`]: + '# Edge Cases\n\nBack to [SKILL.md](./SKILL.md).', + }, + moduleDir, + moduleDir, + ) + + const config: InstallCommandConfig = { + command: 'install', + resolution: 'default', + kb: true, + offline: false, + } + + await handleInstallCommand(config, fs) + + const targetDir = `${moduleDir}/.claude/skills/pair-process-implement` + // Sibling file shipped alongside SKILL.md, not dropped by flatten+prefix + await expect(fs.exists(`${targetDir}/edge-cases.md`)).resolves.toBe(true) + + const skillContent = await fs.readFile(`${targetDir}/SKILL.md`) + const edgeCasesContent = await fs.readFile(`${targetDir}/edge-cases.md`) + // Same-directory cross-references resolve post-install (both files moved together) + expect(skillContent).toContain('[edge cases](./edge-cases.md)') + expect(edgeCasesContent).toContain('[SKILL.md](./SKILL.md)') + }) + }) + describe('Bug 3: target directory resolution', () => { test('output targets CWD when rootModuleDir differs', async () => { const moduleDir = '/project/apps/pair-cli' diff --git a/packages/content-ops/src/ops/copy/copy-directory-transforms.test.ts b/packages/content-ops/src/ops/copy/copy-directory-transforms.test.ts index fda7c5fd..96b62969 100644 --- a/packages/content-ops/src/ops/copy/copy-directory-transforms.test.ts +++ b/packages/content-ops/src/ops/copy/copy-directory-transforms.test.ts @@ -327,6 +327,42 @@ describe('copyDirectoryWithTransforms (via copyPathOps, flatten/prefix)', () => ).rejects.toThrow(/collision/i) }) + describe('multi-file skill directories (story #313 T5 prerequisite)', () => { + it('ships every sibling file of a multi-file skill dir, not just SKILL.md', async () => { + const fileService = createTestFileService({ + '/dataset/source/process/implement/SKILL.md': + '---\nname: implement\n---\n# /implement\nSee [edge cases](./edge-cases.md).', + '/dataset/source/process/implement/edge-cases.md': + '# Edge Cases\nBack to [SKILL](./SKILL.md).', + '/dataset/source/process/implement/reference.md': '# Reference material', + }) + + await copyPathOps({ + fileService, + source: 'source', + target: 'target', + datasetRoot: '/dataset', + options: { flatten: true, prefix: 'pair', targets: [] }, + }) + + // All three sibling files land in the same transformed target directory + await TEST_ASSERTIONS.assertFileExists( + fileService, + '/dataset/target/pair-process-implement/reference.md', + '# Reference material', + ) + const skill = await fileService.readFile('/dataset/target/pair-process-implement/SKILL.md') + const edgeCases = await fileService.readFile( + '/dataset/target/pair-process-implement/edge-cases.md', + ) + + // Cross-references between siblings resolve post-install (same-dir relative + // links are unchanged since both files move together under the same rename) + expect(skill).toContain('[edge cases](./edge-cases.md)') + expect(edgeCases).toContain('[SKILL](./SKILL.md)') + }) + }) + describe('mirror behavior — idempotent updates (AC4)', () => { it('removes a stale flattened directory when its source skill is gone', async () => { const fileService = createTestFileService({ diff --git a/packages/content-ops/src/ops/link-rewriter.ts b/packages/content-ops/src/ops/link-rewriter.ts index 64687929..997c631f 100644 --- a/packages/content-ops/src/ops/link-rewriter.ts +++ b/packages/content-ops/src/ops/link-rewriter.ts @@ -57,6 +57,36 @@ function reRootTarget( return absoluteTarget } +/** + * Rebases a link target that resolves inside the current file's own original + * directory (e.g. a sibling file in a multi-file skill dir) onto the new + * directory that same dir is moving to. + * + * This takes priority over `reRootTarget`: the current file's directory is + * precisely the one this copy operation is moving from `originalFileDir` to + * `newFileDir`, so a link resolving inside it maps 1:1 onto the new + * directory — no need to go through the coarser dataset-root re-rooting, + * which only knows about the *overall* content-root move and would otherwise + * misplace a same-directory sibling link (see #313 T5 fixture regression). + * + * Known scope boundary: only rebases links resolving inside the SAME + * directory the current file lives in. A link that escapes to a *different* + * transformed sibling directory (e.g. one skill linking into another skill's + * sibling file) still falls through to `reRootTarget` and is not corrected by + * this function — not needed by any skill in the corpus today. + */ +function rebaseWithinMovedDir( + absoluteTarget: string, + originalFileDir: string, + newFileDir: string, +): string | null { + if (absoluteTarget === originalFileDir) return newFileDir + if (absoluteTarget.startsWith(originalFileDir + '/')) { + return newFileDir + absoluteTarget.slice(originalFileDir.length) + } + return null +} + type ComputeNewHrefParams = { href: string originalFileDir: string @@ -65,6 +95,29 @@ type ComputeNewHrefParams = { sourceContentRoot?: string } +/** + * Resolves the absolute target a link points at, after accounting for the + * current copy operation: a same-directory rebase takes priority over the + * coarser dataset-root re-root (see `rebaseWithinMovedDir` docs). + */ +function resolveAbsoluteTarget(params: { + originalFileDir: string + newFileDir: string + pathPart: string + datasetRoot?: string + sourceContentRoot?: string +}): string { + const { originalFileDir, newFileDir, pathPart, datasetRoot, sourceContentRoot } = params + const absoluteTarget = posix.resolve(originalFileDir, pathPart) + + const rebased = rebaseWithinMovedDir(absoluteTarget, originalFileDir, newFileDir) + if (rebased) return rebased + if (datasetRoot && sourceContentRoot) { + return reRootTarget(absoluteTarget, datasetRoot, sourceContentRoot) + } + return absoluteTarget +} + /** * Computes the new href for a relative link after the file has moved. * Returns null if the link should not be rewritten (external, anchor, unchanged). @@ -79,11 +132,13 @@ function computeNewHref(params: ComputeNewHrefParams): string | null { if (pathPart === '') return null // pure anchor link - let absoluteTarget = posix.resolve(originalFileDir, pathPart) - - if (datasetRoot && sourceContentRoot) { - absoluteTarget = reRootTarget(absoluteTarget, datasetRoot, sourceContentRoot) - } + const absoluteTarget = resolveAbsoluteTarget({ + originalFileDir, + newFileDir, + pathPart, + ...(datasetRoot && { datasetRoot }), + ...(sourceContentRoot && { sourceContentRoot }), + }) let newRelativePath = posix.relative(newFileDir, absoluteTarget) diff --git a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md index fd0ec189..63eb8cf1 100644 --- a/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/bootstrap/SKILL.md @@ -99,38 +99,7 @@ Orchestrate the complete project setup sequence. Transforms a PRD into a fully c ### Step 2.2: Assessment Phase (Optional) 1. **Check**: Are assess-\* skills installed? Scan installed skills directory for `assess-*` skills. -2. **Act** (installed): Compose assess-\* skills in recommended sequence. Each skill checks its own adoption file first — already-decided domains are skipped automatically (resolution cascade). **assess-\* skills are output-only**: each returns a proposal `{ content, target, decision-metadata }` and writes nothing. For each accepted proposal, `/bootstrap` composes `/record-decision(content, target, decision-metadata)` — the **sole adoption writer** — to persist it. Never let an assess-\* skill write adoption directly. - - **Recommended sequence** (respects adoption file dependencies): - 1. `/assess-architecture` → proposes `architecture.md` content (needed by stack and infrastructure) - 2. `/assess-stack` → proposes core sections of `tech-stack.md` (needed by testing and AI) - 3. `/assess-testing` → proposes testing section of `tech-stack.md` - 4. `/assess-ai` → proposes AI section of `tech-stack.md` - 5. `/assess-infrastructure` → proposes `infrastructure.md` content (needed by observability) - 6. `/assess-observability` → proposes observability section of `infrastructure.md` - 7. `/assess-methodology` → proposes methodology section of `way-of-working.md` - 8. `/assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/setup-pm` when installed) - - After each assessment (or after collecting the batch), compose `/record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/assess-pm` persists via `/setup-pm` when that skill is installed; otherwise `/bootstrap` persists its proposal via `/record-decision` like the others. - - **Section ownership** (each assess-\* proposal owns its section; `/record-decision` preserves the rest on write): - - | Adoption File | Section | Owner Skill | - | -------------------- | ------------------ | ---------------------- | - | `architecture.md` | Full file | `/assess-architecture` | - | `tech-stack.md` | Core sections | `/assess-stack` | - | `tech-stack.md` | Testing section | `/assess-testing` | - | `tech-stack.md` | AI section | `/assess-ai` | - | `infrastructure.md` | Core sections | `/assess-infrastructure` | - | `infrastructure.md` | Observability | `/assess-observability`| - | `way-of-working.md` | Methodology | `/assess-methodology` | - | `way-of-working.md` | PM tool | `/assess-pm` | - | `way-of-working.md` | Quality gates | `/bootstrap` (Step 3.2)| - - **Parallel safety**: Because assess-\* skills only produce proposals (no writes), they can run in parallel freely. The actual writes happen serially through `/record-decision` (the sole writer), which preserves sections it does not own. The recommended sequence orders the proposals by adoption-file dependency. - - **Partial installation**: If only some assess-\* skills are installed, compose those and skip the rest with a warning. Each assess-\* skill is independent — partial installation is supported. - +2. **Act** (installed): Compose assess-\* skills in recommended sequence — see [assess-orchestration.md](assess-orchestration.md) for the sequence, each skill's owned adoption-file section, and the parallel-safety/partial-installation rules. Each skill checks its own adoption file first — already-decided domains are skipped automatically (resolution cascade). **assess-\* skills are output-only**: each returns a proposal `{ content, target, decision-metadata }` and writes nothing. For each accepted proposal, `/bootstrap` composes `/record-decision(content, target, decision-metadata)` — the **sole adoption writer** — to persist it. Never let an assess-\* skill write adoption directly. 3. **Act** (not installed): Warn and proceed with manual assessment: > assess-\* skills are not yet installed. Proceeding with manual assessment. diff --git a/packages/knowledge-hub/dataset/.skills/process/bootstrap/assess-orchestration.md b/packages/knowledge-hub/dataset/.skills/process/bootstrap/assess-orchestration.md new file mode 100644 index 00000000..5703c396 --- /dev/null +++ b/packages/knowledge-hub/dataset/.skills/process/bootstrap/assess-orchestration.md @@ -0,0 +1,34 @@ +# Phase 2, Step 2.2: Assess-\* Orchestration — Detail + +Disclosed from [SKILL.md](SKILL.md) Step 2.2 — only reached when at least one `assess-*` skill is installed. + +**Recommended sequence** (respects adoption file dependencies): + +1. `/assess-architecture` → proposes `architecture.md` content (needed by stack and infrastructure) +2. `/assess-stack` → proposes core sections of `tech-stack.md` (needed by testing and AI) +3. `/assess-testing` → proposes testing section of `tech-stack.md` +4. `/assess-ai` → proposes AI section of `tech-stack.md` +5. `/assess-infrastructure` → proposes `infrastructure.md` content (needed by observability) +6. `/assess-observability` → proposes observability section of `infrastructure.md` +7. `/assess-methodology` → proposes methodology section of `way-of-working.md` +8. `/assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/setup-pm` when installed) + +After each assessment (or after collecting the batch), compose `/record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/assess-pm` persists via `/setup-pm` when that skill is installed; otherwise `/bootstrap` persists its proposal via `/record-decision` like the others. + +**Section ownership** (each assess-\* proposal owns its section; `/record-decision` preserves the rest on write): + +| Adoption File | Section | Owner Skill | +| --------------------- | ------------------ | ---------------------- | +| `architecture.md` | Full file | `/assess-architecture` | +| `tech-stack.md` | Core sections | `/assess-stack` | +| `tech-stack.md` | Testing section | `/assess-testing` | +| `tech-stack.md` | AI section | `/assess-ai` | +| `infrastructure.md` | Core sections | `/assess-infrastructure` | +| `infrastructure.md` | Observability | `/assess-observability`| +| `way-of-working.md` | Methodology | `/assess-methodology` | +| `way-of-working.md` | PM tool | `/assess-pm` | +| `way-of-working.md` | Quality gates | `/bootstrap` (Step 3.2)| + +**Parallel safety**: Because assess-\* skills only produce proposals (no writes), they can run in parallel freely. The actual writes happen serially through `/record-decision` (the sole writer), which preserves sections it does not own. The recommended sequence orders the proposals by adoption-file dependency. + +**Partial installation**: If only some assess-\* skills are installed, compose those and skip the rest with a warning. Each assess-\* skill is independent — partial installation is supported. diff --git a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md index 01fe334d..8a386b7e 100644 --- a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md @@ -308,48 +308,7 @@ Follow the TDD discipline rules strictly, and the [Design Rules](../../../.pair/ ## Phase 4: Post-Review Merge -After code review approval (typically via `/review`), re-invoke `/implement` to merge and close. - -### Step 4.1: Verify Review Approval - -1. **Check**: Is the PR approved by the reviewer? -2. **Skip**: If not approved → **HALT**. Wait for review completion. -3. **Verify**: PR has at least one approval. - -### Step 4.2: Prepare Merge Commit Message - -1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase). -2. **Act**: Draft the final commit message: - - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md). - - **If merge or rebase**: use the default merge/rebase message. -3. **Act** (BLOCKING): Present the commit message to the developer for confirmation: - - > **Merge commit message:** - > - > ```text - > [#<story-id>] feat: <story description> - > - > - <summary of changes> - > - Tasks: T-1, T-2, ..., T-N - > - > Refs: #<story-id> - > ``` - > - > Confirm or edit? - -4. **Verify**: Developer confirms the commit message. - -### Step 4.3: Merge PR - -1. **Act**: Merge the PR with the confirmed commit message and the configured merge strategy. -2. **Verify**: PR merged and closed. - -### Step 4.4: Update Story & Parents - -1. **Act**: Update user story status to "Done" in the PM tool. -2. **Act**: Check parent epic — if ALL stories in the epic are Done, update epic status to "Done". -3. **Act**: Check parent initiative — if ALL epics in the initiative are Done, update initiative status to "Done". -4. **Verify**: Story and parent hierarchy updated recursively. +After code review approval (typically via `/review`), re-invoke `/implement` to merge and close — see [post-review-merge.md](post-review-merge.md) for the verify-approval, merge-commit, merge, and parent-cascade steps (Steps 4.1–4.4) plus the completion output. ## Output Format @@ -366,17 +325,7 @@ IMPLEMENTATION COMPLETE: └── Quality: [All gates passing] ``` -At merge (Phase 4): - -```text -STORY DONE: -├── Story: [#ID: Title] -├── PR: [#PR-number — merged] -├── Merge: [squash | merge | rebase] -├── Story: Done -├── Epic: [#ID — Done | In Progress (X/Y stories done)] -└── Initiative: [#ID — Done | In Progress (X/Y epics done)] -``` +At merge (Phase 4): see [post-review-merge.md](post-review-merge.md). ## HALT Conditions diff --git a/packages/knowledge-hub/dataset/.skills/process/implement/post-review-merge.md b/packages/knowledge-hub/dataset/.skills/process/implement/post-review-merge.md new file mode 100644 index 00000000..7f9b54a0 --- /dev/null +++ b/packages/knowledge-hub/dataset/.skills/process/implement/post-review-merge.md @@ -0,0 +1,56 @@ +# Phase 4: Post-Review Merge — Detail + +Disclosed from [SKILL.md](SKILL.md) Phase 4 — only reached when `/implement` is re-invoked after code review approval (typically via `/review`), to merge and close the story. + +### Step 4.1: Verify Review Approval + +1. **Check**: Is the PR approved by the reviewer? +2. **Skip**: If not approved → **HALT**. Wait for review completion. +3. **Verify**: PR has at least one approval. + +### Step 4.2: Prepare Merge Commit Message + +1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase). +2. **Act**: Draft the final commit message: + - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md). + - **If merge or rebase**: use the default merge/rebase message. +3. **Act** (BLOCKING): Present the commit message to the developer for confirmation: + + > **Merge commit message:** + > + > ```text + > [#<story-id>] feat: <story description> + > + > - <summary of changes> + > - Tasks: T-1, T-2, ..., T-N + > + > Refs: #<story-id> + > ``` + > + > Confirm or edit? + +4. **Verify**: Developer confirms the commit message. + +### Step 4.3: Merge PR + +1. **Act**: Merge the PR with the confirmed commit message and the configured merge strategy. +2. **Verify**: PR merged and closed. + +### Step 4.4: Update Story & Parents + +1. **Act**: Update user story status to "Done" in the PM tool. +2. **Act**: Check parent epic — if ALL stories in the epic are Done, update epic status to "Done". +3. **Act**: Check parent initiative — if ALL epics in the initiative are Done, update initiative status to "Done". +4. **Verify**: Story and parent hierarchy updated recursively. + +## Output Format (merge) + +```text +STORY DONE: +├── Story: [#ID: Title] +├── PR: [#PR-number — merged] +├── Merge: [squash | merge | rebase] +├── Story: Done +├── Epic: [#ID — Done | In Progress (X/Y stories done)] +└── Initiative: [#ID — Done | In Progress (X/Y epics done)] +``` diff --git a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md index ec641925..b8a922a4 100644 --- a/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/review/SKILL.md @@ -142,36 +142,7 @@ This phase uses a **4-level graceful degradation cascade** depending on which op ### Step 3.2: Run Adoption Check -**Level 1** (/verify-adoption + /assess-stack): - -1. Compose `/verify-adoption` with `$scope = all`. -2. For each non-conformity: - - **Tech-stack**: compose `/assess-stack` (output-only — returns a proposal) → on developer approval, `/review` persists the entry via `/record-decision(content, target)` (the sole writer); on rejection → CHANGES-REQUESTED. - - **Architecture**: report to developer for resolution. Missing ADR → HALT via `/record-decision`. - - **Other** (security, coding-standards, infrastructure): report findings. -3. Record all results. - -**Level 2** (/verify-adoption only): - -1. Compose `/verify-adoption` with `$scope = all`. -2. For tech-stack non-conformities: report as findings for manual resolution. -3. For other non-conformities: same as Level 1. -4. Record results. - -**Level 3** (/assess-stack only): - -1. Inline check: scan PR diff for new dependencies not in [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md). -2. For unlisted dependencies: compose `/assess-stack` (output-only — returns a proposal) → on approval, `/review` persists via `/record-decision`; on rejection, flag as CHANGES-REQUESTED. -3. No broader adoption compliance check (security, architecture, etc. — covered partially by Phase 2). -4. Record results. - -**Level 4** (neither installed): - -1. Warn: - - > `/verify-adoption` and `/assess-stack` are not installed — skipping automated adoption compliance. Please manually verify code against adoption files. - -2. Move to Phase 4. +Run the procedure for the level determined in Step 3.1 — see [degradation-levels.md](degradation-levels.md) for the exact steps of each of the 4 levels. ### Step 3.3: Verify Adoption Results @@ -246,77 +217,9 @@ Based on compiled findings: 4. **Verify**: If "Merge now" selected → proceed to Phase 6. Otherwise → output and stop. -## Phase 6: Merge & Close (APPROVED only) - -### Step 6.1: Read Merge Strategy - -1. **Check**: Is merge strategy specified in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)? -2. **Skip**: If not specified, default to `squash`. -3. **Act**: Read the adopted merge strategy (`squash`, `merge`, or `rebase`). -4. **Verify**: Strategy determined. - -### Step 6.2: Prepare Merge Commit - -1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md): - - ```text - [#<story-id>] feat: <story description> - - - <summary of changes> - - Tasks: T-1, T-2, ..., T-N +## Phase 6: Merge & Close (APPROVED only, optional) - Refs: #<story-id> - ``` - -2. **Act** (BLOCKING): Present to reviewer for confirmation: - - > **Merge commit message:** - > - > ```text - > [commit message] - > ``` - > - > Confirm or edit? - -3. **Verify**: Reviewer confirms message. - -### Step 6.3: Merge PR - -1. **Act**: Merge the PR using the adopted strategy (per [github-implementation.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/github-implementation.md)): - - MCP-first: use `merge_pull_request` with `merge_method` and `commit_title` + `commit_message`. - - CLI fallback: `gh pr merge <number> --squash --subject "<title>" --body "<body>"`. -2. **Verify**: PR merged and closed. - -### Step 6.4: Update Story & Parent Cascade - -1. **Act**: Close the user story issue in the PM tool: - - MCP: `issue_write` with `method = update`, `state = closed`, `state_reason = completed`. - - CLI: `gh issue close <story-number> --reason completed`. -2. **Act**: Check parent epic — read sub-issues to determine if ALL stories are Done: - - MCP: `issue_read` with `method = get_sub_issues` on the epic. - - If all sub-issues closed → close the epic with `state_reason = completed`. - - If not all closed → leave epic open. -3. **Act**: Check parent initiative — same cascade logic: - - If all epics closed → close the initiative. - - If not all closed → leave initiative open. -4. **Verify**: Story closed. Epic and initiative updated if applicable. - -### Step 6.5: Branch Cleanup - -1. **Act**: Delete the feature branch (remote): - - CLI: `git push origin --delete <branch>`. -2. **Act**: Remove the story's checkpoint if one exists — `.pair/working/checkpoints/<story-id>.md` — so completed-story state does not linger as stale context (per the task-scoped cleanup rule; see `/checkpoint`). -3. **Verify**: Feature branch deleted and story checkpoint removed (if any existed). - -### Step 6.6: Post-Merge Manual Test Validation (Optional) - -1. **Check**: Is `/execute-manual-tests` installed? Does the project have a manual test suite (`qa/` directory)? -2. **Skip**: If skill not installed or no test suite found → skip. Log: "Manual test validation skipped — no suite or skill not installed." -3. **Act**: Compose `/execute-manual-tests` with `$scope = all`, `$priority = P0` (blockers only for fast validation). -4. **Verify**: If PASS → note in review output. If FAIL → do NOT revert the merge. Instead: - - Create a GitHub issue for each Critical/Major failure. - - Append manual test results as addendum to the review report (PR comment). - - Warn: "Post-merge manual tests found failures. Issues created." +Only reached when the reviewer picked "Merge now" in Step 5.4 — see [merge-and-cascade.md](merge-and-cascade.md) for the merge-strategy, merge-commit, merge, parent-cascade, branch-cleanup, and post-merge-manual-test steps (Steps 6.1–6.6) plus the completion output. ## Output Format @@ -335,18 +238,7 @@ REVIEW COMPLETE: └── Report: [Posted as PR comment] ``` -At merge (Phase 6): - -```text -STORY DONE: -├── Story: [#ID: Title] -├── PR: [#PR-number — merged] -├── Merge: [squash | merge | rebase] -├── Story: Done -├── Epic: [#ID — Done | In Progress (X/Y stories done)] -├── Initiative: [#ID — Done | In Progress (X/Y epics done)] -└── Manual Tests: [PASS | FAIL — N issues created | SKIPPED — no suite] -``` +At merge (Phase 6): see [merge-and-cascade.md](merge-and-cascade.md). ## HALT Conditions diff --git a/packages/knowledge-hub/dataset/.skills/process/review/degradation-levels.md b/packages/knowledge-hub/dataset/.skills/process/review/degradation-levels.md new file mode 100644 index 00000000..2eade5b3 --- /dev/null +++ b/packages/knowledge-hub/dataset/.skills/process/review/degradation-levels.md @@ -0,0 +1,34 @@ +# Phase 3, Step 3.2: Adoption Compliance Levels — Detail + +Disclosed from [SKILL.md](SKILL.md) Step 3.2. Run only the procedure matching the level determined in Step 3.1 — the other three never apply on this run. + +**Level 1** (/verify-adoption + /assess-stack): + +1. Compose `/verify-adoption` with `$scope = all`. +2. For each non-conformity: + - **Tech-stack**: compose `/assess-stack` (output-only — returns a proposal) → on developer approval, `/review` persists the entry via `/record-decision(content, target)` (the sole writer); on rejection → CHANGES-REQUESTED. + - **Architecture**: report to developer for resolution. Missing ADR → HALT via `/record-decision`. + - **Other** (security, coding-standards, infrastructure): report findings. +3. Record all results. + +**Level 2** (/verify-adoption only): + +1. Compose `/verify-adoption` with `$scope = all`. +2. For tech-stack non-conformities: report as findings for manual resolution. +3. For other non-conformities: same as Level 1. +4. Record results. + +**Level 3** (/assess-stack only): + +1. Inline check: scan PR diff for new dependencies not in [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md). +2. For unlisted dependencies: compose `/assess-stack` (output-only — returns a proposal) → on approval, `/review` persists via `/record-decision`; on rejection, flag as CHANGES-REQUESTED. +3. No broader adoption compliance check (security, architecture, etc. — covered partially by Phase 2). +4. Record results. + +**Level 4** (neither installed): + +1. Warn: + + > `/verify-adoption` and `/assess-stack` are not installed — skipping automated adoption compliance. Please manually verify code against adoption files. + +2. Move to Phase 4. diff --git a/packages/knowledge-hub/dataset/.skills/process/review/merge-and-cascade.md b/packages/knowledge-hub/dataset/.skills/process/review/merge-and-cascade.md new file mode 100644 index 00000000..4909df9b --- /dev/null +++ b/packages/knowledge-hub/dataset/.skills/process/review/merge-and-cascade.md @@ -0,0 +1,86 @@ +# Phase 6: Merge & Close — Detail + +Disclosed from [SKILL.md](SKILL.md) Phase 6 — only reached when the reviewer picked "Merge now" in Step 5.4. + +### Step 6.1: Read Merge Strategy + +1. **Check**: Is merge strategy specified in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)? +2. **Skip**: If not specified, default to `squash`. +3. **Act**: Read the adopted merge strategy (`squash`, `merge`, or `rebase`). +4. **Verify**: Strategy determined. + +### Step 6.2: Prepare Merge Commit + +1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md): + + ```text + [#<story-id>] feat: <story description> + + - <summary of changes> + - Tasks: T-1, T-2, ..., T-N + + Refs: #<story-id> + ``` + +2. **Act** (BLOCKING): Present to reviewer for confirmation: + + > **Merge commit message:** + > + > ```text + > [commit message] + > ``` + > + > Confirm or edit? + +3. **Verify**: Reviewer confirms message. + +### Step 6.3: Merge PR + +1. **Act**: Merge the PR using the adopted strategy (per [github-implementation.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/github-implementation.md)): + - MCP-first: use `merge_pull_request` with `merge_method` and `commit_title` + `commit_message`. + - CLI fallback: `gh pr merge <number> --squash --subject "<title>" --body "<body>"`. +2. **Verify**: PR merged and closed. + +### Step 6.4: Update Story & Parent Cascade + +1. **Act**: Close the user story issue in the PM tool: + - MCP: `issue_write` with `method = update`, `state = closed`, `state_reason = completed`. + - CLI: `gh issue close <story-number> --reason completed`. +2. **Act**: Check parent epic — read sub-issues to determine if ALL stories are Done: + - MCP: `issue_read` with `method = get_sub_issues` on the epic. + - If all sub-issues closed → close the epic with `state_reason = completed`. + - If not all closed → leave epic open. +3. **Act**: Check parent initiative — same cascade logic: + - If all epics closed → close the initiative. + - If not all closed → leave initiative open. +4. **Verify**: Story closed. Epic and initiative updated if applicable. + +### Step 6.5: Branch Cleanup + +1. **Act**: Delete the feature branch (remote): + - CLI: `git push origin --delete <branch>`. +2. **Act**: Remove the story's checkpoint if one exists — `.pair/working/checkpoints/<story-id>.md` — so completed-story state does not linger as stale context (per the task-scoped cleanup rule; see `/checkpoint`). +3. **Verify**: Feature branch deleted and story checkpoint removed (if any existed). + +### Step 6.6: Post-Merge Manual Test Validation (Optional) + +1. **Check**: Is `/execute-manual-tests` installed? Does the project have a manual test suite (`qa/` directory)? +2. **Skip**: If skill not installed or no test suite found → skip. Log: "Manual test validation skipped — no suite or skill not installed." +3. **Act**: Compose `/execute-manual-tests` with `$scope = all`, `$priority = P0` (blockers only for fast validation). +4. **Verify**: If PASS → note in review output. If FAIL → do NOT revert the merge. Instead: + - Create a GitHub issue for each Critical/Major failure. + - Append manual test results as addendum to the review report (PR comment). + - Warn: "Post-merge manual tests found failures. Issues created." + +## Output Format (merge) + +```text +STORY DONE: +├── Story: [#ID: Title] +├── PR: [#PR-number — merged] +├── Merge: [squash | merge | rebase] +├── Story: Done +├── Epic: [#ID — Done | In Progress (X/Y stories done)] +├── Initiative: [#ID — Done | In Progress (X/Y epics done)] +└── Manual Tests: [PASS | FAIL — N issues created | SKIPPED — no suite] +```