diff --git a/AGENTS.md b/AGENTS.md index a9fc8a76..4600e642 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,11 +139,11 @@ All work starts with a spec file under `docs/plans/`. Specs follow this format: **Never create, copy, or delete `LICENSE` files.** The maintainer manages these manually in every package and plugin directory. If a spec step or acceptance criterion requires a `LICENSE` file to exist, warn the maintainer to add it themselves before continuing. -## Agent skills +## Skill summary ### Issue tracker -Issues live as local markdown files under `docs/issues/`. See `docs/agents/issue-tracker.md`. +Issues live in GitHub Issues at `unic/unic-agents-plugins` (planned migration to Azure DevOps). See `docs/agents/issue-tracker.md`. ### Triage labels diff --git a/docs/issues/auto-format-config/01-config-module.md b/docs/issues/auto-format-config/01-config-module.md deleted file mode 100644 index 76b08e66..00000000 --- a/docs/issues/auto-format-config/01-config-module.md +++ /dev/null @@ -1,39 +0,0 @@ -# Extract `lib/config.mjs` with `DEFAULTS`, `loadConfig`, and tests - -**Status:** closed -**Category:** refactor - -## Parent - -`docs/issues/auto-format-config/PRD.md` - -## What to build - -Create `scripts/lib/config.mjs` and `scripts/lib/config.test.mjs`. - -`config.mjs` exports: - -- `DEFAULTS` — the `ProjectConfig` constant currently at lines 25–57 of `format-hook.mjs` -- `loadConfig(projectDir: string) → ProjectConfig` — the merge logic currently in - `loadProjectConfig()`, with `PROJECT_DIR` replaced by the `projectDir` parameter - -`config.test.mjs` covers ten scenarios via real temp directories (see PRD for the full list). - -`package.json#scripts.test` is updated to include `scripts/lib/config.test.mjs`. - -`format-hook.mjs` is not modified in this issue. - -Full implementation details in `apps/claude-code/auto-format/docs/plans/29-config-module.md`. - -## Acceptance criteria - -- [ ] `scripts/lib/config.mjs` exports `DEFAULTS` and `loadConfig` -- [ ] `loadConfig` takes `projectDir: string`, does not close over any module-level constant -- [ ] All 10 tests in `scripts/lib/config.test.mjs` pass -- [ ] `pnpm test` passes (existing tests unaffected) -- [ ] `pnpm typecheck` passes -- [ ] `format-hook.mjs` is not modified - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/auto-format-config/02-wire-up.md b/docs/issues/auto-format-config/02-wire-up.md deleted file mode 100644 index f14b0eab..00000000 --- a/docs/issues/auto-format-config/02-wire-up.md +++ /dev/null @@ -1,31 +0,0 @@ -# Update `format-hook.mjs` to use `lib/config.mjs` - -**Status:** closed -**Category:** refactor - -## Parent - -`docs/issues/auto-format-config/PRD.md` - -## What to build - -Update `scripts/format-hook.mjs` to import `loadConfig` from `./lib/config.mjs` and remove the -now-moved code: - -1. Add `import { loadConfig } from './lib/config.mjs'` -2. Delete the `DEFAULTS` constant (lines 25–57) -3. Delete the `loadProjectConfig` function (lines 65–93) -4. Replace `const CONFIG = loadProjectConfig()` with `const CONFIG = loadConfig(PROJECT_DIR)` - -External behaviour is identical. `tests/format-hook.test.mjs` must pass without modification. - -## Acceptance criteria - -- [ ] `grep -n "const DEFAULTS\|function loadProjectConfig" scripts/format-hook.mjs` → 0 matches -- [ ] `grep -n "loadConfig" scripts/format-hook.mjs` → match on import and call site -- [ ] `pnpm test` passes without any changes to `tests/format-hook.test.mjs` -- [ ] `pnpm typecheck` passes - -## Blocked by - -01-config-module diff --git a/docs/issues/auto-format-config/03-version-bump.md b/docs/issues/auto-format-config/03-version-bump.md deleted file mode 100644 index 5959abb7..00000000 --- a/docs/issues/auto-format-config/03-version-bump.md +++ /dev/null @@ -1,28 +0,0 @@ -# Version bump and CHANGELOG entry - -**Status:** closed -**Category:** release - -## Parent - -`docs/issues/auto-format-config/PRD.md` - -## What to build - -Bump the auto-format plugin version and add a dated CHANGELOG entry. - -```sh -pnpm --filter auto-format bump patch -``` - -CHANGELOG entry should describe the config loading extraction as an internal refactor. - -## Acceptance criteria - -- [ ] `pnpm --filter auto-format verify:changelog` passes -- [ ] CHANGELOG entry present for the new version -- [ ] `plugin.json` and `marketplace.json` versions are in sync - -## Blocked by - -02-wire-up diff --git a/docs/issues/auto-format-runners/01-formatter-descriptor-type.md b/docs/issues/auto-format-runners/01-formatter-descriptor-type.md deleted file mode 100644 index b1848a8c..00000000 --- a/docs/issues/auto-format-runners/01-formatter-descriptor-type.md +++ /dev/null @@ -1,39 +0,0 @@ -# Add `FormatterDescriptor` typedef to `lib/types.mjs` - -**Status:** closed -**Category:** refactor - -## Parent - -`docs/issues/auto-format-runners/PRD.md` - -## What to build - -Add a `FormatterDescriptor` JSDoc typedef to `scripts/lib/types.mjs`, after the existing -`ProjectConfig` definition: - -```js -/** - * Descriptor for a single formatter invocation. - * - * @typedef {{ - * name: string, - * bin: string, - * args: (filePath: string) => string[], - * warnIfMissing?: boolean, - * toleratedStatuses?: number[], - * }} FormatterDescriptor - */ -``` - -No runtime code changes. No other files touched. - -## Acceptance criteria - -- [ ] `grep -n "FormatterDescriptor" scripts/lib/types.mjs` → match -- [ ] All five fields present with correct types -- [ ] `pnpm typecheck` passes - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/auto-format-runners/02-runner-module.md b/docs/issues/auto-format-runners/02-runner-module.md deleted file mode 100644 index 975faed7..00000000 --- a/docs/issues/auto-format-runners/02-runner-module.md +++ /dev/null @@ -1,38 +0,0 @@ -# Extract `lib/runners.mjs` with `runFormatter` and tests - -**Status:** closed -**Category:** refactor - -## Parent - -`docs/issues/auto-format-runners/PRD.md` - -## What to build - -Create two new files: `scripts/lib/runners.mjs` and `scripts/lib/runners.test.mjs`. - -`runners.mjs` exports a single `runFormatter(descriptor, filePath, cwd, timeoutMs)` function that -owns the subprocess contract — binary existence check, `spawnSync` invocation, SIGTERM/null -detection, tolerated-exit-code filtering, stderr reporting. It imports `FormatterDescriptor` from -`./types.mjs` via JSDoc `@import`. It has no knowledge of Prettier, ESLint, or Biome. - -`runners.test.mjs` tests the contract with real child processes (stub Node.js scripts in temp -directories). Six tests covering: missing binary silent, missing binary warn, timeout, tolerated -status, non-tolerated status, args passed correctly. - -`package.json#scripts.test` is updated to include `scripts/lib/runners.test.mjs` so `pnpm test` -covers the new file. - -Full implementation details in `apps/claude-code/auto-format/docs/plans/26-runner-module.md`. - -## Acceptance criteria - -- [ ] `scripts/lib/runners.mjs` exists and exports `runFormatter` -- [ ] All 6 tests in `scripts/lib/runners.test.mjs` pass -- [ ] `pnpm test` passes (existing tests unaffected) -- [ ] `pnpm typecheck` passes -- [ ] `format-hook.mjs` is not modified in this issue - -## Blocked by - -01-formatter-descriptor-type diff --git a/docs/issues/auto-format-runners/03-replace-runner-functions.md b/docs/issues/auto-format-runners/03-replace-runner-functions.md deleted file mode 100644 index 48c1530b..00000000 --- a/docs/issues/auto-format-runners/03-replace-runner-functions.md +++ /dev/null @@ -1,38 +0,0 @@ -# Replace runner functions with descriptors in `format-hook.mjs` - -**Status:** closed -**Category:** refactor - -## Parent - -`docs/issues/auto-format-runners/PRD.md` - -## What to build - -Replace the three inline runner functions (`runPrettier`, `runEslint`, `runBiome`) in -`scripts/format-hook.mjs` with three `FormatterDescriptor` constants and a dispatch through -`runFormatter` from `lib/runners.mjs`. - -Changes: - -1. Add `import { runFormatter } from './lib/runners.mjs'` -2. Add `/** @import { FormatterDescriptor } from './lib/types.mjs' */` type-import tag -3. Define `PRETTIER_DESCRIPTOR`, `ESLINT_DESCRIPTOR`, `BIOME_DESCRIPTOR` constants -4. Update `main()` dispatch to bind `cwd` and `timeoutMs` once and call `runFormatter` -5. Delete `runPrettier`, `runEslint`, `runBiome` functions - -External behaviour is identical. `tests/format-hook.test.mjs` must pass without modification. - -Full implementation details in -`apps/claude-code/auto-format/docs/plans/27-replace-runner-functions.md`. - -## Acceptance criteria - -- [ ] `grep -n "function runPrettier\|function runEslint\|function runBiome" scripts/format-hook.mjs` → 0 matches -- [ ] `grep -n "PRETTIER_DESCRIPTOR\|ESLINT_DESCRIPTOR\|BIOME_DESCRIPTOR" scripts/format-hook.mjs` → 3 matches -- [ ] `pnpm test` passes without any changes to `tests/format-hook.test.mjs` -- [ ] `pnpm typecheck` passes - -## Blocked by - -02-runner-module diff --git a/docs/issues/auto-format-runners/04-version-bump.md b/docs/issues/auto-format-runners/04-version-bump.md deleted file mode 100644 index be38de12..00000000 --- a/docs/issues/auto-format-runners/04-version-bump.md +++ /dev/null @@ -1,28 +0,0 @@ -# Version bump and CHANGELOG entry - -**Status:** closed -**Category:** release - -## Parent - -`docs/issues/auto-format-runners/PRD.md` - -## What to build - -Bump the auto-format plugin version and add a dated CHANGELOG entry. - -```sh -pnpm --filter auto-format bump patch -``` - -CHANGELOG entry should describe the formatter runner extraction as an internal refactor. - -## Acceptance criteria - -- [ ] `pnpm --filter auto-format verify:changelog` passes -- [ ] CHANGELOG entry present for the new version -- [ ] `plugin.json` and `marketplace.json` versions are in sync - -## Blocked by - -03-replace-runner-functions diff --git a/docs/issues/feature-runner/01-skill-scaffold.md b/docs/issues/feature-runner/01-skill-scaffold.md deleted file mode 100644 index fdd896c5..00000000 --- a/docs/issues/feature-runner/01-skill-scaffold.md +++ /dev/null @@ -1,29 +0,0 @@ -# Skill scaffold and minimal execution loop - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Create `.claude/skills/implement-feature/SKILL.md`. Implement the full happy path for a named-slug invocation on a feature with one or more issues: create a `feature/afk/` worktree from `develop`, read all `NN-*.md` files in the feature directory, filter to those with `Status: ready-for-agent` (skip `resolved` and `closed`), sort numerically, invoke `/tdd` as a non-interactive sub-agent for each issue in order with the issue file and PRD as context, mark each issue `Status: resolved` on successful completion. - -All file and git operations must use Claude tool calls — no shell scripts, no POSIX paths. This is the tracer bullet: the entire end-to-end happy path without failure handling, PR creation, or progress output. - -## Acceptance criteria - -- [ ] `.claude/skills/implement-feature/SKILL.md` exists and is invocable as `/implement-feature ` -- [ ] Running `/implement-feature ` creates a `feature/afk/` branch and worktree from `develop` -- [ ] Only issues at `Status: ready-for-agent` are processed; `resolved` and `closed` issues are skipped -- [ ] Each issue is handed to `/tdd` as a non-interactive sub-agent invocation with the issue file and PRD as context -- [ ] Each issue file is updated to `Status: resolved` after successful `/tdd` completion -- [ ] All file and git operations use Claude tool calls, not shell scripts (cross-platform requirement) - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/feature-runner/02-failure-handling.md b/docs/issues/feature-runner/02-failure-handling.md deleted file mode 100644 index f3fde0a0..00000000 --- a/docs/issues/feature-runner/02-failure-handling.md +++ /dev/null @@ -1,26 +0,0 @@ -# Failure handling - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Extend the skill to handle `/tdd` sub-agent failures. When `/tdd` fails on an issue, append a failure note to that issue file under a `## Comments` heading, leave the issue at `Status: ready-for-agent`, stop the runner, and leave the worktree in place for inspection. Subsequent issues in the feature must not run — they could inherit a broken foundation. - -## Acceptance criteria - -- [ ] When `/tdd` fails on an issue, a failure note is appended to that issue file under `## Comments` (prefixed with the AI-generated disclaimer) -- [ ] The failing issue remains at `Status: ready-for-agent` after the failure note is appended -- [ ] The runner stops after the first failure; no subsequent issues in the feature are executed -- [ ] The worktree is left in place (not removed) on failure, for inspection -- [ ] The runner surfaces a clear failure message to the user naming which issue failed - -## Blocked by - -`docs/issues/feature-runner/01-skill-scaffold.md` diff --git a/docs/issues/feature-runner/03-pr-creation.md b/docs/issues/feature-runner/03-pr-creation.md deleted file mode 100644 index 84c03cbd..00000000 --- a/docs/issues/feature-runner/03-pr-creation.md +++ /dev/null @@ -1,28 +0,0 @@ -# PR creation and worktree cleanup - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Extend the skill so that when all issues in a feature are `resolved`, it opens a pull request targeting `develop` using the `gh` CLI. The PR title is derived from the feature slug and the PRD's `title` frontmatter field. The PR body references the feature PRD and lists all resolved issues. After the PR is opened successfully, the worktree is removed. - -Blocked on failure handling (02) so the runner never reaches PR creation when an issue has failed. - -## Acceptance criteria - -- [ ] When all issues in the feature are `resolved`, `gh pr create` is called targeting `develop` -- [ ] PR title is derived from the feature slug and the PRD's `title` frontmatter field -- [ ] PR body includes a reference to `docs/issues//PRD.md` and a list of all resolved issues -- [ ] The worktree is removed after the PR is opened successfully -- [ ] No PR is opened if the runner stopped due to a `/tdd` failure (failure handling from 02 prevents this) - -## Blocked by - -`docs/issues/feature-runner/02-failure-handling.md` diff --git a/docs/issues/feature-runner/04-progress-reporting.md b/docs/issues/feature-runner/04-progress-reporting.md deleted file mode 100644 index 6f3ce247..00000000 --- a/docs/issues/feature-runner/04-progress-reporting.md +++ /dev/null @@ -1,24 +0,0 @@ -# Progress reporting - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Extend the skill to emit a progress line before each `/tdd` invocation so the user can judge when to check back. The line should name the current issue number, the total count, and the issue title. - -## Acceptance criteria - -- [ ] Before each `/tdd` invocation, the runner outputs a line in the format: `Implementing issue N of M: ` -- [ ] N counts from 1 and M is the total number of `ready-for-agent` issues in the feature (excluding already `resolved` or `closed` ones at run start) -- [ ] The progress line is emitted regardless of whether failure handling or PR creation are in place - -## Blocked by - -`docs/issues/feature-runner/01-skill-scaffold.md` diff --git a/docs/issues/feature-runner/05-full-context-bundle.md b/docs/issues/feature-runner/05-full-context-bundle.md deleted file mode 100644 index 5b9b26c9..00000000 --- a/docs/issues/feature-runner/05-full-context-bundle.md +++ /dev/null @@ -1,27 +0,0 @@ -# Full context bundle for /tdd sub-agent invocations - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Extend the `/tdd` sub-agent invocation to use the full context bundle defined in ADR-0027, replacing the minimal bundle (issue file + PRD only) from the scaffold slice. The bundle adds: all sibling issue files in the feature directory, domain-scoped `CONTEXT.md`, domain-scoped ADRs, and the last 5 git commits. - -Scope is inferred by scanning the PRD for `apps/claude-code/` path references. If found, inject that plugin's `docs/adr/` and `CONTEXT.md`. If not found, inject the root `docs/adr/` and root `CONTEXT.md`. - -## Acceptance criteria - -- [ ] Each `/tdd` invocation receives the full bundle: issue file, PRD, all sibling issue files, scoped `CONTEXT.md`, scoped ADRs, last 5 git commits -- [ ] For a feature whose PRD references paths under `apps/claude-code//`, the plugin's `docs/adr/` and `CONTEXT.md` are injected -- [ ] For a feature whose PRD does not reference any `apps/claude-code//` path, the root `docs/adr/` and root `CONTEXT.md` are injected -- [ ] Root ADRs are not injected into plugin feature runs - -## Blocked by - -`docs/issues/feature-runner/01-skill-scaffold.md` diff --git a/docs/issues/feature-runner/06-dependency-graph.md b/docs/issues/feature-runner/06-dependency-graph.md deleted file mode 100644 index 8de3d229..00000000 --- a/docs/issues/feature-runner/06-dependency-graph.md +++ /dev/null @@ -1,28 +0,0 @@ -# Dependency graph and topological ordering - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Extend the skill to parse `## Blocked by` references from all issue files in the feature, build a topological execution order, and replace the numerical sort from the scaffold slice. If any `## Blocked by` reference conflicts with numerical filename order, halt with a descriptive error before executing any issue. Issues with `## Blocked by: None` (or equivalent) have no predecessors. - -See ADR-0028 for the rationale: `## Blocked by` is the canonical dependency signal; numerical order is a UX convenience, not an execution contract. - -## Acceptance criteria - -- [ ] `## Blocked by` references are parsed from all `NN-*.md` files in the feature directory before execution begins -- [ ] Issues are executed in topological order derived from `## Blocked by`, not numerical filename order -- [ ] Issues with `## Blocked by: None` or no `## Blocked by` section have no predecessors in the graph -- [ ] If a `## Blocked by` reference points to an issue with a higher number than the blocking issue (conflict with numerical order), the runner halts with a descriptive error before executing any issue -- [ ] The error message names the conflicting issues so the developer can resolve the ordering - -## Blocked by - -`docs/issues/feature-runner/01-skill-scaffold.md` diff --git a/docs/issues/feature-runner/07-auto-selection.md b/docs/issues/feature-runner/07-auto-selection.md deleted file mode 100644 index 91102879..00000000 --- a/docs/issues/feature-runner/07-auto-selection.md +++ /dev/null @@ -1,26 +0,0 @@ -# Auto-selection and LOOP_COMPLETE - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Extend the skill to handle no-argument invocation. When invoked without a slug, scan `docs/issues/` for features where every `NN-*.md` file is at `Status: ready-for-agent`. Select the first such feature alphabetically and run it. When no qualifying feature exists, emit `LOOP_COMPLETE` on its own line and exit cleanly. This makes `/loop /implement-feature` composable for overnight queue draining — the `/loop` skill catches `LOOP_COMPLETE` and terminates. - -## Acceptance criteria - -- [ ] Running `/implement-feature` with no argument scans `docs/issues/` and selects the first feature (alphabetically by slug) where all `NN-*.md` files are `Status: ready-for-agent` -- [ ] The selected feature is then executed using the same logic as the named-slug path -- [ ] When no qualifying feature exists, the skill outputs `LOOP_COMPLETE` on its own line and exits cleanly with no error -- [ ] Running `/loop /implement-feature` terminates cleanly after `LOOP_COMPLETE` is emitted -- [ ] Features with a mix of `ready-for-agent` and `resolved`/`closed` issues are not selected (partial features are skipped) - -## Blocked by - -`docs/issues/feature-runner/01-skill-scaffold.md` diff --git a/docs/issues/feature-runner/08-feature-runner-docs.md b/docs/issues/feature-runner/08-feature-runner-docs.md deleted file mode 100644 index cd5029a2..00000000 --- a/docs/issues/feature-runner/08-feature-runner-docs.md +++ /dev/null @@ -1,38 +0,0 @@ -# `docs/agents/feature-runner.md` reference document - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Write `docs/agents/feature-runner.md` — the agent reference document for the Feature Runner. It must describe the full lifecycle as implemented (not as planned), and document the historical cleanup convention. It must not duplicate content from `docs/agents/issue-tracker.md`, which is overwritten by `setup-matt-pocock-skills`. - -The document should cover: - -- The Feature Runner lifecycle: feature selected → worktree created → issues implemented in topological order → PR opened → issues marked `closed` on merge -- The context bundle injected into each `/tdd` invocation (what it contains and why) -- The `## Blocked by` sequencing rule and what happens on conflict -- The historical cleanup convention: when a Spec in `docs/plans/` is marked `done` and a corresponding `docs/issues//` folder exists, manually mark all issue files `closed` and append a note referencing the Spec - -## Acceptance criteria - -- [ ] `docs/agents/feature-runner.md` exists -- [ ] It documents the full Feature Runner lifecycle with all phases named correctly using domain vocabulary from `CONTEXT.md` -- [ ] It documents the context bundle contents (issue, PRD, siblings, scoped CONTEXT.md, scoped ADRs, recent commits) -- [ ] It documents the `## Blocked by` sequencing rule and conflict behaviour -- [ ] It documents the historical cleanup convention with a concrete example of the note to append -- [ ] It does not duplicate content from `docs/agents/issue-tracker.md` - -## Blocked by - -- `docs/issues/feature-runner/03-pr-creation.md` -- `docs/issues/feature-runner/04-progress-reporting.md` -- `docs/issues/feature-runner/05-full-context-bundle.md` -- `docs/issues/feature-runner/06-dependency-graph.md` -- `docs/issues/feature-runner/07-auto-selection.md` diff --git a/docs/issues/feature-runner/09-retry-on-tdd-failure.md b/docs/issues/feature-runner/09-retry-on-tdd-failure.md deleted file mode 100644 index 75ef81fc..00000000 --- a/docs/issues/feature-runner/09-retry-on-tdd-failure.md +++ /dev/null @@ -1,21 +0,0 @@ -# Retry mechanism on /tdd failure - -**Status:** rejected -**Category:** enhancement - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## Summary - -Add a retry mechanism to `implement-feature` so the runner tries the `/tdd` invocation again before stopping on failure. - -## Rejection reasoning - -Grilled 2026-05-09. Both failure modes that could trigger a retry are not worth automating: - -- **Agent tool errors** (safety classifier, quota exceeded) have unpredictable resolution windows (minutes to hours). An immediate or short-delay retry is a coin flip and provides no reliable value. -- **Sub-agent gave up** — `/tdd` already has a built-in red-green loop that exhausts retries internally. If it exits with failure, a second invocation hits the same wall. This is a signal for human review, not automation. - -The existing "stop + note + leave worktree" behaviour from issue 02 is already the correct response for every failure mode that can occur in practice. diff --git a/docs/issues/feature-runner/10-references-split.md b/docs/issues/feature-runner/10-references-split.md deleted file mode 100644 index a03ccffd..00000000 --- a/docs/issues/feature-runner/10-references-split.md +++ /dev/null @@ -1,72 +0,0 @@ -# Extract protocol strings to references/runner-output-formats.md - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Create `.claude/skills/implement-feature/references/runner-output-formats.md` containing all verbatim output strings that the runner emits or embeds. Remove those strings from `SKILL.md` and replace each with a reference to the file by name. - -The verbatim strings to extract are: - -1. **Progress line** — `Implementing issue N of M: ` -2. **Dependency conflict error block** — the four-line `Feature Runner error: dependency conflict detected.` message (including the two indented detail lines and the resolution instruction) -3. **Failure note** — the full `## Comments` markdown block appended to a failing issue file (including the blockquote attribution and the bold `Feature Runner failure —` sentence) -4. **PR body template** — the heredoc body passed to `gh pr create` (Feature section, Resolved issues list, and the 🤖 attribution line) -5. **LOOP_COMPLETE signal** — the bare `LOOP_COMPLETE` string with a note that it must appear on its own line - -Each entry in `references/runner-output-formats.md` should have a short heading, the exact string (in a fenced code block where multiline), and one sentence explaining when the runner emits it. - -`SKILL.md` procedural steps should reference the file by name rather than repeating the strings inline, reducing SKILL.md by approximately 50 lines. - -## Acceptance criteria - -- [ ] `.claude/skills/implement-feature/references/runner-output-formats.md` exists and contains all five strings listed above -- [ ] Each entry has a heading, a fenced code block with the exact string, and a one-sentence context note -- [ ] `SKILL.md` no longer contains the verbatim strings inline; each step references `references/runner-output-formats.md` by name instead -- [ ] The procedural logic in `SKILL.md` is unchanged — only the literal strings move -- [ ] `SKILL.md` line count is reduced to approximately 160 lines or fewer - -## Blocked by - -`docs/issues/feature-runner/01-skill-scaffold.md` - -## Comments - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** enhancement -**Summary:** Extract verbatim runner output strings from `implement-feature` SKILL.md into a dedicated `references/runner-output-formats.md` file. - -**Current behavior:** -Five verbatim output strings are embedded inline inside the procedural steps of the `implement-feature` skill: the progress line, the dependency conflict error block, the failure note markdown block, the PR body heredoc, and the LOOP_COMPLETE signal. Updating any of these strings requires editing the step prose rather than a named reference file. - -**Desired behavior:** -A `references/runner-output-formats.md` file exists inside the `implement-feature` skill directory alongside `SKILL.md`. It contains all five strings, each under a short heading, in a fenced code block, with one sentence explaining when the runner emits it. The procedural steps in `SKILL.md` reference the file by name instead of repeating the strings inline. Procedural logic is unchanged — only the literal strings move. - -**Key interfaces:** - -- The `implement-feature` skill directory structure — gains a `references/` subdirectory, consistent with the `new-plugin` and `verify-spec` skills which also use `references/` -- `references/runner-output-formats.md` — new file; its five sections must exactly match the strings currently in SKILL.md (no editorial changes to the strings themselves) - -**Acceptance criteria:** - -- [ ] `references/runner-output-formats.md` exists in the `implement-feature` skill directory and contains all five strings listed in `## What to build` -- [ ] Each entry has a heading, a fenced code block with the exact string, and a one-sentence context note -- [ ] `SKILL.md` no longer contains the verbatim strings inline; each relevant step references `references/runner-output-formats.md` by name -- [ ] The procedural logic in `SKILL.md` is unchanged — only the literal strings move -- [ ] `SKILL.md` line count is reduced to approximately 160 lines or fewer - -**Out of scope:** - -- Changing the content of any output string (this is a structural move only) -- Adding new output strings or removing existing ones -- Updating `docs/agents/feature-runner.md` (it already documents the strings in prose) diff --git a/docs/issues/feature-runner/11-quick-start.md b/docs/issues/feature-runner/11-quick-start.md deleted file mode 100644 index 31656b3b..00000000 --- a/docs/issues/feature-runner/11-quick-start.md +++ /dev/null @@ -1,67 +0,0 @@ -# Add Quick start section to SKILL.md - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Add a `## Quick start` section near the top of `.claude/skills/implement-feature/SKILL.md`, immediately after the opening paragraph and before `## Steps`. The section should show the three realistic invocation patterns as annotated bullet points, so a user can orient themselves before reading the full step-by-step. - -The three patterns: - -1. **Named run** — `/implement-feature pr-review-doc-context-enrichment` — targets a specific feature slug directly -2. **Auto-select** — `/implement-feature` with no argument — scans `docs/issues/` and picks the first fully `ready-for-agent` feature alphabetically -3. **Overnight loop** — `/loop /implement-feature` — composes with the `/loop` skill to drain the queue unattended; the runner emits `LOOP_COMPLETE` when no qualifying feature remains, which terminates the loop - -No separate `EXAMPLES.md` file is needed — `docs/agents/feature-runner.md` already covers lifecycle and mechanics in prose. - -## Acceptance criteria - -- [ ] A `## Quick start` section exists in `SKILL.md` between the opening paragraph and `## Steps` -- [ ] The section contains exactly the three invocation patterns listed above, each as a bullet with a concrete example command and a one-line description -- [ ] No new files are created (no `EXAMPLES.md`) -- [ ] The rest of `SKILL.md` is unchanged - -## Blocked by - -`docs/issues/feature-runner/01-skill-scaffold.md` - -## Comments - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** enhancement -**Summary:** Add a `## Quick start` section to the `implement-feature` skill so users can orient themselves before reading the full 7-step workflow. - -**Current behavior:** -The `implement-feature` SKILL.md opens with a one-paragraph description and jumps directly into `## Steps`. A user invoking the skill for the first time must read all 7 steps to understand the three basic usage patterns. - -**Desired behavior:** -A `## Quick start` section appears between the opening paragraph and `## Steps`. It contains exactly three bullet points — one per invocation pattern — each with a concrete example command and a one-line description of what it does. No new files are created. - -**Key interfaces:** - -- The `implement-feature` SKILL.md top-level structure: frontmatter → opening paragraph → `## Quick start` → `## Steps` -- The three invocation patterns (content defined in `## What to build`) must match the behavior already implemented in Step 0 of SKILL.md - -**Acceptance criteria:** - -- [ ] A `## Quick start` section exists in SKILL.md between the opening paragraph and `## Steps` -- [ ] The section contains exactly three bullet points covering: named run, auto-select, and overnight loop via `/loop` -- [ ] Each bullet includes a concrete example command and a one-line description -- [ ] No new files are created (no `EXAMPLES.md` or other companion files) -- [ ] All other sections of SKILL.md are unchanged - -**Out of scope:** - -- Changing any step logic or the 7-step structure -- Creating an `EXAMPLES.md` file -- Updating `docs/agents/feature-runner.md` diff --git a/docs/issues/feature-runner/12-heredoc-note-in-references.md b/docs/issues/feature-runner/12-heredoc-note-in-references.md deleted file mode 100644 index 2c448ca9..00000000 --- a/docs/issues/feature-runner/12-heredoc-note-in-references.md +++ /dev/null @@ -1,74 +0,0 @@ -# Add heredoc wrapping note to PR body template in runner-output-formats.md - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -The PR body template in `references/runner-output-formats.md` shows the multiline body content but gives no instruction on how to pass it to `gh pr create`. Step 7 of SKILL.md currently shows `--body ""` as a placeholder, but an agent executing the step has no guidance on quoting a multiline string for the `--body` flag. - -Add a "how to use" note directly under the PR body template in `references/runner-output-formats.md` showing the bash heredoc wrapper: - -``` -Pass via a bash heredoc: - -gh pr create \ - --base develop \ - --title "feat(): " \ - --body "$(cat <<'EOF' - -EOF -)" -``` - -No changes to SKILL.md are needed — step 7 already directs the agent to `references/runner-output-formats.md` for the body template. - -## Acceptance criteria - -- [ ] The PR body template section in `references/runner-output-formats.md` includes a note explaining that the body must be passed via a bash heredoc -- [ ] The note shows a complete, correct `gh pr create` command with the heredoc wrapper -- [ ] SKILL.md step 7 is unchanged -- [ ] No other sections of `references/runner-output-formats.md` are modified - -## Blocked by - -`docs/issues/feature-runner/10-references-split.md` - -## Comments - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** enhancement -**Summary:** Add heredoc wrapping instruction to the PR body template in `references/runner-output-formats.md` so agents know how to pass multiline content to `gh pr create`. - -**Current behavior:** -The PR body template section shows the body content in a fenced code block but gives no instruction on how to embed it in a `gh pr create` call. Step 7 of SKILL.md shows `--body ""` as a placeholder — an agent executing this step has no guidance on quoting a multiline string for `--body`. - -**Desired behavior:** -The PR body template section in `references/runner-output-formats.md` includes a follow-on note showing the complete `gh pr create` command with the body content wrapped in a bash heredoc (`--body "$(cat <<'EOF' ... EOF)"`). An agent reading the section finds both the template content and the exact quoting pattern needed to use it. - -**Key interfaces:** - -- The PR body template section in `references/runner-output-formats.md` — gains a "how to use" note after the fenced code block -- SKILL.md step 7 — unchanged; it already directs the agent to the references file - -**Acceptance criteria:** - -- [ ] The PR body template section in `references/runner-output-formats.md` includes a note explaining that the body must be passed via a bash heredoc -- [ ] The note shows a complete, correct `gh pr create` command with the heredoc wrapper -- [ ] SKILL.md step 7 is unchanged -- [ ] No other sections of `references/runner-output-formats.md` are modified - -**Out of scope:** - -- Changing the PR body template content itself -- Adding cross-platform alternatives to the heredoc (the cross-platform concern pre-dates this issue and is not being addressed here) -- Modifying SKILL.md diff --git a/docs/issues/feature-runner/13-tdd-prompt-template-in-references.md b/docs/issues/feature-runner/13-tdd-prompt-template-in-references.md deleted file mode 100644 index 34a59187..00000000 --- a/docs/issues/feature-runner/13-tdd-prompt-template-in-references.md +++ /dev/null @@ -1,91 +0,0 @@ -# Extract /tdd prompt template to references/tdd-prompt-template.md - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -The 23-line `/tdd` prompt template in step 4 of SKILL.md is the last large inline block. It is a structured template (not a verbatim output string) that the agent fills in dynamically at runtime, but its presence mid-step interrupts the prose flow and keeps SKILL.md at 177 lines — above the ≤160 acceptance criterion set in issue 10. - -Create `references/tdd-prompt-template.md` containing the full prompt template. Update step 4 of SKILL.md to reference the file by name instead of repeating the template inline. - -The template to extract (currently in step 4 of SKILL.md, inside a fenced code block): - -``` -You are running /tdd in AFK mode. The planning phase is complete — do not ask for confirmation. Use the acceptance criteria below as the pre-approved plan and proceed directly to the red→green→refactor loop. - -Working directory: .claude/worktrees/ - ---- ISSUE --- - - ---- PRD (parent context) --- -/PRD.md> - ---- SIBLING ISSUES --- - - ---- CONTEXT.md --- - - ---- ADRs --- - - ---- RECENT COMMITS (last 5) --- - -``` - -The new file should have a short heading, the template in a fenced code block, and a one-sentence note explaining that placeholders are filled at runtime. - -Step 4 in SKILL.md should replace the fenced block with: "Construct the prompt using the template in `references/tdd-prompt-template.md`, substituting all `` values at runtime." - -## Acceptance criteria - -- [ ] `references/tdd-prompt-template.md` exists in the `implement-feature` skill directory and contains the full prompt template -- [ ] The template in the new file is identical to the template currently in SKILL.md step 4 (no content changes) -- [ ] Step 4 of SKILL.md no longer contains the inline fenced block; it references `references/tdd-prompt-template.md` by name -- [ ] SKILL.md line count drops to approximately 154 lines or fewer -- [ ] No other steps in SKILL.md are modified - -## Blocked by - -`docs/issues/feature-runner/10-references-split.md` - -## Comments - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** enhancement -**Summary:** Extract the 23-line `/tdd` prompt template from SKILL.md step 4 into `references/tdd-prompt-template.md` to bring SKILL.md under the ≤160 line target. - -**Current behavior:** -Step 4 of the `implement-feature` skill contains a 23-line fenced code block with the `/tdd` prompt template inline. SKILL.md is 177 lines — above the ≤160 target set in issue 10. The template is the last remaining large inline block. - -**Desired behavior:** -`references/tdd-prompt-template.md` exists alongside `references/runner-output-formats.md` in the `implement-feature` skill directory. It contains the prompt template (with a heading, fenced code block, and one-sentence note about runtime substitution). Step 4 of SKILL.md replaces the inline block with a single sentence referencing the file by name. SKILL.md drops to approximately 154 lines. - -**Key interfaces:** - -- `references/tdd-prompt-template.md` — new file; template content must be identical to what is currently inline in SKILL.md step 4 -- SKILL.md step 4 — loses the inline fenced block, gains a one-sentence reference to the new file; all other prose in step 4 is unchanged - -**Acceptance criteria:** - -- [ ] `references/tdd-prompt-template.md` exists and contains the full prompt template, identical to the current inline version -- [ ] Step 4 of SKILL.md references `references/tdd-prompt-template.md` by name instead of repeating the template -- [ ] SKILL.md line count drops to approximately 154 lines or fewer -- [ ] No other steps in SKILL.md are modified - -**Out of scope:** - -- Changing the prompt template content (structural move only) -- Modifying `references/runner-output-formats.md` -- Updating `docs/agents/feature-runner.md` or ADR 0029 diff --git a/docs/issues/feature-runner/14-smarter-auto-select.md b/docs/issues/feature-runner/14-smarter-auto-select.md deleted file mode 100644 index 99069b22..00000000 --- a/docs/issues/feature-runner/14-smarter-auto-select.md +++ /dev/null @@ -1,62 +0,0 @@ -# Smarter auto-select: resume partial features and reuse existing worktrees - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Relax the auto-selection qualification rule so that partially-completed features (e.g. after a failure mid-run) are included alongside fresh ones. Update the worktree creation step to reuse an existing worktree rather than failing or recreating it. - -### Auto-select qualification (Step 0) - -**Current rule:** a feature qualifies only if every `NN-*.md` file is exactly `ready-for-agent`. - -**New rule:** a feature qualifies if: - -- Every `NN-*.md` file has a status in `{ready-for-agent, resolved, closed, rejected, ready-for-human}` -- At least one `NN-*.md` file has status `ready-for-agent` - -Any issue in `{needs-triage, needs-info, needs-specs}` (or any unrecognised state) disqualifies the whole feature — it is not fully prepped for autonomous execution. - -Alphabetical slug ordering is unchanged. - -### Worktree creation (Step 2) - -Before running `git worktree add`, check whether `.claude/worktrees/` already exists: - -``` -ls .claude/worktrees/ -``` - -- **Exists** (prior failed run) → skip `git worktree add` and reuse the existing worktree. The branch `feature/afk/` already contains the committed work from that run. -- **Does not exist** → create it as before: - -``` -git worktree add .claude/worktrees/ -b feature/afk/ develop -``` - -### Quick start note - -Add a note to the Quick start section explaining that a failed partial feature requires named invocation (`/implement-feature `) only if the loop is not running — if the loop is running, the new auto-select rule will pick it up automatically once the developer fixes the failing issue and leaves it at `ready-for-agent`. - -## Acceptance criteria - -- [ ] Auto-select picks up a feature where some issues are `resolved` and at least one is `ready-for-agent` -- [ ] Auto-select skips a feature that has any issue in `needs-triage`, `needs-info`, or `needs-specs` -- [ ] Auto-select still skips a feature where every issue is `resolved`, `closed`, or `rejected` (nothing left to run) -- [ ] Issues with status `ready-for-human` or `rejected` do not disqualify a feature -- [ ] When `.claude/worktrees/` already exists, the runner reuses it and does not call `git worktree add` -- [ ] When `.claude/worktrees/` does not exist, the runner creates it as before -- [ ] The execution queue (Step 3) continues to filter to `ready-for-agent` only — `resolved`, `closed`, `rejected`, and `ready-for-human` issues act only as satisfied dependency nodes -- [ ] `docs/agents/feature-runner.md` — Feature selection section updated to reflect the new qualification rule -- [ ] SKILL.md Quick start updated to note loop auto-resume behaviour after failure fix - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/feature-runner/15-ready-for-human-unsatisfied-dependency.md b/docs/issues/feature-runner/15-ready-for-human-unsatisfied-dependency.md deleted file mode 100644 index 97dbba96..00000000 --- a/docs/issues/feature-runner/15-ready-for-human-unsatisfied-dependency.md +++ /dev/null @@ -1,71 +0,0 @@ -# Halt when a ready-for-agent issue depends on a ready-for-human blocker - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Extend the step 3 dependency validation so that `ready-for-human` blockers are treated as **unsatisfied** dependencies. If a `ready-for-agent` issue in the execution queue has a `## Blocked by` dependency whose status is `ready-for-human`, the runner must halt before executing anything. - -Also clarify the "satisfied" language in step 3 and `docs/agents/feature-runner.md` to be explicit about which statuses satisfy dependencies and which do not. - -### Dependency satisfaction model - -| Status | Satisfies dependents? | Executed? | -| ----------------- | --------------------- | --------------------------------------------------------- | -| `resolved` | Yes | No | -| `closed` | Yes | No | -| `rejected` | Yes | No — rejection is a terminal decision; dependents proceed | -| `ready-for-human` | **No** | No — human work may not be done; dependents are blocked | -| `ready-for-agent` | — | Yes | - -### New validation check (Step 3) - -After building the topological execution order, before executing anything, add a second check: - -For each `ready-for-agent` issue in the execution queue, inspect its `## Blocked by` list. If any listed blocker has status `ready-for-human`, halt immediately with the **unsatisfied dependency error** (see `references/runner-output-formats.md`). - -### New error format (`references/runner-output-formats.md`) - -Add an **unsatisfied dependency error** section: - -``` -Feature Runner error: unsatisfied dependency. - Issue NN- is blocked by NN-, but NN- has status ready-for-human. - Complete issue NN- manually (or update its status) before re-running /implement-feature . -``` - -### Language fix (Step 3 and `docs/agents/feature-runner.md`) - -Replace: - -> "`resolved` and `closed` issues are already satisfied and act only as satisfied dependencies, not as items to execute." - -With: - -> "`resolved`, `closed`, and `rejected` issues are satisfied and act as satisfied dependency nodes — not items to execute. `ready-for-human` issues are not satisfied: if a `ready-for-agent` issue depends on one, the runner halts before executing anything." - -## Rationale - -`ready-for-human` means the work still needs to be done — just not by the runner. If a `ready-for-agent` issue depends on that work, executing it on an incomplete foundation risks a correct-but-wrong implementation. - -`rejected` is treated as satisfied because it is a terminal, intentional decision: the team consciously ruled the work out. A dependent issue proceeding without a rejected blocker is exactly what triage intended. (Typical scenario: team rejects issue 01 after initial triage; issue 02 which was blocked by 01 should still run.) - -## Acceptance criteria - -- [ ] Step 3 of SKILL.md checks each `ready-for-agent` issue's blockers for `ready-for-human` status before executing anything -- [ ] If any such blocker is found, the runner halts with the unsatisfied dependency error before executing any issue -- [ ] `references/runner-output-formats.md` contains the new unsatisfied dependency error format -- [ ] Step 3 "satisfied" language lists `resolved`, `closed`, and `rejected` as satisfied; notes `ready-for-human` as unsatisfied -- [ ] `docs/agents/feature-runner.md` updated to reflect the same model -- [ ] A `rejected` blocker does not halt the runner (treated as satisfied) - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/feature-runner/16-explicit-tdd-skill-invocation.md b/docs/issues/feature-runner/16-explicit-tdd-skill-invocation.md deleted file mode 100644 index ccc58462..00000000 --- a/docs/issues/feature-runner/16-explicit-tdd-skill-invocation.md +++ /dev/null @@ -1,49 +0,0 @@ -# Explicit `/tdd` skill invocation and pinned `subagent_type` in step 4 - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -The Feature Runner's step 4 invokes `/tdd` via the Agent tool but does not pin `subagent_type` and does not instruct the sub-agent to explicitly load the `/tdd` skill. The current prompt template frames the sub-agent as "running /tdd in AFK mode" and relies on trigger-phrase auto-discovery to load `/tdd`'s procedural guidance — an unreliable mechanism. - -ADR-0029 ratifies replacing `/tdd`'s _planning_ phase with acceptance criteria. The rest of the skill (anti-horizontal-slicing, tracer-bullet loop, refactor-only-when-green, deep-modules / interface-design / refactoring sub-references) is still load-bearing and must be loaded deterministically. - -### Changes - -**1. `SKILL.md` step 4** — pin the subagent type. - -Replace the current "invoke `/tdd` as a non-interactive sub-agent using the Agent tool" sentence with one that names the subagent type explicitly: - -> Invoke the sub-agent using the Agent tool with `subagent_type: general-purpose` — the only stock type with access to both the `Skill` tool (to load `/tdd`) and `Edit`/`Write` tools (to write code). - -**2. `references/tdd-prompt-template.md`** — prepend an explicit skill invocation instruction. - -At the top of the prompt body (before the AFK framing), add: - -``` -Begin by invoking the `tdd` skill via the Skill tool to load its full procedural guidance (red→green→refactor, vertical-slice rule, deep-modules / interface-design / refactoring sub-references). Then follow it using the acceptance criteria below as the pre-approved plan — the planning phase is complete; do not ask for confirmation. -``` - -**3. `docs/adr/0029-feature-runner-afk-invocation.md`** — amend the Consequences section. - -Append: - -> The Feature Runner's prompt template explicitly instructs the sub-agent to invoke the `tdd` skill via the Skill tool, rather than relying on auto-discovery via trigger phrases. This makes the procedural-guidance load deterministic across Claude Code surfaces. - -## Acceptance criteria - -- [ ] `SKILL.md` step 4 names `subagent_type: general-purpose` for the `Agent` call -- [ ] `references/tdd-prompt-template.md` opens with an explicit Skill-tool invocation instruction for `tdd`, placed before the AFK framing -- [ ] `docs/adr/0029-feature-runner-afk-invocation.md` Consequences section reflects the explicit-invocation policy -- [ ] The existing AFK framing ("The planning phase is complete — do not ask for confirmation") is preserved after the new instruction - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/feature-runner/17-prd-title-extraction-step-1.md b/docs/issues/feature-runner/17-prd-title-extraction-step-1.md deleted file mode 100644 index c027c7c2..00000000 --- a/docs/issues/feature-runner/17-prd-title-extraction-step-1.md +++ /dev/null @@ -1,32 +0,0 @@ -# Extract PRD `title:` frontmatter in step 1 - -**Status:** closed -**Category:** bug - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Step 7 of SKILL.md says: _"Derive the PR title from the PRD's `title` frontmatter field (already read in step 1)"_. But step 1 only says to read the PRD and scan it for `apps/claude-code//` path references. It never says to extract the `title:` value from the YAML frontmatter. - -A re-implementer or a sub-agent following step 1 verbatim would complete the step without capturing the PRD title, then encounter the step 7 parenthetical with no value to substitute. - -### Change - -In `SKILL.md` step 1, under "**Read the PRD:**", add one explicit instruction after the plugin-path scan: - -> Also extract the `title:` field from the PRD's YAML frontmatter (the value between the opening `---` and closing `---` at the top of the file). Retain it for use in step 7's PR title derivation. - -## Acceptance criteria - -- [ ] Step 1 of SKILL.md explicitly instructs the runner to extract the PRD's `title:` YAML frontmatter value -- [ ] Step 7's parenthetical "(already read in step 1)" remains accurate — the PRD title is gathered in step 1, not on-demand in step 7 -- [ ] No other changes to SKILL.md - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/feature-runner/18-failure-loop-protection.md b/docs/issues/feature-runner/18-failure-loop-protection.md deleted file mode 100644 index 6636297f..00000000 --- a/docs/issues/feature-runner/18-failure-loop-protection.md +++ /dev/null @@ -1,73 +0,0 @@ -# Protect `/loop` from re-picking a failed Feature (flip status to `needs-info`) - -**Status:** closed -**Category:** enhancement - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -When `/tdd` fails on an issue, the Feature Runner appends a failure note and stops — but leaves the failing issue at `ready-for-agent`. Under `/loop /implement-feature`, auto-select then re-picks the same Feature on the next iteration (because it still has a `ready-for-agent` issue) and retries the same failing issue, burning loop iterations indefinitely. - -The fix: on `/tdd` failure, flip the failing issue's `**Status:**` line from `ready-for-agent` to `needs-info`. `needs-info` is an existing triage label ("waiting on reporter for more information") and is already in the auto-select disqualification list at step 0 — no vocabulary expansion is required. - -### Changes - -**1. `SKILL.md` step 4 "On failure"** - -After appending the failure note, add a second edit: - -> Using the Edit tool, change the `**Status:** ready-for-agent` line to `**Status:** needs-info`. This prevents auto-select from picking up this Feature on subsequent loop iterations. - -**2. `references/runner-output-formats.md` — failure note** - -Update the failure note to mention the status flip and the recovery procedure: - -```markdown -## Comments - -> _This was generated by AI during triage._ - -**Feature Runner failure** — `/tdd` could not complete this issue. Status has been set to `needs-info`. - -The worktree at `.claude/worktrees/` has been left in place for inspection. Once the issue is resolved manually, restore `**Status:** ready-for-agent` and re-run `/implement-feature ` to resume. Alternatively, close or reject the issue if it should not be retried. -``` - -**3. `docs/agents/feature-runner.md` — "Failure behaviour" section** - -Update step 2 of the numbered list: - -Replace: - -> The issue remains at `Status: ready-for-agent`. - -With: - -> The issue status is changed to `needs-info`. This prevents the auto-selection path from picking up this Feature on subsequent `/loop` iterations until the developer investigates and restores `ready-for-agent` (or closes/rejects the issue). - -**4. `SKILL.md` Quick start — "Safe to interrupt" bullet** - -Distinguish Ctrl+C from `/tdd` failure explicitly. Update the bullet: - -> **Safe to interrupt** — Ctrl+C during any issue leaves that issue at `ready-for-agent`; re-running resumes from the first unresolved issue. Note: a **/tdd failure** (as opposed to a Ctrl+C interrupt) sets the failing issue to `needs-info`, preventing auto-select from retrying until the developer intervenes. - -## Rationale - -The overnight-loop use case is the primary composition for the Feature Runner. An auto-select that retries the same broken Feature undermines the purpose of `/loop`. `needs-info` already signals "blocked on a human" in the triage vocabulary — exactly the right state for a Feature Runner failure. - -## Acceptance criteria - -- [ ] On `/tdd` failure, the failing issue's `**Status:**` is changed to `needs-info` (not left at `ready-for-agent`) -- [ ] Subsequent auto-select runs skip the Feature (because `needs-info` already disqualifies a Feature in step 0) -- [ ] The failure note in `references/runner-output-formats.md` documents the `needs-info` flip and the recovery procedure (restore `ready-for-agent` and re-run, or close/reject) -- [ ] `docs/agents/feature-runner.md` "Failure behaviour" section reflects the status flip to `needs-info` -- [ ] SKILL.md Quick start distinguishes Ctrl+C (leaves `ready-for-agent`) from `/tdd` failure (sets `needs-info`) -- [ ] Manual interrupt (`Ctrl+C`) behaviour is unchanged: issue stays `ready-for-agent` - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/feature-runner/19-skill-agents-doc-crosslink.md b/docs/issues/feature-runner/19-skill-agents-doc-crosslink.md deleted file mode 100644 index 0597a546..00000000 --- a/docs/issues/feature-runner/19-skill-agents-doc-crosslink.md +++ /dev/null @@ -1,39 +0,0 @@ -# Add cross-link from SKILL.md to `docs/agents/feature-runner.md` - -**Status:** closed -**Category:** documentation - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -`SKILL.md` and `docs/agents/feature-runner.md` serve distinct audiences and should remain separate: - -- `SKILL.md` — runtime guidance for the orchestrating Claude instance. -- `docs/agents/feature-runner.md` — human-facing reference: lifecycle diagram, dependency-satisfaction matrix, ADR scope, historical cleanup convention. - -Currently there is no link from SKILL.md to the agents doc. A human reading the skill (or a developer extending it) has no signal that a fuller reference exists. - -### Change - -In `SKILL.md` Supporting Documentation section, add one line pointing to the agents doc: - -```markdown -- **`docs/agents/feature-runner.md`** — human-facing reference: lifecycle diagram, dependency-satisfaction matrix, ADR scope, historical cleanup convention. Maintained in parallel; consult for broader context, not for runtime instructions. -``` - -No prose is removed from either file. - -## Acceptance criteria - -- [ ] `SKILL.md` Supporting Documentation section includes a pointer to `docs/agents/feature-runner.md` with a one-line description -- [ ] No prose is removed from SKILL.md or `docs/agents/feature-runner.md` -- [ ] SKILL.md word count remains under 2,000 words after the addition - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/feature-runner/20-prompt-template-and-step-cleanup.md b/docs/issues/feature-runner/20-prompt-template-and-step-cleanup.md deleted file mode 100644 index 127c0e3e..00000000 --- a/docs/issues/feature-runner/20-prompt-template-and-step-cleanup.md +++ /dev/null @@ -1,60 +0,0 @@ -# Prompt-template deduplication and step-1/step-4 wording cleanup - -**Status:** closed -**Category:** documentation - -> _This was generated by AI during triage._ - -## Parent - -`docs/issues/feature-runner/PRD.md` - -## What to build - -Three small cleanups surfaced in the second-pass review of issues 16–19. - -### 20.a — Deduplicate prompt-template framing - -`references/tdd-prompt-template.md` currently opens with two paragraphs that both say "the planning phase is complete; do not ask for confirmation" and "use the acceptance criteria as the pre-approved plan." This is a side-effect of issue 16 prepending the explicit `tdd` Skill-tool-load instruction while preserving the original AFK framing verbatim. Every `/tdd` sub-agent invocation receives the duplicate. - -Replace both paragraphs with one consolidated paragraph that retains all unique signal: AFK identity, planning-phase-complete, explicit `tdd` Skill tool load, acceptance-criteria-as-plan, red→green→refactor loop entry. - -**Replacement** (everything before the `Working directory:` line): - -``` -You are running `/tdd` in AFK mode. The interactive planning phase is complete — do not ask for confirmation. Begin by invoking the `tdd` skill via the Skill tool to load its full procedural guidance (red→green→refactor, vertical-slice rule, deep-modules / interface-design / refactoring sub-references), then follow it using the acceptance criteria below as the pre-approved plan and proceed directly to the red→green→refactor loop. -``` - -### 20.b — Tighten step 1 closing line - -`SKILL.md` step 1 closing line (currently "These four items (PRD, CONTEXT.md, ADRs, recent commits) are static") was not updated when issue 17 added the PRD `title:` frontmatter parse. The PRD entry should reflect that both content and title are captured. - -**Replacement:** - -> These items (PRD content + title, CONTEXT.md, ADRs, recent commits) are static — gather them once before the issue loop begins. - -### 20.c — Reorder step 4 "On failure" sub-steps - -`SKILL.md` step 4 "On failure" currently appends the failure note (whose text says "Status has been set to `needs-info`") _before_ flipping the status to `needs-info`. This briefly leaves the file self-contradicting: the note says the status is `needs-info` while the status line still reads `ready-for-agent`. - -Swap the order so the status flip happens first: - -1. Using the Edit tool, change the `**Status:** ready-for-agent` line to `**Status:** needs-info`. This prevents auto-select from picking up this Feature on subsequent loop iterations. -2. Append the **failure note** (see `references/runner-output-formats.md`) to the issue file using the Edit tool, substituting ``. -3. Stop the runner immediately. Do not execute any subsequent issues — they may depend on a foundation this issue was meant to lay. -4. Report to the user: which issue failed, that the worktree is at `.claude/worktrees/` on branch `feature/afk/`, and that no subsequent issues were run. - -`docs/agents/feature-runner.md` "Failure behaviour" should reflect the same numbered order (status flip is step 2 in the list, failure note is step 1 currently — update to match). - -## Acceptance criteria - -- [ ] `references/tdd-prompt-template.md` contains exactly one paragraph framing the AFK invocation, before the `Working directory:` line -- [ ] The single paragraph mentions: AFK mode, planning-phase-complete, `tdd` Skill tool load via Skill tool, acceptance criteria as pre-approved plan, red→green→refactor loop -- [ ] No information from the previous two-paragraph version is lost -- [ ] `SKILL.md` step 1 closing line names "PRD content + title" (or equivalent) alongside CONTEXT.md, ADRs, and recent commits -- [ ] `SKILL.md` step 4 "On failure" performs the status flip (sub-step 1) before appending the failure note (sub-step 2) -- [ ] `docs/agents/feature-runner.md` "Failure behaviour" numbered list reflects the same ordering (status flip before note) - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/inbox-collision-check/01-fix-exit-code.md b/docs/issues/inbox-collision-check/01-fix-exit-code.md deleted file mode 100644 index 7c76305d..00000000 --- a/docs/issues/inbox-collision-check/01-fix-exit-code.md +++ /dev/null @@ -1,42 +0,0 @@ -# Fix inverted exit code in `/inbox` collision check - -**Status:** closed -**Category:** bug - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** bug -**Summary:** The `/inbox` command's collision-check script exits with code 1 on the happy path (no collision), causing Claude Code's Bash tool to display a false "Error: Exit code 1" on every successful capture. - -**Current behavior:** -The collision check in `.claude/commands/inbox.md` uses: - -```js -process.exit(require('fs').existsExists(p) ? 0 : 1) -``` - -Exit 0 (tool-success) means "file exists" (collision). Exit 1 (tool-error) means "file does not exist" (no collision). Since the no-collision path is the common case, every normal inbox capture shows a red "Error: Exit code 1" in the Bash tool output, even though the file is created successfully. - -**Desired behavior:** -The no-collision path should exit 0 (tool-success) and the collision path should exit 1 (tool-error). This way the Bash tool shows no error on a normal capture, and Claude correctly detects a collision (non-zero exit) and appends `-2`, `-3`, etc. - -**Key interfaces:** - -- The collision-check `node -e` snippet in `.claude/commands/inbox.md` Step 2 — swap the exit code values - -**Acceptance criteria:** - -- [ ] Running `/inbox ` produces no "Error: Exit code 1" in tool output -- [ ] Running `/inbox ` still detects the collision and appends `-2` to the slug -- [ ] The same fix is applied to the copy at the installed path (`.claude/plugins/marketplaces/unic-agent-plugins/.claude/commands/inbox.md`) if it is managed in this repo - -**Out of scope:** - -- Rewriting the collision-check with a different mechanism (fs.existsSync is fine) -- Changes to other parts of the inbox skill - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/pr-review-agents-not-discovered/01-rename-agents-dir-and-fix-frontmatter.md b/docs/issues/pr-review-agents-not-discovered/01-rename-agents-dir-and-fix-frontmatter.md deleted file mode 100644 index a35c0e19..00000000 --- a/docs/issues/pr-review-agents-not-discovered/01-rename-agents-dir-and-fix-frontmatter.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: 'pr-review: rename .agents/ → agents/ and add name: field to agent frontmatter' -created: 2026-05-19 ---- - -**Status:** resolved -**Category:** bug -**Plugin:** `apps/claude-code/pr-review` -**Depends on:** — - -## Problem Statement - -`pr-review:ado-fetcher` (and all other `pr-review` plugin agents) fail at runtime with: - -``` -Error: Agent type 'pr-review:ado-fetcher' not found. -``` - -**Root cause:** Claude Code's agent discovery scans an `agents/` directory inside each plugin. The `pr-review` plugin stores its agent files in `.agents/` (dot-prefixed, hidden on Unix), which is never scanned. The `pr-review-toolkit` plugin — which works correctly — uses `agents/` (no dot). - -**Secondary issue:** The `pr-review-toolkit` agent files declare a `name:` field in their YAML frontmatter (e.g. `name: code-reviewer`). The `pr-review` agent files only have `allowed-tools` and `description`. Whether the missing `name:` field is independently load-bearing is uncertain; it is added here defensively to match the working convention. - -**Evidence:** - -- Working: `~/.claude/plugins/cache/claude-plugins-official/pr-review-toolkit/unknown/agents/code-reviewer.md` -- Broken: `~/.claude/plugins/cache/unic-agent-plugins/pr-review/1.2.10/.agents/ado-fetcher.md` - -## Affected files - -| File | Change | -| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | -| `apps/claude-code/pr-review/.agents/` (directory) | Rename to `agents/` | -| `apps/claude-code/pr-review/.agents/ado-fetcher.md` | Add `name: ado-fetcher` to frontmatter | -| `apps/claude-code/pr-review/.agents/ado-writer.md` | Add `name: ado-writer` to frontmatter | -| `apps/claude-code/pr-review/.agents/re-review-coordinator.md` | Add `name: re-review-coordinator` to frontmatter | -| `apps/claude-code/pr-review/.agents/doc-context-orchestrator.md` | Add `name: doc-context-orchestrator` to frontmatter | -| `apps/claude-code/pr-review/.agents/doc-context-synthesizer.md` | Add `name: doc-context-synthesizer` to frontmatter | -| `apps/claude-code/pr-review/CLAUDE.md` | Update repository layout section: `.agents/` → `agents/` | -| `apps/claude-code/pr-review/docs/adr/0013-orchestrator-split-for-review-pr.md` | Amend in place: fix `.agents/` → `agents/` in the "Three focused agents live in…" paragraph | -| `CHANGELOG.md` | Add patch entry | -| `.claude-plugin/plugin.json` + `marketplace.json` | Bump patch version | - -Do **not** update historical plan files (`docs/plans/`) — those are already-executed specs and are left as written. - -## Implementation steps - -1. Rename the directory: `git mv apps/claude-code/pr-review/.agents apps/claude-code/pr-review/agents` -2. Add `name: ` as the first frontmatter key in each of the five agent files (use the filename stem as the value, e.g. `name: ado-fetcher`). -3. Update the repository layout table in `CLAUDE.md`: change `.agents/` → `agents/` in the directory tree and in any prose that names the directory. -4. Amend ADR 0013 in place: change the one occurrence of `the plugin's \`.agents/\` directory`to`the plugin's \`agents/\` directory`. No status or consequence lines need changing. -5. Add a `CHANGELOG.md` entry and bump the patch version in `plugin.json` + `marketplace.json`. - -## Verification - -After implementing, verify the fix end-to-end: - -1. **Cache invalidation check** — it is unknown whether the directory-source marketplace re-reads from the repo live or serves from the `~/.claude/plugins/cache/` snapshot. After renaming, check whether `~/.claude/plugins/cache/unic-agent-plugins/pr-review//.agents/` still exists. If it does, manually remove it (or delete and re-add the `pr-review@unic` entry in `enabledPlugins`) to force a fresh cache read. -2. **Agent discovery** — restart Claude Code and confirm `pr-review:ado-fetcher` appears in the available agent list (the list shown in the error message is a reliable source of truth). -3. **End-to-end smoke test** — run `/pr-review:review-pr` against a real ADO PR URL and confirm the ADO Fetcher agent launches without the "not found" error. - -## Acceptance criteria - -- `pr-review:ado-fetcher`, `pr-review:ado-writer`, `pr-review:re-review-coordinator`, `pr-review:doc-context-orchestrator`, and `pr-review:doc-context-synthesizer` all appear in Claude Code's available agent list after the rename. -- Running `/pr-review:review-pr ` reaches at least Step 5 (ADO Fetcher launch) without an "Agent type not found" error. -- No references to `.agents/` remain in `CLAUDE.md` or `docs/adr/0013-*`. -- ADR 0013 retains its original status and all consequence lines; only the directory name is corrected. diff --git a/docs/issues/pr-review-doc-context-enrichment/01-confluence-page-client.md b/docs/issues/pr-review-doc-context-enrichment/01-confluence-page-client.md deleted file mode 100644 index 205c159a..00000000 --- a/docs/issues/pr-review-doc-context-enrichment/01-confluence-page-client.md +++ /dev/null @@ -1,83 +0,0 @@ -# Confluence page client script + tests - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-doc-context-enrichment/PRD.md` - -## What to build - -Create `scripts/confluence-client.mjs` — a self-contained Node.js script (zero external runtime dependencies, `// @ts-check` + JSDoc) that loads Confluence credentials and fetches a page by URL via the Confluence v2 REST API. - -**Credential loading** follows the shared Unic precedence: environment variables (`CONFLUENCE_URL`, `CONFLUENCE_USER`, `CONFLUENCE_TOKEN`) take precedence; `~/.unic-confluence.json` is the fallback (same format as `unic-confluence`). Throws a descriptive error if neither source yields valid credentials. - -**Page fetching**: given a Confluence page URL, extract the numeric page ID (pattern: `/pages/{id}/` or `/pages/{id}` with optional trailing slug), call `GET /wiki/api/v2/pages/{pageId}?body-format=storage` with Basic auth, and return the `body.storage.value` string (Confluence storage XML). Throw a descriptive error on non-2xx responses or network failures — the caller handles warnings and fallback. - -**CLI entry point**: when invoked directly (`node scripts/confluence-client.mjs `), print the storage-format body to stdout and exit non-zero on any error. Also support `--check-creds` (exit 0 if credentials are available, non-zero otherwise). - -**Test suite** (`node:test`, no live Confluence connection): mock the HTTPS layer with fixtures. Cover: - -- Credential loading: env vars take precedence over `~/.unic-confluence.json` -- Credential loading: throws with actionable message when neither source is configured -- Page ID extraction from URL variants (`/pages/{id}/slug`, `/pages/{id}`, no trailing slash) -- Returns storage-format body on 200 response -- Throws descriptive error on 401, 403, 404 -- Throws descriptive error on network failure / timeout - -Follow the fixture pattern established in `apps/claude-code/pr-review/docs/plans/09-test-harness.md`. - -## Acceptance criteria - -- [ ] `scripts/confluence-client.mjs` exists with zero external runtime dependencies -- [ ] `node scripts/confluence-client.mjs ` fetches and prints page content (manual smoke test) -- [ ] `node scripts/confluence-client.mjs --check-creds` exits 0 when credentials are configured, non-zero otherwise -- [ ] All `node:test` cases pass -- [ ] Credential lookup order mirrors `unic-confluence` exactly - -## Blocked by - -None — can start immediately. - -## Comments - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** enhancement -**Summary:** Create a self-contained Confluence page client script with credential loading, page fetching, and a node:test suite — all with zero external runtime dependencies. - -**Current behavior:** -The pr-review plugin has no mechanism to fetch Confluence pages. No client script exists. - -**Desired behavior:** -A standalone Node.js script (`// @ts-check`, ESM) is available in the plugin's `scripts/` directory. It loads Confluence credentials following the Unic precedence order (env vars → `~/.unic-confluence.json`), accepts a Confluence page URL, extracts the numeric page ID from the URL path, fetches the page body in storage format via the Confluence v2 REST API, and returns the raw `body.storage.value` string. It exposes a `--check-creds` CLI flag that exits 0 when credentials are present and non-zero otherwise. On any error (bad credentials, non-2xx response, network failure) it throws a descriptive message — the caller handles warnings and fallback. - -The test suite uses `node:test` with a mocked HTTPS layer (no live Confluence connection). It covers the credential precedence, all URL ID extraction patterns, the happy path, and the main error conditions. - -**Key interfaces:** - -- `loadCredentials()` — reads env vars first, falls back to `~/.unic-confluence.json`; throws a descriptive `Error` if neither source is configured. Mirror the implementation in `unic-confluence`'s push script exactly. -- `fetchPageText(pageUrl, credentials)` — extracts numeric page ID from URL (handles `/pages/{id}/slug`, `/pages/{id}`, no trailing slash), calls Confluence v2 `GET /wiki/api/v2/pages/{id}?body-format=storage` with Basic auth, returns `body.storage.value`; throws on non-2xx or network error. -- CLI `--check-creds` flag — exits 0 if credentials load without error, non-zero otherwise. -- `~/.unic-confluence.json` shape — `{ url, username, token }` (same as `unic-confluence`). - -**Acceptance criteria:** - -- [ ] Script exists with zero external runtime dependencies -- [ ] `--check-creds` exits 0 when credentials are configured, non-zero otherwise -- [ ] Page ID extracted correctly from all three URL variants -- [ ] Returns storage-format body on 200 response -- [ ] Throws descriptive error on 401, 403, 404, and network failure -- [ ] Credential loading: env vars take precedence over `~/.unic-confluence.json` -- [ ] Credential loading: throws actionable message when neither source is configured -- [ ] All `node:test` cases pass without a live Confluence connection -- [ ] Credential lookup order is identical to `unic-confluence`'s push script - -**Out of scope:** - -- Parsing or stripping Confluence storage XML — callers receive the raw value -- Caching page content across invocations -- Any changes to `commands/review-pr.md` (that is issues 02 and 03) diff --git a/docs/issues/pr-review-doc-context-enrichment/02-work-item-doc-context-enrichment.md b/docs/issues/pr-review-doc-context-enrichment/02-work-item-doc-context-enrichment.md deleted file mode 100644 index abc18508..00000000 --- a/docs/issues/pr-review-doc-context-enrichment/02-work-item-doc-context-enrichment.md +++ /dev/null @@ -1,81 +0,0 @@ -# Work item Doc Context enrichment - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-doc-context-enrichment/PRD.md` - -## What to build - -Add a new **step 4a** to `commands/review-pr.md` that runs after the changed files list (step 4) and in parallel with the local diff and file reading steps (5–7). Step 8 waits for step 4a to complete before launching review agents. - -Step 4a fetches the ADO work items linked to the PR via the `pullRequestWorkItems` API endpoint. If the list is empty, it exits silently with no change to behaviour. For each linked work item, it fetches the work item details (`az boards work-item show`) and spawns one **Doc Context Sub-agent** per work item in parallel (single message). - -Each Doc Context Sub-agent receives the work item ID, title, and description (HTML), plus the changed files list and the local diff if already available. It produces a diff-aware summary of the work item description — focused only on what is relevant to the changed files — and returns a structured block: - -``` -### Work item: [{ID}] {Title} -{diff-aware summary} -``` - -Step 4a collects all sub-agent outputs, prepends a `## Business context for this PR` header, and stores the result as `DOC_CONTEXT`. Step 8 injects `DOC_CONTEXT` as a preamble before the diff content in every review agent prompt. When `DOC_CONTEXT` is empty (no work items, or all sub-agents returned nothing useful), the preamble is omitted and step 8 behaves exactly as today. - -## Acceptance criteria - -- [ ] A PR with one or more linked ADO work items: review agents receive a `## Business context for this PR` preamble with a summarised work item section per item -- [ ] A PR with no linked work items: step 4a exits silently, review agent prompts are unchanged -- [ ] Multiple work items are all included in the Doc Context block -- [ ] Step 4a runs in parallel with steps 5–7 (not sequentially before them) -- [ ] When the local diff is not yet available at step 4a time, sub-agents work from the changed files list only -- [ ] No new comments or threads are posted to the PR - -## Blocked by - -None — can start immediately. - -## Comments - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** enhancement -**Summary:** Add step 4a to the review command that fetches linked ADO work items, spawns parallel Doc Context Sub-agents to summarise them, and injects the result as a business context preamble into every review agent's prompt. - -**Current behavior:** -The review command (steps 1–12) passes the PR title, description, diff, and changed file contents to review agents. No work item data is fetched. Review agents have no visibility into the business intent of the PR. - -**Desired behavior:** -A new step 4a runs after the changed files list (step 4) and in parallel with steps 5–7. It calls the ADO `pullRequestWorkItems` API to get the IDs of all work items linked to the PR. If none are linked, step 4a exits silently and behaviour is unchanged. For each linked work item it fetches the full work item record (`az boards work-item show`) and spawns one Doc Context Sub-agent per work item in a single parallel message. Each sub-agent receives the work item ID, title, and HTML description, plus the changed files list and local diff (if already available). It returns a diff-aware summary as: - -``` -### Work item: [{ID}] {Title} -{diff-aware summary focused on what is relevant to the changed files} -``` - -Step 4a collects all sub-agent outputs, prepends a `## Business context for this PR` header, and stores the assembled block as `DOC_CONTEXT`. Step 8 injects `DOC_CONTEXT` as a preamble before the diff content in every review agent prompt. If `DOC_CONTEXT` is empty, step 8 behaves exactly as before. - -**Key interfaces:** - -- ADO `pullRequestWorkItems` resource — called via `az devops invoke` with `repositoryId`, `pullRequestId`, and `org` route parameters; returns `{ value: [{ id }] }` -- `az boards work-item show --id {id} --org {ORG_URL}` — fields needed: `System.Title`, `System.Description` -- Doc Context block header: `## Business context for this PR` -- Work item section format: `### Work item: [{ID}] {Title}` followed by the summary -- Step 8 prompt preamble injection: `DOC_CONTEXT` precedes the diff section - -**Acceptance criteria:** - -- [ ] PR with linked work items: review agents receive a `## Business context for this PR` preamble with one section per work item -- [ ] PR with no linked work items: step 4a exits silently, review agent prompts unchanged -- [ ] Multiple linked work items: all appear in the Doc Context block -- [ ] Step 4a spawns sub-agents in parallel with steps 5–7, not before them -- [ ] Sub-agents function correctly when local diff is not yet available (work from changed files list only) -- [ ] No new comments or threads are posted to the PR - -**Out of scope:** - -- Fetching Confluence pages (that is issue 03) -- Any credential handling (no Confluence dependency in this issue) -- Changes to the confluence-client script (that is issue 01) diff --git a/docs/issues/pr-review-doc-context-enrichment/03-confluence-page-doc-context-enrichment.md b/docs/issues/pr-review-doc-context-enrichment/03-confluence-page-doc-context-enrichment.md deleted file mode 100644 index a0152915..00000000 --- a/docs/issues/pr-review-doc-context-enrichment/03-confluence-page-doc-context-enrichment.md +++ /dev/null @@ -1,116 +0,0 @@ -# Confluence page Doc Context enrichment - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-doc-context-enrichment/PRD.md` - -## What to build - -Extend the work item Doc Context Sub-agent (from issue 02) to follow Confluence page links found in work item descriptions. - -Each work item Doc Context Sub-agent, after summarising the work item description, extracts all Confluence page URLs from the description text. It then checks whether Confluence credentials are available (`node scripts/confluence-client.mjs --check-creds`). - -**If credentials are available**: spawn one nested **Confluence page Doc Context Sub-agent** per extracted URL in parallel. Each page sub-agent invokes `node scripts/confluence-client.mjs ` to fetch the storage-format page body, then produces a diff-aware plain-text summary of the page content (reading through Confluence storage-format XML directly, no dedicated parser). It returns a structured block: - -``` -### Confluence — {Page Title} ({URL}) -{diff-aware summary} -``` - -These blocks are appended after the work item summary section in the Doc Context block for that work item. - -**If credentials are absent and at least one Confluence URL was found**: emit a console warning (never post to the PR): - -``` -⚠ Confluence pages not fetched — set CONFLUENCE_URL, CONFLUENCE_USER, - CONFLUENCE_TOKEN (or configure ~/.unic-confluence.json) to enable - doc-aware review. -``` - -**If credentials are absent and no Confluence URLs were found**: skip silently. - -**If a page fetch fails** (network error, 401, 403, or any non-2xx): skip that page and emit a per-page console warning: - -``` -⚠ Could not fetch Confluence page — -``` - -Continue with whatever other context was gathered. A single failing page does not block the review. - -## Acceptance criteria - -- [ ] A PR whose work item description links to a Confluence page, with valid credentials: review agents receive the work item summary plus a Confluence page summary with provenance label (title + URL) -- [ ] Multiple Confluence links in one work item: all pages are fetched in parallel and included -- [ ] Credentials absent + Confluence URLs found: console warning shown, review continues with work item summaries only -- [ ] Credentials absent + no Confluence URLs: no warning, no change in output -- [ ] Confluence page returns 403: that page skipped with per-page console warning; other pages and work items still included -- [ ] Network error on a page fetch: same skip-and-warn behaviour as 403 -- [ ] Warnings are emitted to the console only — nothing posted to the PR - -## Blocked by - -- `docs/issues/pr-review-doc-context-enrichment/01-confluence-page-client.md` -- `docs/issues/pr-review-doc-context-enrichment/02-work-item-doc-context-enrichment.md` - -## Comments - -> _This was generated by AI during triage._ - -## Agent Brief - -**Category:** enhancement -**Summary:** Extend each work item Doc Context Sub-agent to extract Confluence URLs from the work item description, fetch those pages using the Confluence client script, and append diff-aware page summaries to the Doc Context block — with graceful degradation when credentials are absent or a fetch fails. - -**Current behavior:** -Work item Doc Context Sub-agents (from issue 02) summarise work item descriptions only. They do not follow any Confluence links found in those descriptions. - -**Desired behavior:** -After summarising the work item description, each work item Doc Context Sub-agent extracts all Confluence page URLs from the description text. It then runs `node scripts/confluence-client.mjs --check-creds` to determine whether credentials are available. - -If credentials are present: spawn one nested Confluence page Doc Context Sub-agent per extracted URL in a single parallel message. Each page sub-agent runs `node scripts/confluence-client.mjs ` to fetch the storage-format page body, reads through the XML directly (no dedicated parser), and returns a diff-aware plain-text summary as: - -``` -### Confluence — {Page Title} ({URL}) -{diff-aware summary} -``` - -These sections are appended after the work item summary in the work item's Doc Context block. - -If credentials are absent and at least one Confluence URL was found: emit a console warning (never post to the PR): - -``` -⚠ Confluence pages not fetched — set CONFLUENCE_URL, CONFLUENCE_USER, - CONFLUENCE_TOKEN (or configure ~/.unic-confluence.json) to enable - doc-aware review. -``` - -If credentials are absent and no Confluence URLs were found: skip silently. - -If any individual page fetch fails (any error): skip that page, emit a per-page console warning (`⚠ Could not fetch Confluence page — `), and continue with whatever other context was gathered. - -**Key interfaces:** - -- `node scripts/confluence-client.mjs --check-creds` — exit 0 = credentials present -- `node scripts/confluence-client.mjs ` — stdout = storage-format XML; non-zero exit = error with message on stderr -- Confluence page section format: `### Confluence — {Page Title} ({URL})` followed by the summary -- Console warning format: `⚠ Confluence pages not fetched — …` (credentials absent) and `⚠ Could not fetch Confluence page — ` (per-page error) - -**Acceptance criteria:** - -- [ ] PR with a work item linking to a Confluence page, valid credentials: review agents receive work item summary + Confluence page summary with provenance label -- [ ] Multiple Confluence links in one work item: all fetched in parallel and included -- [ ] Credentials absent + Confluence URLs found: single console warning; review continues with work item summaries only -- [ ] Credentials absent + no Confluence URLs: no warning, no change in output -- [ ] Page fetch returns 403: that page skipped with per-page console warning; other pages and work items still included -- [ ] Network error on a fetch: same skip-and-warn behaviour -- [ ] All warnings go to the console only — nothing posted to the PR - -**Out of scope:** - -- Parsing Confluence storage XML with a dedicated parser — the sub-agent reads through it directly -- Caching page content across review runs -- Fetching Confluence pages linked from the PR description (not via a work item) -- Any changes to the confluence-client script itself (that is issue 01) diff --git a/docs/issues/pr-review-doc-context-enrichment/04-version-bump-and-docs.md b/docs/issues/pr-review-doc-context-enrichment/04-version-bump-and-docs.md deleted file mode 100644 index 88d3a182..00000000 --- a/docs/issues/pr-review-doc-context-enrichment/04-version-bump-and-docs.md +++ /dev/null @@ -1,48 +0,0 @@ -# Version bump + CHANGELOG + docs - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-doc-context-enrichment/PRD.md` - -## What to build - -Finalise metadata, documentation, and release artefacts for the doc context enrichment feature. - -**Before running the bump script**, check what version the re-review feature shipped at (`docs/issues/pr-review-rereview/09-version-bump-and-release.md`). The bump for this feature must target the next available minor version after re-review — do not hardcode a version number here. - -**Steps (in order):** - -1. **Add CHANGELOG entry.** Under `## [Unreleased]` in `CHANGELOG.md`, add under `### Added`: - - > Doc Context enrichment: before review agents run, fetch linked ADO work items and any Confluence pages referenced in their descriptions; inject structured, diff-aware summaries as business context into every review agent's prompt. Requires Confluence credentials (`CONFLUENCE_URL`, `CONFLUENCE_USER`, `CONFLUENCE_TOKEN` or `~/.unic-confluence.json`) for Confluence page fetching; degrades gracefully when absent or unreachable. - -2. **Bump the version.** Run `pnpm --filter pr-review bump minor`. This updates both `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` atomically. Never hand-edit `marketplace.json`. - -3. **Update `README.md`.** Add a section describing the Doc Context enrichment capability: what it does, credential prerequisites (`CONFLUENCE_URL`, `CONFLUENCE_USER`, `CONFLUENCE_TOKEN` or `~/.unic-confluence.json`), and graceful degradation behaviour. - -4. **Update `CLAUDE.md`.** Remove "PR description generation from diff" and any doc-context-enrichment roadmap lines if present. Verify that new step 4a is reflected in the repository layout description. - -5. **Verify.** Run `pnpm --filter pr-review verify:changelog` locally before opening the PR. - -## Acceptance criteria - -- [ ] `pnpm --filter pr-review verify:changelog` passes locally -- [ ] Versions match across `plugin.json` and `marketplace.json` -- [ ] `CHANGELOG.md` has a dated entry for the new version under `### Added` -- [ ] `README.md` documents the enrichment capability and credential prerequisites -- [ ] CI passes on the release PR - -## Blocked by - -- `docs/issues/pr-review-doc-context-enrichment/02-work-item-doc-context-enrichment.md` -- `docs/issues/pr-review-doc-context-enrichment/03-confluence-page-doc-context-enrichment.md` - -## Comments - -> _This was generated by AI during triage._ - -**Why this is ready-for-human, not ready-for-agent:** -The version number cannot be determined without first knowing what version the re-review feature shipped at. That requires checking a real-time state (`docs/issues/pr-review-rereview/09-version-bump-and-release.md`) that may not be resolved when this issue is picked up. Additionally, the CHANGELOG entry and README section involve prose decisions that benefit from human authorship. The mechanical bump step (`pnpm --filter pr-review bump minor`) is straightforward once the version is confirmed. diff --git a/docs/issues/pr-review-doc-context-spawn-reliability/01-adr-and-synthesizer-agent.md b/docs/issues/pr-review-doc-context-spawn-reliability/01-adr-and-synthesizer-agent.md deleted file mode 100644 index 307c0a7e..00000000 --- a/docs/issues/pr-review-doc-context-spawn-reliability/01-adr-and-synthesizer-agent.md +++ /dev/null @@ -1,70 +0,0 @@ -# ADR-0012 + Doc Context Synthesizer agent - -**Status:** closed -**Category:** enhancement -**Type:** AFK - -## Parent - -`docs/issues/pr-review-doc-context-spawn-reliability/PRD.md` - -## What to build - -Write ADR-0012 recording the decision to have the Doc Context Orchestrator agent return plain markdown rather than a JSON wrapper. Then create the Doc Context Synthesizer agent — a new plugin agent that receives all Work Item Summarizer outputs and Confluence Fetcher outputs, and produces a single `## Business context for this PR` flat narrative with no per-work-item headings, no redundant content, focused on business intent. Returns an empty string if no meaningful context was gathered. - -## Acceptance criteria - -- [ ] `docs/adr/0012-plain-text-doc-context-agent-return.md` exists and records: the decision (plain markdown), the rejected alternative (JSON wrapper), and the reasons (LLM agents produce malformed JSON under long-context conditions; warnings are already emitted as side effects; `jq` extraction from LLM output is unreliable). -- [ ] `.agents/doc-context-synthesizer.md` exists as a plugin agent file. -- [ ] The synthesizer agent prompt instructs it to produce a flat `## Business context for this PR` narrative — no per-work-item headings, no structural grouping by ticket. -- [ ] The prompt instructs the agent to merge overlapping content (same feature described by multiple work items or Confluence pages) rather than repeating it. -- [ ] The prompt instructs the agent to focus on business intent (what the PR should accomplish and why) and omit implementation details already visible in the diff. -- [ ] The prompt instructs the agent to return an empty string if no meaningful context was gathered. - -## Blocked by - -None — can start immediately. - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Create ADR-0012 (plain-markdown return format) and the Doc Context Synthesizer agent - -**Current behavior:** - -Neither file exists. The ADR decision and the synthesizer agent are prerequisites for the orchestrator agent (issue 02) and the step 4a wire-up (issue 03). - -**Desired behavior:** - -`docs/adr/0012-plain-text-doc-context-agent-return.md` exists and records the decision to return plain markdown from the Doc Context Orchestrator agent (not a JSON wrapper), the rejected JSON alternative, and the three reasons it was rejected (malformed JSON under long context; warnings already emitted as side effects; `jq` extraction from LLM output is unreliable). - -`.agents/doc-context-synthesizer.md` exists as a plugin agent. Its prompt instructs the agent to: - -- Receive all Work Item Summarizer outputs and Confluence Fetcher outputs -- Produce a single flat `## Business context for this PR` narrative — no per-work-item headings, no redundant repetition -- Merge overlapping content where multiple sources describe the same feature -- Focus on business intent (what the PR should accomplish and why), not implementation details visible in the diff -- Return an empty string if no meaningful context was gathered - -**Key interfaces:** - -- `doc-context-synthesizer` plugin agent — input: work item summaries + Confluence page summaries (plain text); output: `## Business context for this PR` markdown block or empty string -- ADR-0012 — follows the existing ADR format in `docs/adr/` - -**Acceptance criteria:** - -- [ ] `docs/adr/0012-plain-text-doc-context-agent-return.md` exists with decision, rejected alternative, and reasons -- [ ] `.agents/doc-context-synthesizer.md` exists as a plugin agent file -- [ ] Synthesizer prompt produces a flat narrative — no per-work-item headings -- [ ] Synthesizer prompt merges overlapping content rather than repeating it -- [ ] Synthesizer prompt returns an empty string when no meaningful context is available - -**Out of scope:** - -- The orchestrator agent (issue 02) -- Changes to `commands/review-pr.md` (issue 03) -- Any changes to `confluence-client.mjs` or its tests diff --git a/docs/issues/pr-review-doc-context-spawn-reliability/02-orchestrator-agent.md b/docs/issues/pr-review-doc-context-spawn-reliability/02-orchestrator-agent.md deleted file mode 100644 index c267efa6..00000000 --- a/docs/issues/pr-review-doc-context-spawn-reliability/02-orchestrator-agent.md +++ /dev/null @@ -1,86 +0,0 @@ -# Doc Context Orchestrator agent - -**Status:** closed -**Category:** enhancement -**Type:** AFK - -## Parent - -`docs/issues/pr-review-doc-context-spawn-reliability/PRD.md` - -## What to build - -Create the Doc Context Orchestrator agent — a new self-contained plugin agent that handles the entire Doc Context gathering phase in its own context window. It receives: `ORG_URL`, `PR_ID`, a list of work item IDs, the full diff, the changed files list, and the absolute path to `confluence-client.mjs` (pre-expanded by the caller — agents do not inherit env vars). - -The agent must: - -1. Fetch each work item via `az boards work-item show`. Skip and warn on failure. -2. Branch on work item type: `Bug` → extract `Microsoft.VSTS.TCM.ReproSteps` + `Microsoft.VSTS.TCM.SystemInfo`; all other types (including unrecognised) → `System.Description`. -3. Spawn one Work Item Summarizer agent per work item in parallel. Each summarizer receives the work item content, changed files, and diff; returns a plain-text summary and a list of Confluence URLs found in the description. -4. Run `node {CONFLUENCE_CLIENT_PATH} --check-creds` exactly once. If creds are absent and Confluence URLs were found: emit the standard warning to console and skip all Confluence fetching. -5. If creds are available: collect all unique Confluence URLs across all summarizer outputs and spawn one Confluence Fetcher agent per unique URL in parallel. Each fetcher runs `node {CONFLUENCE_CLIENT_PATH} {URL}` and returns a plain-text summary or emits a warning and returns nothing on failure. -6. Pass all summarizer and fetcher outputs to the Doc Context Synthesizer agent. -7. Return the synthesizer's output verbatim as plain markdown — no JSON wrapper. - -## Acceptance criteria - -- [ ] `.agents/doc-context-orchestrator.md` exists as a plugin agent file. -- [ ] The agent prompt references `pr-review:doc-context-synthesizer` for the final synthesis step. -- [ ] Bug work items: prompt instructs extraction of `ReproSteps` + `SystemInfo`, not `System.Description`. -- [ ] Unrecognised work item types: prompt instructs fallback to `System.Description`. -- [ ] Credential check runs exactly once (not per fetcher, not per work item). -- [ ] All paths to `confluence-client.mjs` in the prompt are described as absolute literal strings passed in by the caller — no relative paths, no env-var references inside the agent. -- [ ] Console warnings (failed work item fetch, missing creds, failed Confluence fetch) are printed as side effects; none appear in the agent's return value. -- [ ] The agent returns plain markdown (the synthesizer's output verbatim), consistent with ADR-0012. - -## Blocked by - -`01-adr-and-synthesizer-agent.md` — synthesizer interface must be settled before this agent references it. - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Create the Doc Context Orchestrator agent — self-contained gathering phase in its own context window - -**Current behavior:** - -The agent file does not exist. Step 4a currently satisfies doc-context intent inline with no `Agent()` spawn call, so no orchestrator runs and no business context is gathered. - -**Desired behavior:** - -`.agents/doc-context-orchestrator.md` exists as a plugin agent. When invoked, it receives `ORG_URL`, `PR_ID`, a list of work item IDs, the full diff, the changed files list, and `CONFLUENCE_CLIENT_PATH` (absolute path, pre-expanded by the caller). It orchestrates the entire Doc Context gathering phase and returns the Doc Context Synthesizer's output verbatim as plain markdown. - -Key behavioural contracts: - -- Per work item: fetch via `az boards work-item show`; branch on type (`Bug` → `ReproSteps` + `SystemInfo`, all others → `System.Description`); skip + warn on failure -- Spawn one Work Item Summarizer agent per work item in parallel -- Run `--check-creds` exactly once; if creds absent and Confluence URLs found, emit the standard warning and skip all fetching -- If creds present: deduplicate Confluence URLs across all summarizer outputs, spawn one Confluence Fetcher agent per unique URL in parallel -- Delegate all outputs to `pr-review:doc-context-synthesizer`; return its output verbatim -- All `confluence-client.mjs` paths are the absolute literal string received as input — no env-var references inside the agent prompt - -**Key interfaces:** - -- `doc-context-orchestrator` plugin agent — inputs: `ORG_URL`, `PR_ID`, work item ID list, diff, changed files, `CONFLUENCE_CLIENT_PATH` (absolute string); output: plain markdown block or empty string -- `pr-review:doc-context-synthesizer` — called as the final step; must be implemented first (issue 01) -- Work Item Summarizer agents — spawned inline (anonymous), not as named plugin agent types - -**Acceptance criteria:** - -- [ ] `.agents/doc-context-orchestrator.md` exists as a plugin agent file -- [ ] Prompt references `pr-review:doc-context-synthesizer` for the final step -- [ ] Bug work items use `ReproSteps` + `SystemInfo`; all other types use `System.Description` -- [ ] Credential check runs exactly once — not per fetcher, not per work item -- [ ] All `confluence-client.mjs` paths in the prompt are absolute literal strings from the caller — no relative paths -- [ ] Warnings are printed as side effects; none appear in the return value -- [ ] Agent returns plain markdown consistent with ADR-0012 - -**Out of scope:** - -- Changes to `commands/review-pr.md` (issue 03) -- Changes to `confluence-client.mjs` or its tests -- GitHub PR support, caching, or Jira sources diff --git a/docs/issues/pr-review-doc-context-spawn-reliability/03-wire-up-and-housekeeping.md b/docs/issues/pr-review-doc-context-spawn-reliability/03-wire-up-and-housekeeping.md deleted file mode 100644 index 0d5f78dc..00000000 --- a/docs/issues/pr-review-doc-context-spawn-reliability/03-wire-up-and-housekeeping.md +++ /dev/null @@ -1,93 +0,0 @@ -# Wire-up: step 4a rewrite + README + CHANGELOG - -**Status:** closed -**Category:** bug -**Type:** AFK - -## Parent - -`docs/issues/pr-review-doc-context-spawn-reliability/PRD.md` - -## What to build - -Rewrite step 4a in `commands/review-pr.md` to fix the three defects that cause the Doc Context phase to be silently skipped: - -1. Initialise `DOC_CONTEXT=''` unconditionally as the first statement in step 4a. -2. Pre-fetch linked work item IDs in bash. If the `value` array is empty or the command fails, leave `DOC_CONTEXT=''` and proceed. -3. If work items are found: wait for the diff from step 5, resolve `CONFLUENCE_CLIENT_PATH` from `${CLAUDE_PLUGIN_ROOT}` in bash, then spawn the Doc Context Orchestrator agent via an explicit `Agent(subagent_type: "pr-review:doc-context-orchestrator", ...)` call with all required context. Store the agent's plain-text output as `DOC_CONTEXT`. -4. Update the parallelism note: step 4a pre-fetch runs in parallel with steps 5–7; the orchestrator agent spawn waits for the diff from step 5; step 8 waits for the orchestrator to complete. - -Also update `docs/plans/README.md` to add spec 11 to the status table, and add a `Fixed` entry under `[Unreleased]` in `CHANGELOG.md` describing the three defects and the orchestrator extraction. - -## Acceptance criteria - -- [ ] `DOC_CONTEXT=''` is the first statement in step 4a. -- [ ] Step 4a contains an explicit `Agent(subagent_type: "pr-review:doc-context-orchestrator", ...)` call — the intent is not satisfied inline. -- [ ] The `Agent()` call passes `ORG_URL`, `PR_ID`, work item ID list, `CONFLUENCE_CLIENT_PATH` (as an absolute string expanded from `${CLAUDE_PLUGIN_ROOT}`), changed files list, and diff. -- [ ] No `node scripts/confluence-client.mjs` relative-path call remains in step 4a. -- [ ] The parallelism note correctly reflects that the orchestrator spawn waits for the diff before starting. -- [ ] `docs/plans/README.md` includes spec 11 in the status table. -- [ ] `CHANGELOG.md` has a `Fixed` entry under `[Unreleased]` covering the three defects. -- [ ] PR with ≥1 linked non-Bug work item and no Confluence links: `DOC_CONTEXT` is non-empty after a review run; review agents receive the `## Business context` preamble. -- [ ] PR with no linked work items: step 4a exits silently; `DOC_CONTEXT=''`; step 8 prompts unchanged. -- [ ] No new PR threads or comments produced by the Doc Context phase. - -## Blocked by - -- `01-adr-and-synthesizer-agent.md` -- `02-orchestrator-agent.md` - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** bug -**Summary:** Fix step 4a in `review-pr` command — initialise `DOC_CONTEXT`, add explicit Agent() spawn, resolve absolute path - -**Current behavior:** - -Step 4a has three defects that cause the Doc Context phase to be silently skipped on every run: - -1. No `DOC_CONTEXT=''` initialisation — the variable is undefined when the phase is skipped -2. No explicit `Agent()` spawn call — the orchestrator satisfies intent inline and proceeds without spawning anything -3. `confluence-client.mjs` is referenced with a relative path that fails when the working directory is the reviewed project's root - -**Desired behavior:** - -Step 4a in the `review-pr` command is rewritten so that: - -- `DOC_CONTEXT=''` is the first statement -- If no work items are linked, the step exits silently with `DOC_CONTEXT=''` -- If work items are found, an explicit `Agent(subagent_type: "pr-review:doc-context-orchestrator", ...)` call is made — never satisfied inline — with all required context: `ORG_URL`, `PR_ID`, work item IDs, `CONFLUENCE_CLIENT_PATH` (absolute string from `${CLAUDE_PLUGIN_ROOT}`), changed files list, and diff -- The agent's plain-text output is stored as `DOC_CONTEXT` -- The parallelism note reflects the correct sequencing: pre-fetch runs in parallel with steps 5–7; orchestrator spawn waits for the diff; step 8 waits for the orchestrator - -`docs/plans/README.md` includes spec 11 in the status table. `CHANGELOG.md` has a `Fixed` entry under `[Unreleased]` covering the three defects. - -**Key interfaces:** - -- `review-pr` command step 4a — the `Agent()` call must name `subagent_type: "pr-review:doc-context-orchestrator"` explicitly -- `CONFLUENCE_CLIENT_PATH` — resolved as `"${CLAUDE_PLUGIN_ROOT}/scripts/confluence-client.mjs"` in bash before the spawn -- `DOC_CONTEXT` — string; empty when no work items are found, plain markdown block otherwise - -**Acceptance criteria:** - -- [ ] `DOC_CONTEXT=''` is the first statement in step 4a -- [ ] Explicit `Agent(subagent_type: "pr-review:doc-context-orchestrator", ...)` call present — intent not satisfied inline -- [ ] `Agent()` call passes all required context variables -- [ ] No `node scripts/confluence-client.mjs` relative-path call remains in step 4a -- [ ] Parallelism note correctly reflects orchestrator spawn waiting for the diff -- [ ] `docs/plans/README.md` includes spec 11 -- [ ] `CHANGELOG.md` has a `Fixed` entry under `[Unreleased]` -- [ ] PR with ≥1 linked non-Bug work item: `DOC_CONTEXT` non-empty after a review run -- [ ] PR with no linked work items: step 4a silent; `DOC_CONTEXT=''` -- [ ] No new PR threads or comments from the Doc Context phase - -**Out of scope:** - -- The agent file implementations (issues 01 and 02) -- Changes to `confluence-client.mjs` or its tests -- Thread posting, re-review logic, or Bot Signature -- GitHub PR support, caching, or Jira sources diff --git a/docs/issues/pr-review-orchestrator-split/01-create-ado-fetcher-agent.md b/docs/issues/pr-review-orchestrator-split/01-create-ado-fetcher-agent.md deleted file mode 100644 index 6e6e2cbf..00000000 --- a/docs/issues/pr-review-orchestrator-split/01-create-ado-fetcher-agent.md +++ /dev/null @@ -1,65 +0,0 @@ -# Create ADO Fetcher agent - -**Status:** resolved -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-orchestrator-split/PRD.md` - -## What to build - -Create a new plugin agent (`pr-review:ado-fetcher`) that encapsulates all Azure DevOps read operations required for a PR review. The agent receives a PR URL (org, project, PR ID) and an optional prior iteration ID (passed in for re-review, empty string for first-review), and returns a structured context block containing: PR metadata (title, description, source/target branches, repo ID), latest iteration ID and its commit SHA, changed files list, raw diff, and work-item IDs linked to the PR. - -This agent replaces the inline ADO shell commands currently scattered across Steps 2–5 of the `review-pr` command. It is invoked by first-review and re-review modes; pre-PR mode never calls it. - -The ADO Fetcher is a prerequisite for the Doc Context Orchestrator — the Fetcher must complete first because its output (work-item IDs) is the input the Doc Context Orchestrator needs. Once the Fetcher returns, the Doc Context Orchestrator and review aspect agents launch concurrently with each other. - -## Acceptance criteria - -- [x] The agent accepts PR URL components (org URL, project, PR ID) and returns a structured context block -- [x] The context block includes PR metadata, latest iteration ID, latest commit SHA, changed files list, and raw diff -- [x] The context block includes the work-item IDs linked to the PR (empty list if none) -- [x] The agent handles the case where no iterations are returned (defaults gracefully) -- [x] The agent handles PRs that are already merged (continues without error) -- [x] The agent contains no write operations — it is purely a read agent - -## Blocked by - -None — can start immediately. - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Create the `pr-review:ado-fetcher` agent that encapsulates all ADO read operations for a PR review. - -**Current behavior:** -ADO read operations (PR metadata, iterations, changed files, diff, work-item IDs) are scattered as inline `az devops invoke` shell commands across multiple steps of the `review-pr` command. There is no dedicated agent for this concern. - -**Desired behavior:** -A new plugin agent (`pr-review:ado-fetcher`) accepts PR URL components and returns a single structured context block. All other agents and the orchestrator consume this block rather than making their own ADO calls. The agent is purely read-only — it performs no write operations. - -**Key interfaces:** - -- Input: org URL, project, PR ID, optional prior iteration ID (passed in for re-review) -- Output: structured context block — PR metadata, latest iteration ID, latest commit SHA, changed files list, raw diff, work-item IDs list -- The agent must handle zero-iteration PRs and already-merged PRs gracefully - -**Acceptance criteria:** - -- [x] The agent accepts PR URL components and returns a structured context block -- [x] The context block includes PR metadata, latest iteration ID, latest commit SHA, changed files list, and raw diff -- [x] The context block includes the work-item IDs linked to the PR (empty list if none) -- [x] The agent handles the case where no iterations are returned (defaults gracefully) -- [x] The agent handles PRs that are already merged (continues without error) -- [x] The agent contains no write operations — it is purely a read agent - -**Out of scope:** - -- Any ADO write operations -- Doc Context fetching (that stays with the Doc Context Orchestrator) -- GitHub or GitLab platform support diff --git a/docs/issues/pr-review-orchestrator-split/02-create-ado-writer-agent.md b/docs/issues/pr-review-orchestrator-split/02-create-ado-writer-agent.md deleted file mode 100644 index ac545a3a..00000000 --- a/docs/issues/pr-review-orchestrator-split/02-create-ado-writer-agent.md +++ /dev/null @@ -1,72 +0,0 @@ -# Create ADO Writer agent - -**Status:** resolved -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-orchestrator-split/PRD.md` - -## What to build - -Create a new plugin agent (`pr-review:ado-writer`) that encapsulates all Azure DevOps write-back operations for a PR review. The agent receives: PR context (org URL, project, repo ID, PR ID, latest iteration ID, summary thread ID), a list of compact findings, and a mode flag (first-review or re-review). - -For each finding it posts a new Inline Comment thread to ADO. After all findings are posted it posts the Review Summary on first-review, or a delta reply to the existing summary thread on re-review. As its final action it posts the completion marker reply to the summary thread. - -The compact finding schema the agent accepts: `{ severity, filePath, startLine, endLine, title, body }`. Every comment posted must end with the canonical Bot Signature trailer `---\n🤖 *Reviewed by Claude Code* — Iteration N`. - -This agent is used by both first-review and re-review modes. It is not invoked in pre-PR mode. - -## Acceptance criteria - -- [x] The agent posts one Inline Comment thread per finding at the correct file path and line range -- [x] Each posted comment ends with the canonical Bot Signature including the iteration number -- [x] On first-review, the agent posts a full Review Summary as a new general thread -- [x] On re-review with at least one new finding, the agent posts a delta reply to the existing summary thread -- [x] On re-review with zero new findings, the agent skips the summary reply -- [x] The agent posts a completion marker reply (`✅ Review complete — Iteration N`) to the summary thread as its final action -- [x] If `threadContext` is rejected by ADO (file not in diff), the agent retries without `threadContext` (general comment fallback) -- [x] The agent returns the final `SUMMARY_THREAD_ID` and `FINDINGS_POSTED` count to the caller - -## Blocked by - -None — can start immediately. - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Create the `pr-review:ado-writer` agent that encapsulates all ADO write-back operations for a PR review. - -**Current behavior:** -ADO write operations (posting Inline Comment threads, patching thread status, posting the Review Summary, posting the completion marker) are inline shell commands in `review-pr.md`. There is no dedicated agent for write-back. - -**Desired behavior:** -A new plugin agent (`pr-review:ado-writer`) receives a PR context block, a compact findings list, a mode flag, and an optional existing summary thread ID. It posts all Inline Comments, the Review Summary (or delta reply on re-review), and the completion marker. Every comment ends with the canonical Bot Signature. - -**Key interfaces:** - -- Input: PR context (org URL, project, repo ID, PR ID, latest iteration ID, summary thread ID), findings list as `{ severity, filePath, startLine, endLine, title, body }[]`, mode (`first-review` | `re-review`) -- Output: `{ summaryThreadId, findingsPosted }` returned to the caller -- Bot Signature constant: `🤖 *Reviewed by Claude Code*` prefix — must not change -- On `threadContext` rejection by ADO, retries without `threadContext` (general comment fallback) - -**Acceptance criteria:** - -- [ ] The agent posts one Inline Comment thread per finding at the correct file path and line range -- [ ] Each posted comment ends with the canonical Bot Signature including the iteration number -- [ ] On first-review, the agent posts a full Review Summary as a new general thread -- [ ] On re-review with at least one new finding, the agent posts a delta reply to the existing summary thread -- [ ] On re-review with zero new findings, the agent skips the summary reply -- [ ] The agent posts a completion marker reply to the summary thread as its final action -- [ ] If `threadContext` is rejected by ADO, the agent retries without `threadContext` -- [ ] The agent returns the final `summaryThreadId` and `findingsPosted` count - -**Out of scope:** - -- Reply posting for re-review classified threads (that is the Re-review Coordinator's responsibility) -- Pre-PR mode (no ADO calls in that mode) -- Reading or fetching any ADO data diff --git a/docs/issues/pr-review-orchestrator-split/03-create-re-review-coordinator-agent.md b/docs/issues/pr-review-orchestrator-split/03-create-re-review-coordinator-agent.md deleted file mode 100644 index 35ed7520..00000000 --- a/docs/issues/pr-review-orchestrator-split/03-create-re-review-coordinator-agent.md +++ /dev/null @@ -1,81 +0,0 @@ -# Create Re-review Coordinator agent - -**Status:** resolved -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-orchestrator-split/PRD.md` - -## What to build - -Create a new plugin agent (`pr-review:re-review-coordinator`) that owns the full re-review state machine. The agent receives the ADO Fetcher context block (which includes the raw diff) and the raw full PR threads JSON (the unfiltered ADO thread list). It parses the raw diff into diff hunks internally before calling `classify-thread` — the hunks file is a temp artefact managed inside the agent, not an input from the orchestrator. - -It performs in order: - -1. Calls the `detect-prior-review` Node.js module to identify prior bot threads and locate the summary thread. -2. Runs the partial-run check (looks for the completion marker for the prior iteration in the summary thread). Falls back to first-review mode if the marker is absent. -3. If no new revisions exist since the prior review (prior iteration ID equals latest iteration ID), prints outstanding pending threads to the console and exits early — no ADO writes. -4. Calls `classify-thread` on each prior thread against the diff hunks. -5. For each new finding passed in, calls `match-finding` to look for a matching prior thread. -6. Based on classification, posts replies to prior threads: acknowledges disputes, confirms resolutions (and PATCHes thread status to fixed), adds new evidence to pending threads with new information, skips pending threads with no new evidence, ignores obsolete threads. -7. Returns the classification counts (addressed, disputed, pending, obsolete), the fresh findings list (`freshFindings[]` — only unmatched findings; matched findings are consumed and not returned), and an `earlyExit` flag. `earlyExit` is `true` only on the no-new-revisions path (step 3); it is `false` on all other paths including normal completion with zero fresh findings. - -The four Node.js modules (`detect-prior-review`, `classify-thread`, `match-finding`, `parse-signature`) remain in `scripts/re-review/` unchanged. This agent calls them via `node --input-type=module` inline scripts, exactly as the current `review-pr.md` does. - -## Acceptance criteria - -- [ ] The agent correctly detects prior bot threads using the `detect-prior-review` module -- [ ] The agent falls back to first-review mode when no completion marker is found for the prior iteration -- [ ] The agent exits early (console output only, no ADO writes) when prior and latest iteration IDs are identical, and returns `earlyExit: true` -- [ ] The agent classifies all prior threads using the `classify-thread` module -- [ ] The agent matches new findings to prior threads using the `match-finding` module with ±3-line drift tolerance -- [ ] The agent posts a dispute acknowledgement reply to disputed threads including the ADO nudge -- [ ] The agent posts a resolution confirmation reply and PATCHes status to fixed for addressed threads -- [ ] The agent posts a new-evidence reply to pending threads that have new analysis; skips pending threads with no new evidence -- [ ] The agent returns classification counts (addressed, disputed, pending, obsolete), the unmatched (fresh) findings list, and the `earlyExit` flag -- [ ] The existing re-review module unit tests (`detect-prior-review`, `classify-thread`, `match-finding`, `parse-signature`) pass unchanged - -## Blocked by - -None — can start immediately. - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Create the `pr-review:re-review-coordinator` agent that owns the full re-review state machine. - -**Current behavior:** -The re-review state machine (prior thread detection, partial-run check, Thread Classification, finding matching, reply/resolution posting) lives inline in `review-pr.md` across Steps 3.5–10-Path-B. It is loaded on every invocation regardless of mode. - -**Desired behavior:** -A new plugin agent (`pr-review:re-review-coordinator`) receives the ADO Fetcher context block (which includes the raw diff) and the raw full PR threads JSON (unfiltered). It calls `detect-prior-review` internally to identify bot threads, parses the raw diff into diff hunks internally, then runs the full re-review state machine, posts classified replies directly to ADO, and returns classification counts plus the list of unmatched (fresh) findings for the ADO Writer to post as new threads. The four existing Node.js modules (`detect-prior-review`, `classify-thread`, `match-finding`, `parse-signature`) are called from this agent unchanged. - -**Key interfaces:** - -- Input: ADO Fetcher context block (includes raw diff), raw full PR threads JSON (captured by the orchestrator during mode detection via `az repos pr thread list` — not re-fetched; `detect-prior-review` filters this list inside the Coordinator), new findings list, Bot Signature prefix constant -- The Coordinator parses the raw diff into diff hunks internally; this is not an orchestrator concern -- Output: `{ addressed, disputed, pending, obsolete, freshFindings[], earlyExit }` — fresh findings are those with no matching prior thread; `earlyExit: true` signals the no-new-revisions path to the orchestrator -- The agent calls the four Node.js modules via `node --input-type=module` inline scripts (same pattern as current `review-pr.md`) -- Early-exit path: when prior iteration ID equals latest iteration ID, prints pending threads to console and returns `{ earlyExit: true, freshFindings: [], addressed: 0, disputed: 0, pending: N, obsolete: 0 }` — all count fields are always present; the orchestrator must skip the ADO Writer entirely when `earlyExit: true` - -**Acceptance criteria:** - -- [ ] The agent correctly detects prior bot threads using the `detect-prior-review` module -- [ ] The agent falls back to first-review mode when no completion marker is found for the prior iteration -- [ ] The agent exits early when prior and latest iteration IDs are identical (console output only, no ADO writes), returning `earlyExit: true` -- [ ] The agent classifies all prior threads using the `classify-thread` module -- [ ] The agent matches new findings to prior threads using `match-finding` with ±3-line drift tolerance -- [ ] The agent posts dispute acknowledgement, resolution confirmation, and new-evidence replies appropriately -- [ ] The agent returns classification counts (addressed, disputed, pending, obsolete), the unmatched fresh findings list, and the `earlyExit` flag -- [ ] The four re-review module unit tests pass unchanged after this issue is implemented - -**Out of scope:** - -- Posting new Inline Comment threads for fresh findings (ADO Writer's responsibility) -- Posting the Review Summary or completion marker (ADO Writer's responsibility) -- First-review or pre-PR mode logic diff --git a/docs/issues/pr-review-orchestrator-split/04-refactor-orchestrator.md b/docs/issues/pr-review-orchestrator-split/04-refactor-orchestrator.md deleted file mode 100644 index 3a150b76..00000000 --- a/docs/issues/pr-review-orchestrator-split/04-refactor-orchestrator.md +++ /dev/null @@ -1,83 +0,0 @@ -# Refactor review-pr.md to thin orchestrator - -**Status:** resolved -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-orchestrator-split/PRD.md` - -## What to build - -Refactor `review-pr.md` into a thin orchestrator of approximately 200 lines. The orchestrator: - -1. Validates prerequisites in a mode-aware way: always checks `git` availability and `pr-review-toolkit`; checks Azure CLI and `azure-devops` extension only when a PR URL is present (Pre-PR mode requires no ADO credentials). -2. Parses `$ARGUMENTS` for a PR URL. If absent, sets mode to Pre-PR; if present, proceeds to detection. -3. For PR URL cases: makes a lightweight ADO thread-list call directly (not via the ADO Fetcher) using `az repos pr thread list` (not `az devops invoke`) to check for a prior Bot Signature, determining mode and extracting the prior iteration ID if found. The full thread list from this call is captured and passed forward to the Re-review Coordinator in step 6 — no second ADO thread-list call is made. -4. Logs the detected mode clearly before delegating. -5. For First-review: invokes the ADO Fetcher agent (passing org URL, project, PR ID), then runs Doc Context Orchestrator + review aspect agents in parallel, collects compact findings, delegates write-back to the ADO Writer agent. -6. For Re-review: invokes the ADO Fetcher agent (passing org URL, project, PR ID, and prior iteration ID), then runs Doc Context Orchestrator + review aspect agents in parallel. Once all review aspect agents return their findings, passes the complete findings list and prior-thread data to the Re-review Coordinator agent (which handles replies). If the Coordinator returns `earlyExit: true` (no new revisions), the orchestrator stops — ADO Writer is not called. Otherwise passes fresh findings to the ADO Writer agent. -7. Pre-PR mode is a stub at this slice — it detects the mode and prints a "Pre-PR mode not yet implemented" message. Full Pre-PR behaviour is delivered in issue 05. - -The `review-pr.md` file must contain no `az devops invoke` shell commands after this refactor — the three focused agents own all data-fetch and write-back ADO operations. The one allowed inline ADO call is the mode-detection `az repos pr thread list` in step 3, which is an orchestration concern, not a data-fetch or write-back operation. The Bot Signature constants and detection prefix are unchanged. All existing re-review module unit tests must pass. - -## Acceptance criteria - -- [ ] `review-pr.md` is ≤ 200 lines and contains no `az devops invoke` calls -- [ ] Prerequisite checks are mode-aware: Azure CLI and `azure-devops` extension are not required in Pre-PR mode (no PR URL provided) -- [ ] The orchestrator logs the detected mode (Pre-PR / First-review / Re-review) before delegating -- [ ] First-review mode produces the same ADO comment output as the pre-refactor command (full Review Summary + Inline Comments + completion marker) -- [ ] Re-review mode produces the same ADO comment output as the pre-refactor command (classified replies + fresh findings + delta summary + completion marker) -- [ ] Pre-PR mode prints a clear "not yet implemented" message and exits cleanly -- [ ] The ADO Fetcher and Doc Context Orchestrator still run in the correct order (Fetcher first, then both Doc Context and review agents can overlap) -- [ ] The Bot Signature format and detection prefix are unchanged -- [ ] `pnpm test` passes (all re-review module unit tests green) -- [ ] `pnpm format` produces no diff - -## Blocked by - -- `docs/issues/pr-review-orchestrator-split/01-create-ado-fetcher-agent.md` -- `docs/issues/pr-review-orchestrator-split/02-create-ado-writer-agent.md` -- `docs/issues/pr-review-orchestrator-split/03-create-re-review-coordinator-agent.md` - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Refactor `review-pr.md` into a thin orchestrator (~200 lines) that delegates to the three focused agents. - -**Current behavior:** -`review-pr.md` is ~1000 lines, mixing orchestration logic, ADO shell commands, re-review state machine, and write-back in a single file. Every invocation loads the entire file into context. - -**Desired behavior:** -`review-pr.md` shrinks to ~200 lines containing: mode-aware prerequisite validation (ADO tooling skipped for Pre-PR), argument parsing, mode detection (Pre-PR / First-review / Re-review), and delegation calls to the ADO Fetcher, Re-review Coordinator, and ADO Writer agents. The file contains no `az devops invoke` calls. Pre-PR mode is a stub that prints "not yet implemented" — full implementation is in issue 05. - -**Key interfaces:** - -- Mode detection sequence: no URL → Pre-PR; URL → orchestrator calls `az repos pr thread list` (not `az devops invoke`) → no Bot Signature → First-review; Bot Signature found → extract prior iteration ID → Re-review -- Bot Signature detection prefix: `🤖 *Reviewed by Claude Code*` — must not change -- ADO Fetcher agent invocation: passes org URL, project, PR ID (plus prior iteration ID in re-review) -- Re-review Coordinator agent invocation (re-review only): called after all review aspect agents complete; passes ADO Fetcher context + full PR threads JSON (captured from mode detection in step 3, not re-fetched) + new findings list; returns `{ earlyExit, freshFindings[], addressed, disputed, pending, obsolete }` -- If Coordinator returns `earlyExit: true`, orchestrator stops — ADO Writer is not called -- ADO Writer agent invocation: passes PR context + fresh findings list + mode (`"first-review"` | `"re-review"`); the mode determines whether ADO Writer posts a new Review Summary (first-review) or a delta reply (re-review) - -**Acceptance criteria:** - -- [ ] `review-pr.md` is ≤ 200 lines and contains no `az devops invoke` calls -- [ ] Prerequisite checks are mode-aware: Azure CLI and `azure-devops` extension are not required in Pre-PR mode -- [ ] The orchestrator logs the detected mode before delegating -- [ ] First-review produces the same ADO output as pre-refactor -- [ ] Re-review produces the same ADO output as pre-refactor -- [ ] Pre-PR mode prints "not yet implemented" and exits cleanly -- [ ] ADO Fetcher runs before Doc Context Orchestrator (Fetcher provides work-item IDs); Doc Context and review agents may overlap -- [ ] Bot Signature format and detection prefix unchanged -- [ ] `pnpm test` passes; `pnpm format` produces no diff - -**Out of scope:** - -- Full Pre-PR mode implementation (issue 05) -- Compact sub-agent output guidance (issue 06) -- Version bump (issue 07) diff --git a/docs/issues/pr-review-orchestrator-split/05-add-pre-pr-mode.md b/docs/issues/pr-review-orchestrator-split/05-add-pre-pr-mode.md deleted file mode 100644 index 318c3451..00000000 --- a/docs/issues/pr-review-orchestrator-split/05-add-pre-pr-mode.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add Pre-PR mode - -**Status:** resolved -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-orchestrator-split/PRD.md` - -## What to build - -Implement the Pre-PR operating mode in the orchestrator. When `/pr-review:review-pr` is invoked without a PR URL, the command: - -1. Diffs the current local branch against its upstream target (e.g. `git diff origin/...HEAD`). -2. Reads key changed files (same skip-list as today: generated files, serialization YAMLs, etc.). -3. Launches the same `pr-review-toolkit` review aspect agents as the ADO modes, passing the local diff and file contents. Doc Context is skipped (no work items or Confluence pages to fetch without a PR). -4. Aggregates findings and presents them in the Claude interface as a structured list (severity, file, line, title, body) — no ADO calls are made. -5. Prints a clear completion message when done. - -No ADO credentials are required and no ADO calls are made in this mode. The pre-PR Review uses the same review aspect agent selection logic as ADO modes (aspect filter from `$ARGUMENTS` applies). - -## Acceptance criteria - -- [x] Running the command without a URL enters Pre-PR mode with a console message confirming the mode -- [x] The diff used is the local branch diff against its upstream target -- [x] Review aspect agents receive the local diff and changed file contents -- [x] Findings are presented in the Claude interface with severity, file path, line range, title, and body -- [x] No ADO API calls are made in this mode -- [x] The aspect filter argument (e.g. `code`, `errors`, `all`) is respected in pre-PR mode -- [x] `pnpm test` passes; `pnpm format` produces no diff - -## Blocked by - -- `docs/issues/pr-review-orchestrator-split/04-refactor-orchestrator.md` - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Implement Pre-PR mode — review local branch diff without a PR URL, no ADO write-back. - -**Current behavior:** -The orchestrator stub from issue 04 prints "Pre-PR mode not yet implemented" and exits. No review occurs without a PR URL. - -**Desired behavior:** -When the command is invoked without a URL, it diffs the local branch against its upstream target, runs the same `pr-review-toolkit` review aspect agents as ADO modes, and presents compact structured findings in the Claude interface. No ADO credentials are required or used. Doc Context gathering is skipped (no work items to fetch). The aspect filter argument applies. - -**Key interfaces:** - -- Diff source: `git diff origin/...HEAD` -- File skip-list: same as current (generated files, serialization YAMLs, `*.g.cs`, `swagger.md`) -- Review aspect agents: same selection logic as ADO modes; aspect filter from `$ARGUMENTS` applies -- Finding presentation: compact structured list — severity, file path, line range, title, body — in the Claude interface -- No ADO Fetcher, Re-review Coordinator, or ADO Writer agents are invoked - -**Acceptance criteria:** - -- [ ] Running the command without a URL enters Pre-PR mode with a console message confirming the mode -- [ ] The diff used is the local branch diff against its upstream target -- [ ] Review aspect agents receive the local diff and changed file contents -- [ ] Findings are presented in the Claude interface with severity, file path, line range, title, and body -- [ ] No ADO API calls are made in this mode -- [ ] The aspect filter argument is respected -- [ ] `pnpm test` passes; `pnpm format` produces no diff - -**Out of scope:** - -- Posting findings to ADO -- Doc Context gathering in pre-PR mode -- Any change to first-review or re-review behaviour diff --git a/docs/issues/pr-review-orchestrator-split/06-compact-subagent-output.md b/docs/issues/pr-review-orchestrator-split/06-compact-subagent-output.md deleted file mode 100644 index 7eb42921..00000000 --- a/docs/issues/pr-review-orchestrator-split/06-compact-subagent-output.md +++ /dev/null @@ -1,65 +0,0 @@ -# Add compact sub-agent output guidance to the review-agent launch step - -**Status:** resolved -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-orchestrator-split/PRD.md` - -## What to build - -Update the step in the thin orchestrator that launches `pr-review-toolkit` review aspect agents to instruct them to return compact structured findings rather than prose with embedded code quotes. (The thin orchestrator produced by issue 04 will have a different step numbering than the pre-refactor monolith — find the step by its purpose: the one that spawns the parallel review agents.) - -The prompt addition instructs each agent to return a JSON array where each element has: `severity` (critical / important / minor), `filePath` (leading `/`, forward slashes), `startLine` (integer), `endLine` (integer), `title` (one line, ≤ 80 chars), `body` (one paragraph — the exact text to post as the ADO or local-interface comment, no code quotes, no repeated context). The reasoning and supporting analysis should stay inside the agent's own context, not appear in the return value. - -No changes are made to `pr-review-toolkit` agent definitions — this guidance lives only in the orchestrator's prompt to the agents. - -## Acceptance criteria - -- [ ] The review-agent launch step explicitly requests structured JSON findings with the six required fields -- [ ] The prompt instructs agents to omit code quotes and prose reasoning from the return value -- [ ] The ADO Writer agent correctly receives and processes the structured finding schema -- [ ] Pre-PR mode findings are also presented using the same structured schema -- [ ] No `pr-review-toolkit` agent definition files are modified -- [ ] `pnpm format` produces no diff - -## Blocked by - -- `docs/issues/pr-review-orchestrator-split/04-refactor-orchestrator.md` - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Update the review-agent launch step in the thin orchestrator to request compact structured findings from review aspect agents. - -**Current behavior:** -Review aspect agents return prose findings with embedded code quotes and explanatory text. The full prose flows back into the parent context as tool call results, contributing to token budget pressure. - -**Desired behavior:** -The step in the thin orchestrator that spawns parallel review agents explicitly instructs each `pr-review-toolkit` review aspect agent to return a JSON array of findings. Locate this step by purpose — it is the one that launches the review agents in parallel — not by number (step numbering changed after the issue 04 refactor). Each element: `severity` (critical / important / minor), `filePath`, `startLine`, `endLine`, `title` (≤ 80 chars), `body` (one paragraph, no code quotes). Reasoning stays inside the agent's own context. No `pr-review-toolkit` agent definition files are modified. - -**Key interfaces:** - -- The structured finding schema: `{ severity, filePath, startLine, endLine, title, body }` -- Guidance location: the review-agent launch step in the orchestrator only — not in toolkit agent definitions -- Both ADO modes and Pre-PR mode use this schema - -**Acceptance criteria:** - -- [ ] The review-agent launch step requests structured JSON findings with all six required fields -- [ ] The prompt instructs agents to omit code quotes and prose reasoning from the return value -- [ ] The ADO Writer agent correctly receives and processes the structured schema -- [ ] Pre-PR mode findings are presented using the same schema -- [ ] No `pr-review-toolkit` agent definition files are modified -- [ ] `pnpm format` produces no diff - -**Out of scope:** - -- Enforcing schema validation on agent output -- Changing the toolkit agent definitions -- Token-budget monitoring or benchmarking diff --git a/docs/issues/pr-review-orchestrator-split/07-version-bump-and-release.md b/docs/issues/pr-review-orchestrator-split/07-version-bump-and-release.md deleted file mode 100644 index 44a5b8b5..00000000 --- a/docs/issues/pr-review-orchestrator-split/07-version-bump-and-release.md +++ /dev/null @@ -1,63 +0,0 @@ -# Version bump and CHANGELOG - -**Status:** resolved -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-orchestrator-split/PRD.md` - -## What to build - -Bump the `pr-review` plugin version (minor bump — new features added) and add a dated CHANGELOG entry covering the orchestrator split, the three new agents, pre-PR mode, and compact sub-agent output. - -Run `pnpm --filter pr-review bump minor` to update both `plugin.json` and `marketplace.json`. Add a `[Unreleased]` → versioned entry to `CHANGELOG.md` following the existing format. Run `pnpm --filter pr-review verify:changelog` to confirm the entry passes validation. - -Update `CLAUDE.md` to reflect the new architecture: remove the claim that "the entire behaviour of the plugin lives in `commands/review-pr.md`", add the `.agents/` directory to the repository layout, and update the command conventions section to note that ADO calls now live in the three focused agents (ADO Fetcher, Re-review Coordinator, ADO Writer) rather than inline in the command. - -## Acceptance criteria - -- [ ] `plugin.json` and `marketplace.json` both reflect the new minor version -- [ ] `CHANGELOG.md` has a dated entry for the new version describing the orchestrator split, three new agents, pre-PR mode, and compact output guidance -- [ ] `pnpm --filter pr-review verify:changelog` passes -- [ ] `CLAUDE.md` updated: "entire behaviour lives in `commands/review-pr.md`" claim removed, `.agents/` directory added to layout, command conventions updated to reflect ADO calls live in the focused agents -- [ ] `pnpm format` produces no diff - -## Blocked by - -- `docs/issues/pr-review-orchestrator-split/05-add-pre-pr-mode.md` -- `docs/issues/pr-review-orchestrator-split/06-compact-subagent-output.md` - ---- - -## Agent Brief - -> _This was generated by AI during triage._ - -**Category:** enhancement -**Summary:** Bump `pr-review` to the next minor version and add a CHANGELOG entry for the orchestrator split. - -**Current behavior:** -`plugin.json` and `marketplace.json` carry the current version. `CHANGELOG.md` has no entry for this feature set. - -**Desired behavior:** -Run `pnpm --filter pr-review bump minor` to update both version files atomically. Add a dated entry to `CHANGELOG.md` under the new version number describing: orchestrator split, three new focused agents (ADO Fetcher, Re-review Coordinator, ADO Writer), pre-PR mode, and compact sub-agent output guidance. Verify with `pnpm --filter pr-review verify:changelog`. - -**Key interfaces:** - -- `pnpm --filter pr-review bump minor` — updates `plugin.json` and `marketplace.json` -- `CHANGELOG.md` entry format — must match the existing dated em-dash format enforced by `verify:changelog` -- `pnpm --filter pr-review verify:changelog` — must pass - -**Acceptance criteria:** - -- [ ] `plugin.json` and `marketplace.json` both reflect the new minor version -- [ ] `CHANGELOG.md` has a dated entry for the new version covering all four feature areas -- [ ] `pnpm --filter pr-review verify:changelog` passes -- [ ] `CLAUDE.md` updated to reflect the three-agent architecture -- [ ] `pnpm format` produces no diff - -**Out of scope:** - -- Publishing to the marketplace (manual step) -- Creating the git tag (handled by the release workflow on `main`) diff --git a/docs/issues/pr-review-pre-pr-default-branch-override/01-env-var-override.md b/docs/issues/pr-review-pre-pr-default-branch-override/01-env-var-override.md deleted file mode 100644 index aec87183..00000000 --- a/docs/issues/pr-review-pre-pr-default-branch-override/01-env-var-override.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: pre-pr: env var override for default-branch fallback chain -created: 2026-05-14 ---- - -**Status:** needs-triage -**Category:** enhancement -**Plugin:** `apps/claude-code/pr-review` -**Depends on:** orchestrator-split PR merged - -## Problem Statement - -`detect-default-branch.mjs` uses a Gitflow-aware fallback chain (`remote-show → develop → main → master → none`) when the remote is unreachable. Repos that intentionally use `main` as their integration branch but have a stale `origin/develop` ref will silently diff against `develop` with no escape hatch — the user has no way to override the choice. - -## Solution - -Add an environment variable override (e.g. `PR_REVIEW_DEFAULT_BRANCH`) that, when set, short-circuits the fallback chain and uses the specified branch directly. A Notice should still be emitted if the override bypasses a `remote-show` that would have returned a different result. - -## Acceptance criteria - -- `PR_REVIEW_DEFAULT_BRANCH=main` forces the pre-PR diff to use `main` regardless of what `remote-show` or the fallback chain would have returned -- When the env var is set, the fallback chain is not consulted -- An info-level Notice is emitted when the env var is used, so the invoker knows the override is active -- Existing behavior (no env var set) is unchanged -- Unit tests cover the override path diff --git a/docs/issues/pr-review-rereview/01-normalize-bot-signature.md b/docs/issues/pr-review-rereview/01-normalize-bot-signature.md deleted file mode 100644 index 1d473a3a..00000000 --- a/docs/issues/pr-review-rereview/01-normalize-bot-signature.md +++ /dev/null @@ -1,30 +0,0 @@ -# Normalize bot signature - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Update every signature occurrence in `commands/review-pr.md` to a single canonical form: `🤖 *Reviewed by Claude Code* — Iteration N` (asterisk italics, iteration suffix). The detection substring remains `🤖 *Reviewed by Claude Code*` (prefix match) so it stays backwards-compatible with any legacy comments already on live PRs. - -Two types of locations must be updated end-to-end: - -- **Runtime-emitted** locations (inside JSON payloads written to `/tmp/` in Steps 10 and 11) must emit the full `— Iteration {LATEST_ITERATION_ID}` suffix. -- **Documentation/example** locations (the summary structure markdown block) must switch from underscore to asterisk italics, using a `{N}` placeholder. - -A note is added to the Notes section documenting the prefix/full-form distinction so future editors do not break detection. - -## Acceptance criteria - -- [ ] `grep -nF '🤖 _Reviewed by Claude Code_' commands/review-pr.md` → 0 matches -- [ ] `grep -nF '🤖 *Reviewed by Claude Code*' commands/review-pr.md` → matches at every signature location -- [ ] All runtime-emitted signatures include `— Iteration` followed by a variable reference -- [ ] Notes section documents the invariant prefix and the full emitted form - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/pr-review-rereview/02-detect-prior-review.md b/docs/issues/pr-review-rereview/02-detect-prior-review.md deleted file mode 100644 index 85aa13f2..00000000 --- a/docs/issues/pr-review-rereview/02-detect-prior-review.md +++ /dev/null @@ -1,37 +0,0 @@ -# Detect prior review + extract parse-signature and detect-prior-review modules - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Add a new Step 3.5 to `commands/review-pr.md` that fetches all PR comment threads from ADO, identifies bot-authored threads by signature prefix (no `createdBy` identity check), tags the summary thread, and parses the prior iteration ID from the newest bot comment's signature. - -Two `scripts/re-review/` modules are extracted alongside the command changes so the logic is unit-testable in isolation: - -**`parse-signature.mjs`** — pure function. Given a comment body string, returns `{ iterationId: number }` if the canonical signature suffix `— Iteration N` is present, or `null` for legacy/non-bot comments. - -**`detect-prior-review.mjs`** — given the full array of already-fetched ADO thread objects, returns `{ isRereview, priorThreads, summaryThread, priorIterationId }`. Identifies bot threads by prefix match. Tags the summary thread (`isSummaryThread = true`) when a general thread's first comment contains the summary heading. Stores full `{start: {line, offset}, end: {line, offset}}` ranges per thread, not flat line numbers. - -Pagination in the command: loop on `continuationToken` until all threads are fetched before calling `detect-prior-review.mjs`. - -The command logs: `Detected N prior Claude Code threads — re-review mode ON` (or `OFF`). - -Each module ships with a `node:test` test file covering its core scenarios using JSON fixtures. - -## Acceptance criteria - -- [ ] Step 3.5 runs unconditionally and logs the detection summary line -- [ ] All threads fetched before detection (pagination loop on `continuationToken`) -- [ ] `isSummaryThread` set on the correct general thread (or no thread if none exists) -- [ ] Thread ranges stored as `{start: {line, offset}, end: {line, offset}}` -- [ ] `parse-signature.mjs` returns `{ iterationId }` for current-format comments and `null` for legacy/non-bot -- [ ] `pnpm --filter pr-review test` passes - -## Blocked by - -`docs/issues/pr-review-rereview/01-normalize-bot-signature.md` diff --git a/docs/issues/pr-review-rereview/03-target-latest-iteration.md b/docs/issues/pr-review-rereview/03-target-latest-iteration.md deleted file mode 100644 index c07aa736..00000000 --- a/docs/issues/pr-review-rereview/03-target-latest-iteration.md +++ /dev/null @@ -1,33 +0,0 @@ -# Target latest PR iteration - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Replace all hardcoded `iterationId=1` uses in `commands/review-pr.md` with a dynamic lookup of the latest iteration ID. There are two locations: the file-list call (Step 4, `pullRequestIterationChanges`) and the diff step (Step 5). Both must use `LATEST_ITERATION_ID`. - -The implementation also resolves `PRIOR_ITERATION_ID` and both commit IDs for use by the incremental diff step: - -- Fetch all PR iterations via `pullRequestIterations`; select the highest `id` as `LATEST_ITERATION_ID` using `jq 'max_by(.id)'`. -- Capture `sourceRefCommit.commitId` for the latest iteration as `LATEST_COMMIT_ID`. -- When `IS_REREVIEW=true`: use `PRIOR_ITERATION_ID` (parsed from the prior comment's signature by `parse-signature.mjs`; timestamp fallback for legacy comments) to look up that iteration's `sourceRefCommit.commitId` as `PRIOR_COMMIT_ID`. -- Export `LATEST_COMMIT_ID` and `PRIOR_COMMIT_ID` for the next step. - -Update the `CLAUDE.md` rule: remove the `iterationId=1` guidance; replace with a description of the latest-iteration approach and the `PRIOR_ITERATION_ID` fallback. - -## Acceptance criteria - -- [ ] `grep -n 'iterationId=1' commands/review-pr.md` → 0 matches -- [ ] Step 4 file list and Step 5 diff both reference `LATEST_ITERATION_ID` -- [ ] CLI logs the resolved iteration ID on every run -- [ ] `PRIOR_COMMIT_ID` resolved from signature suffix when available; timestamp fallback for legacy -- [ ] `CLAUDE.md` rule updated - -## Blocked by - -`docs/issues/pr-review-rereview/02-detect-prior-review.md` diff --git a/docs/issues/pr-review-rereview/04-incremental-diff-baseline.md b/docs/issues/pr-review-rereview/04-incremental-diff-baseline.md deleted file mode 100644 index d4504c2c..00000000 --- a/docs/issues/pr-review-rereview/04-incremental-diff-baseline.md +++ /dev/null @@ -1,35 +0,0 @@ -# Incremental diff baseline - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Branch Step 5 of `commands/review-pr.md` on `IS_REREVIEW` so re-reviews only diff the new commits, not the entire branch. - -When `IS_REREVIEW=true`: - -- Diff between `PRIOR_COMMIT_ID` and `LATEST_COMMIT_ID` (from the previous issue). -- If both commit IDs are identical (no new pushes since last review): print `No new commits since last review.`, list all `pending` threads from `PRIOR_THREADS` (file path and line range per thread) to the console, then exit cleanly without proceeding to Steps 6–11. -- Attempt `git fetch origin {PRIOR_COMMIT_ID}` before diffing; if the fetch fails (force-push / garbage collection), fall back to full diff with a warning that includes both commit IDs: `Warning: prior commit {PRIOR_COMMIT_ID} unreachable; latest commit {LATEST_COMMIT_ID} — falling back to full diff.` -- If `PRIOR_COMMIT_ID` is null (legacy comment), fall back to full diff with a simpler warning. - -Export diff hunk boundaries (file path, start line, end line per hunk) as structured JSON to `$TMPDIR` for consumption by the classify-thread module. - -When `IS_REREVIEW=false`: behaviour is unchanged from before this issue. - -## Acceptance criteria - -- [ ] First-time review diff behaviour unchanged -- [ ] Re-review diffs only between `PRIOR_COMMIT_ID` and `LATEST_COMMIT_ID` -- [ ] Early exit on identical commits: pending threads listed to console; no ADO writes -- [ ] Force-push fallback warning includes both commit IDs -- [ ] Diff hunk boundaries exported as structured JSON to `$TMPDIR` - -## Blocked by - -`docs/issues/pr-review-rereview/03-target-latest-iteration.md` diff --git a/docs/issues/pr-review-rereview/05-classify-existing-threads.md b/docs/issues/pr-review-rereview/05-classify-existing-threads.md deleted file mode 100644 index 95b2a671..00000000 --- a/docs/issues/pr-review-rereview/05-classify-existing-threads.md +++ /dev/null @@ -1,39 +0,0 @@ -# Classify existing threads + extract classify-thread module - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Add thread classification to the re-review flow and extract the logic into a standalone `scripts/re-review/classify-thread.mjs` module that the command calls via Bash. - -**`classify-thread.mjs`** — pure function. Given a prior thread object and the diff hunk JSON from the previous step, returns one of four states: - -- `addressed` — ADO thread status is one of `fixed` (2), `wontFix` (3), `closed` (4), or `byDesign` (5), **or** status is `active` (1) or `pending` (6) and the thread's line range (`[start.line, end.line]`) intersects a changed hunk (`max(thread.start, hunk.start) ≤ min(thread.end, hunk.end)`). ADO `pending` (6) is treated like `active` — diff intersection is required. Line numbers only — offsets not used in intersection logic. -- `disputed` — status is `active` and at least one comment in the thread does not contain the signature prefix `🤖 *Reviewed by Claude Code*`. No `createdBy` identity check. -- `pending` — status is `active` and no comment lacks the signature prefix. -- `obsolete` — the thread's `filePath` is not present in the diff at all. - -The summary thread (`isSummaryThread = true`) is skipped — classification does not apply to it. - -After classifying all threads, the command prints a one-line summary: `Threads: N addressed, N disputed, N pending, N obsolete`. - -The module ships with a `node:test` test file covering all four states, multi-line range intersection, general threads (filePath null), and ADO status codes. - -## Acceptance criteria - -- [ ] Every non-summary prior thread receives exactly one classification -- [ ] Summary thread skipped -- [ ] Classification summary line printed before Step 6 -- [ ] `classify-thread.mjs` returns correct state for all four scenarios -- [ ] ADO status codes 2–5 (fixed, wontFix, closed, byDesign) auto-map to `addressed`; status 6 (ADO pending) requires diff intersection like `active` -- [ ] Human reply detection uses signature prefix only — no identity check -- [ ] `pnpm --filter pr-review test` passes - -## Blocked by - -`docs/issues/pr-review-rereview/02-detect-prior-review.md` diff --git a/docs/issues/pr-review-rereview/06-reply-to-threads.md b/docs/issues/pr-review-rereview/06-reply-to-threads.md deleted file mode 100644 index 71efb80d..00000000 --- a/docs/issues/pr-review-rereview/06-reply-to-threads.md +++ /dev/null @@ -1,49 +0,0 @@ -# Reply to threads + extract match-finding module + completion marker - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Branch Step 10 of `commands/review-pr.md` on `IS_REREVIEW` so re-reviews reply to existing threads instead of creating duplicates. Extract the matching logic into `scripts/re-review/match-finding.mjs`. - -**`match-finding.mjs`** — pure function. Given a finding (file path + line range) and the list of prior threads, returns the best-matching prior thread or null. Matching requires file path equality and line-range overlap (`max(finding.start, thread.start) ≤ min(finding.end, thread.end)`) with a ±3 line drift tolerance applied to both endpoints before the overlap test. - -**Reply actions per classification:** - -| Classification | Action | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -| `pending` (unchanged) | Skip — do not post | -| `pending` (new evidence) | Reply via `pullRequestThreadComments` with new evidence only | -| `disputed` | Reply acknowledging the author's point; include nudge to mark thread fixed in ADO | -| `addressed` | Reply `Resolved as of Iteration N — thanks!`; PATCH thread status to `fixed` via `pullRequestThreads` (body `{ "status": 2 }`) | -| `obsolete` | No action | - -New findings (no prior match): create a fresh thread as before; signature suffix carries the iteration number — no separate "Iteration N" header line needed. - -**`pending` general threads** (no filePath, not the summary thread): skip — same rule as inline pending. - -**Completion marker**: after all posts, post one final reply to the summary thread: `✅ Review complete — Iteration {LATEST_ITERATION_ID} ({N} findings posted)`. This is the last action of every successful run. Absence of this marker for the current iteration signals a partial prior run; on the next run, treat the current iteration as first-review mode. - -**PATCH concurrency**: if status PATCH returns 409 (author resolved mid-run), log and continue. - -## Acceptance criteria - -- [ ] No duplicate thread created when a matching prior thread exists -- [ ] All replies carry the canonical signature on their last line -- [ ] `addressed` threads PATCH status via `pullRequestThreads` (not `pullRequestThreadComments`) -- [ ] `disputed` replies include ADO nudge text -- [ ] `pending` threads skipped uniformly (inline and general) -- [ ] Completion marker is the final comment on every successful run -- [ ] Partial prior run detected on next run (no completion marker → first-review mode) -- [ ] `match-finding.mjs` returns correct match/null for overlap, drift, and no-match scenarios -- [ ] `pnpm --filter pr-review test` passes - -## Blocked by - -- `docs/issues/pr-review-rereview/04-incremental-diff-baseline.md` -- `docs/issues/pr-review-rereview/05-classify-existing-threads.md` diff --git a/docs/issues/pr-review-rereview/07-summary-comment-policy.md b/docs/issues/pr-review-rereview/07-summary-comment-policy.md deleted file mode 100644 index 4a99b889..00000000 --- a/docs/issues/pr-review-rereview/07-summary-comment-policy.md +++ /dev/null @@ -1,36 +0,0 @@ -# Summary comment policy on re-review - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Branch Step 11 of `commands/review-pr.md` so re-reviews never post a second full-length summary. Instead, when there is something to report, a compact delta reply is posted to the existing summary thread. - -**Behaviour by case:** - -- `IS_REREVIEW=false`: full summary posted in a new thread — unchanged from before. -- `IS_REREVIEW=true` and at least one of {new threads created, addressed replies, disputed replies}: post a reply to the existing summary thread (identified by `SUMMARY_THREAD_ID` from the detection step) with: - - Counts only: `X new findings, Y resolved, Z disputed, W pending` - - Bullet list of new finding titles linked to their threads - - No prose, no section headings beyond the title line -- `IS_REREVIEW=true` and nothing changed: post nothing at the summary level. -- Prior summary thread not found (deleted by human): fall back to first-review mode and post a new full summary. - -Track the action counters (new threads, addressed replies, disputed replies) during Step 10 and feed them into Step 11. The delta reply uses `pullRequestThreadComments` against `SUMMARY_THREAD_ID`. - -## Acceptance criteria - -- [ ] First-time review posts full summary in a new thread (regression check) -- [ ] Re-review with activity posts a delta reply to the existing summary thread — not a new thread -- [ ] Re-review with no activity posts nothing -- [ ] Delta reply contains counts and bullet list only — no prose paragraphs -- [ ] Fallback to full summary when prior summary thread is absent - -## Blocked by - -`docs/issues/pr-review-rereview/06-reply-to-threads.md` diff --git a/docs/issues/pr-review-rereview/08-test-fixture-suite.md b/docs/issues/pr-review-rereview/08-test-fixture-suite.md deleted file mode 100644 index cff6e5e8..00000000 --- a/docs/issues/pr-review-rereview/08-test-fixture-suite.md +++ /dev/null @@ -1,52 +0,0 @@ -# Complete test fixture suite - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Author the complete set of JSON fixture files and finalize the `node:test` suite so all four extracted modules are covered across all eleven fixture scenarios. Earlier issues include inline unit tests for each module's happy path; this issue completes the edge-case coverage and ensures all scenarios are represented as named fixtures. - -**Fixture files to create under `tests/fixtures/`:** - -| File | Scenario | -| ------------------------------- | --------------------------------------------------------------- | -| `threads-fresh-pr.json` | No prior bot threads | -| `threads-pending.json` | Bot threads, active status, no human replies | -| `threads-disputed.json` | Bot threads with human replies | -| `threads-addressed-status.json` | Bot threads with ADO status `fixed` | -| `threads-addressed-diff.json` | Bot threads, active status, line range in diff hunk | -| `threads-obsolete.json` | Bot threads on file not present in diff | -| `threads-partial-run.json` | Bot threads present, no completion marker for current iteration | -| `threads-paginated-p1.json` | First page (100 threads + `continuationToken`) | -| `threads-paginated-p2.json` | Second page (remaining threads, no token) | -| `diff-hunks-no-change.json` | Empty hunk set (identical commits) | -| `diff-hunks-with-changes.json` | Hunks covering a known line range | - -Fixture JSON shapes must match the ADO `pullRequestThreads` API response format (including `threadContext`, `comments`, `status`, `id` fields). - -**Test coverage to complete or add:** - -- `detect-prior-review.test.mjs`: paginated scenario (p1 + p2 combined), partial-run detection, summary thread tagging. -- `classify-thread.test.mjs`: multi-line range intersection, general thread edge cases, all ADO non-active status codes. -- `match-finding.test.mjs`: outside drift tolerance, multi-line finding vs single-line thread, no-match cases. -- `parse-signature.test.mjs`: iteration number boundary values, malformed suffix. - -No test may import `az` or make any network calls. - -## Acceptance criteria - -- [ ] All 11 fixture files present under `tests/fixtures/` -- [ ] `pnpm --filter pr-review test` passes with zero failures -- [ ] Every fixture scenario exercised by at least one test assertion -- [ ] Deleting any single fixture file causes at least one test to fail with a clear message - -## Blocked by - -- `docs/issues/pr-review-rereview/02-detect-prior-review.md` -- `docs/issues/pr-review-rereview/05-classify-existing-threads.md` -- `docs/issues/pr-review-rereview/06-reply-to-threads.md` diff --git a/docs/issues/pr-review-rereview/09-version-bump-and-release.md b/docs/issues/pr-review-rereview/09-version-bump-and-release.md deleted file mode 100644 index b178d894..00000000 --- a/docs/issues/pr-review-rereview/09-version-bump-and-release.md +++ /dev/null @@ -1,43 +0,0 @@ -# Version bump, README, CLAUDE.md, ADR 0009 - -**Status:** closed -**Category:** enhancement - -## Parent - -`docs/issues/pr-review-rereview/PRD.md` - -## What to build - -Finalise metadata, documentation, and release artefacts for the re-review feature. This is a HITL issue: the bump script and release PR require human review before merging. - -**Steps (in order):** - -1. **Add CHANGELOG entries.** Under `## [Unreleased]` in `CHANGELOG.md`, add bullets under `### Added` describing the re-review feature. Do this before running the bump script — the bump will fail verification if the versioned section only has `(none)` placeholders. - -2. **Check `.prettierignore`.** At the monorepo root, verify `**/CHANGELOG.md` is present (added during spec 00 preflight). If missing, re-run spec 00 before continuing. Prettier must not reformat CHANGELOG files. - -3. **Bump the version.** Run `pnpm --filter pr-review bump minor`. This updates both `.claude-plugin/plugin.json` and `marketplace.json` atomically. Never hand-edit `marketplace.json`. - -4. **Update `CLAUDE.md`.** Remove the roadmap line about re-review. Verify that the signature-prefix and latest-iteration rules added by earlier issues are present. - -5. **Add Re-review section to `README.md`** covering: trigger condition, what changes (detection, thread reuse, delta summary reply, completion marker), new signature format, and known limitations (force-push fallback, partial-run recovery). - -6. **Verify `apps/claude-code/pr-review/docs/adr/0009-summary-delta-as-reply.md` exists** (created in spec 00 preflight). If missing, re-run spec 00 before continuing. Do not create a duplicate. - -7. **Verify.** Run `pnpm --filter pr-review verify:changelog` locally before opening the PR. - -## Acceptance criteria - -- [ ] `pnpm --filter pr-review verify:changelog` passes locally -- [ ] Versions match across `plugin.json` and `marketplace.json` -- [ ] `README.md` includes a Re-review section -- [ ] Roadmap line removed from `CLAUDE.md`; signature and iteration rules present -- [ ] `apps/claude-code/pr-review/docs/adr/0009-summary-delta-as-reply.md` exists, references ADR 0007, status Accepted -- [ ] Monorepo `.prettierignore` contains `**/CHANGELOG.md` -- [ ] CI passes on the release PR - -## Blocked by - -- `docs/issues/pr-review-rereview/07-summary-comment-policy.md` -- `docs/issues/pr-review-rereview/08-test-fixture-suite.md` diff --git a/docs/issues/unic-archon-dlc/01-plugin-scaffold-and-tracer-install.md b/docs/issues/unic-archon-dlc/01-plugin-scaffold-and-tracer-install.md deleted file mode 100644 index 2c2a3b41..00000000 --- a/docs/issues/unic-archon-dlc/01-plugin-scaffold-and-tracer-install.md +++ /dev/null @@ -1,45 +0,0 @@ -# Plugin scaffold and tracer install hook - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -Scaffold the `unic-archon-dlc` plugin at `apps/claude-code/unic-archon-dlc/` with a working install hook that runs end-to-end from `claude /plugin install` and proves the wiring. This is the tracer slice: minimal but complete path through manifest → install hook → on-disk artifacts. - -In scope: - -- Plugin directory under `apps/claude-code/unic-archon-dlc/` following the same shape as `auto-format`, `pr-review`, `unic-confluence`. -- Manifests: `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`. Plugin name is `unic-archon-dlc`. Marketplace entry follows the monorepo convention (no hand edits; subsequent slices use `pnpm --filter ... bump`). -- `.archon/workflows/` and `.archon/commands/` directories shipped inside the plugin (empty placeholders accepted — populated by later slices). -- Install hook as an idempotent Node.js script (`.mjs`, ESM, zero external runtime deps) triggered by the Claude Code plugin install mechanism. -- **Setup explorer** module: reads `git remote`, `CLAUDE.md`, `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/`, existing `.archon/` and returns a structured snapshot of what is already configured. Missing files are reported as absent, not errored. -- **Archon binary check**: install hook verifies `archon` is on `PATH`. If missing, exits with a clear error referencing the README dependency note. Also reads `archon --version` and warns if the version is on the known-incompatible list (start with an empty list shipped as a JSON constant — populated as drift is observed). -- **Mandatory question tier only** in this slice: issue tracker (auto-detected from `git remote`; falls back to a prompt), PR strategy (deduced from tracker), branching strategy (Gitflow default, GitHub Flow alternative). -- Already-configured values are shown back to the user and skippable — re-running the hook never overwrites without consent. -- **Outputs:** - - `.archon/unic-dlc.config.json` (machine-readable) populated with the mandatory tier only. - - `docs/agents/issue-tracker.md` (human-readable) describing the chosen tracker, its CLI, and the create/update conventions. -- Config loader/validator module: `loadConfig(path)` returns a typed config object or a structured error. Mandatory fields validated; unknown keys ignored. -- Tests (`node:test`, `.mjs`) for config loader (valid parse, missing mandatory fields, unknown keys) and setup explorer (mock project directory snapshot, absent-vs-errored handling). - -Out of scope for this slice: label tiers (state/type/priority), e2e command prompt, multi-context detection, remaining `docs/agents/*` files, `CLAUDE.md` block, any workflow YAML or command file contents. - -## Acceptance criteria - -- [ ] `apps/claude-code/unic-archon-dlc/` exists with valid `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` (`pnpm check` and `pnpm typecheck` pass at repo root). -- [ ] Running the install hook against a fresh project writes `.archon/unic-dlc.config.json` with at minimum `{ tracker, pr_strategy, branching }` populated. -- [ ] Running the install hook against a fresh project writes `docs/agents/issue-tracker.md` describing the chosen tracker. -- [ ] Re-running the install hook is idempotent: no overwrites, already-configured values shown and skipped. -- [ ] Missing `archon` binary produces a clear, actionable error and a non-zero exit. -- [ ] Setup explorer returns a structured snapshot for a mock project directory; missing files are reported as absent rather than throwing. -- [ ] `node:test` suite covers config loader (3 cases) and setup explorer (1 case) and passes on macOS, Windows, and Linux paths (use `node:path`). -- [ ] No external runtime deps added to the plugin (`auto-format`-style bar). - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/unic-archon-dlc/02-full-install-hook-and-agent-docs.md b/docs/issues/unic-archon-dlc/02-full-install-hook-and-agent-docs.md deleted file mode 100644 index dbdb4dd2..00000000 --- a/docs/issues/unic-archon-dlc/02-full-install-hook-and-agent-docs.md +++ /dev/null @@ -1,47 +0,0 @@ -# Full install hook with all config tiers and agent docs - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -Expand the install hook from the tracer slice to cover every configuration tier and write the full `docs/agents/` set. The hook remains idempotent and additive: re-running it fills in only what is missing. - -In scope: - -- **Skippable tier:** e2e test command. If the user defers, the config records `e2e_command: null` and the hook can fill it in on a later run. -- **Defaulted tier (no prompt unless `--reconfigure`):** model profile (`balanced`), TDD mode (`on`), Nyquist validation (`on`), slopsquatting gate (`on`). -- **Label configuration tier (canonical → tracker string mapping):** - - **State labels:** `needs-triage` → `needs-info` → `needs-specs` → `ready-for-agent` / `ready-for-human` → `resolved` → `closed` (or `rejected`). Canonical role names match `docs/agents/triage-labels.md` from this repo. - - **Type labels:** `feature`, `bug`, `spike`, `tech-debt`, `docs`. - - **Priority labels:** `p0`, `p1`, `p2`, `p3`. - - Each canonical name is mapped to the actual string used in the project's tracker. -- **Multi-context detection:** if `CONTEXT-MAP.md` exists at repo root, the hook records `repo_layout: "multi-context"` and discovers per-context `CONTEXT.md` paths; otherwise `"single-context"` with the root `CONTEXT.md` path. -- **`docs/agents/` outputs** (write or update — never clobber unrelated content): - - `issue-tracker.md` — already written in slice 1; expand with backend-specific create/update conventions. - - `labels.md` — three-tier taxonomy with canonical-to-string mappings for the chosen tracker. - - `branching.md` — chosen strategy, default branch names, PR target conventions. - - `domain.md` — single-context vs multi-context layout, CONTEXT.md and ADR locations. - - `workflow.md` — maps each of the six workflow phases to its artifact outputs and `docs/workflow/` paths. -- **`CLAUDE.md` update:** append (or update in place) an `## Agent skills` block listing each `docs/agents/*.md` file with a one-line hook. If the block already exists, refresh its contents idempotently. -- Reasonable defaults applied automatically when the tracker is local markdown (canonical strings == tracker strings). - -Out of scope: workflow YAML or command file contents (later slices). - -## Acceptance criteria - -- [ ] Fresh install writes all five `docs/agents/*.md` files plus the `## Agent skills` block in `CLAUDE.md`. -- [ ] `.archon/unic-dlc.config.json` includes all label tiers, e2e command (or `null`), defaulted fields, and `repo_layout`. -- [ ] Multi-context repo (with `CONTEXT-MAP.md`) is detected and recorded; single-context repo records the root `CONTEXT.md` path. -- [ ] Re-running the hook after the tracer install adds only missing fields; existing fields are preserved unless `--reconfigure` is passed. -- [ ] If `CLAUDE.md` already has an `## Agent skills` block, it is refreshed without duplicating sections or destroying neighbouring content. -- [ ] Each `docs/agents/*.md` matches the canonical-to-tracker mapping in `.archon/unic-dlc.config.json` (no drift between machine and human readable). -- [ ] Tests cover the canonical-to-tracker mapping for at least the local-markdown and GitHub backends. - -## Blocked by - -- `docs/issues/unic-archon-dlc/01-plugin-scaffold-and-tracer-install.md` diff --git a/docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md b/docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md deleted file mode 100644 index 25fa363f..00000000 --- a/docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md +++ /dev/null @@ -1,40 +0,0 @@ -# Triage workflow and tracker adapter - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -The simplest of the six workflows — `triage` — paired with the tracker adapter module that every later workflow will depend on. Builds the foundation for issue I/O across all backends. - -In scope: - -- **Tracker adapter module:** translates canonical label names to tracker-specific strings and produces create/update CLI command strings for each configured backend. Backends covered in v1: GitHub Issues, Azure DevOps, Jira, local markdown (per the `docs/agents/issue-tracker.md` convention in this repo: file under `docs/issues//`, `Status:` line records triage state, comments append to a `## Comments` heading). Deep module — all tracker-specific knowledge encapsulated. -- **`/unic-dlc-triage` command** (note the `unic-dlc-` prefix — avoids collision with existing `/triage` skills) plus `.archon/workflows/triage.yaml`. -- **Workflow behaviour:** reads current issue states from the configured tracker, reconciles them against `docs/workflow/ROADMAP.md` (creates it if absent), and produces `HANDOFF.md` capturing: - - Current phase (which workflow last ran, when, on which feature slug) - - Open issues grouped by triage state - - Blockers (issues whose `blocked_by` references are still open) - - Recent decisions (latest ADR file IDs) -- **Standalone invocation:** runnable at any point in the lifecycle without prerequisites. -- **Reused as final node of `cleanup`:** the same workflow file is referenced from the cleanup DAG in slice 13. Both invocations produce the same `HANDOFF.md`. -- Tests covering the tracker adapter: for each backend, canonical label input produces the expected CLI command string. Tests also assert that absent state files are treated as "no data" rather than errors. - -Out of scope: any auto-promotion of issues across states (PRD explicitly excludes this). - -## Acceptance criteria - -- [ ] `/unic-dlc-triage` runs end-to-end against a project with the local-markdown tracker and produces a valid `HANDOFF.md`. -- [ ] Tracker adapter handles all four backends. Each emits a syntactically valid CLI command (or the local-markdown file write) for a canonical-label input. -- [ ] `docs/workflow/ROADMAP.md` is created on first run and updated on subsequent runs; updates do not clobber human-edited sections (use marker-delimited regions for the auto-generated parts). -- [ ] `HANDOFF.md` includes all four sections: phase, open issues by state, blockers, recent decisions. -- [ ] `node:test` covers the tracker adapter (one case per backend) and the HANDOFF generator (golden-file-style assertion on a mock project state). -- [ ] Command file uses the `unic-dlc-` prefix consistently. - -## Blocked by - -- `docs/issues/unic-archon-dlc/02-full-install-hook-and-agent-docs.md` diff --git a/docs/issues/unic-archon-dlc/04-explore-parallel-research-and-synthesize.md b/docs/issues/unic-archon-dlc/04-explore-parallel-research-and-synthesize.md deleted file mode 100644 index ecff2cca..00000000 --- a/docs/issues/unic-archon-dlc/04-explore-parallel-research-and-synthesize.md +++ /dev/null @@ -1,39 +0,0 @@ -# Explore workflow — parallel research and synthesize - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -First half of the `explore` workflow: four parallel research agents converging on a `synthesize` node that produces a coherent brief, written to `docs/workflow//findings.md`. - -In scope: - -- `.archon/workflows/explore.yaml` (will be extended in slice 05 with the prototype phase). -- `/unic-dlc-explore` command file. -- **Four parallel research nodes** running simultaneously, each scoped to a single concern: - - `research-stack` — current and emerging stack relevant to the feature - - `research-features` — comparable existing features in the codebase and prior art - - `research-architecture` — how the change fits the existing architecture and ADRs - - `research-pitfalls` — known traps, deprecations, security/privacy considerations -- **`synthesize` node** combining the four research outputs with the user's stated intent into a coherent brief. Pulls in CONTEXT.md and (if multi-context) CONTEXT-MAP.md so the brief uses the project glossary. -- **`docs/workflow//findings.md`** is committed to the repo. The slug is taken from the user-supplied feature name; the hook creates the directory if absent. -- **Optional input from `explore` is honoured by `plan`:** `plan` works without findings, but consumes them when present (the contract is "findings.md may or may not exist" — slice 06's `specs` node handles both cases). - -Out of scope (covered in slice 05): prototype node, VALIDATED/INVALIDATED/PARTIAL verdicts, spike-branch gate, spike ticket creation. - -## Acceptance criteria - -- [ ] `/unic-dlc-explore ` runs all four research nodes in parallel (verifiable from the Archon execution log or YAML structure). -- [ ] `synthesize` produces `docs/workflow//findings.md` containing sections for each research dimension plus the integrated brief. -- [ ] `findings.md` references CONTEXT.md vocabulary and at least one existing ADR by ID when one is relevant. -- [ ] Running `explore` without an existing `docs/workflow//` directory creates it; running with an existing directory does not destroy prior contents. -- [ ] Command file uses the `unic-dlc-` prefix. - -## Blocked by - -- `docs/issues/unic-archon-dlc/02-full-install-hook-and-agent-docs.md` diff --git a/docs/issues/unic-archon-dlc/05-explore-prototype-and-spike-gate.md b/docs/issues/unic-archon-dlc/05-explore-prototype-and-spike-gate.md deleted file mode 100644 index 38a61239..00000000 --- a/docs/issues/unic-archon-dlc/05-explore-prototype-and-spike-gate.md +++ /dev/null @@ -1,36 +0,0 @@ -# Explore workflow — prototype, spike verdicts, and spike-branch gate - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -Second half of the `explore` workflow: a prototype node that runs structured experiments, an optional human gate for preserving valuable spike code, and a spike ticket in the configured tracker. - -In scope: - -- **`prototype` node** appended to `.archon/workflows/explore.yaml`. Reads `findings.md` and produces one or more experiments, each emitting a structured verdict — exactly one of: - - `VALIDATED` — approach works as expected, evidence captured. - - `INVALIDATED` — approach failed, reason captured. - - `PARTIAL` — partially works, gaps documented. - - Verdicts and per-experiment notes are written into a `## Spike verdicts` section of `findings.md` (single source of truth — no separate spike file). -- **Optional interactive gate** after `prototype`: asks the user whether the spike produced code worth preserving on a branch. If yes, the workflow creates a `spike/` branch with the prototype code committed; if no, the worktree is left clean. -- **Spike ticket creation** via the tracker adapter (slice 03): a ticket of type `spike`, labelled with the configured priority default, linking to `docs/workflow//findings.md`. The ticket records VALIDATED/INVALIDATED/PARTIAL summary in its body so the tracker view is informative. - -Out of scope: feeding spike code into `plan` automatically — `plan` reads `findings.md` only, not the branch. - -## Acceptance criteria - -- [ ] `prototype` node runs after `synthesize` and writes a `## Spike verdicts` section to `findings.md` with at least one experiment carrying exactly one verdict from {VALIDATED, INVALIDATED, PARTIAL}. -- [ ] Spike-branch gate is interactive: answering "yes" creates a `spike/` branch with a commit; answering "no" leaves no branch behind. -- [ ] A spike ticket is created in the configured tracker via the tracker adapter, with type label `spike`, body linking to `findings.md`, and a one-line verdict summary. -- [ ] Re-running `/unic-dlc-explore ` on an existing slug does not duplicate the spike ticket; the existing ticket is updated. - -## Blocked by - -- `docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md` -- `docs/issues/unic-archon-dlc/04-explore-parallel-research-and-synthesize.md` diff --git a/docs/issues/unic-archon-dlc/06-plan-specs-and-to-prd.md b/docs/issues/unic-archon-dlc/06-plan-specs-and-to-prd.md deleted file mode 100644 index 4e072d6a..00000000 --- a/docs/issues/unic-archon-dlc/06-plan-specs-and-to-prd.md +++ /dev/null @@ -1,40 +0,0 @@ -# Plan workflow — specs, to-prd, and first PR gate - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -First half of the `plan` workflow: a grill-with-docs interview, live ADR writes for non-obvious decisions, a structured PRD output, and the first human approval gate. - -In scope: - -- `.archon/workflows/plan.yaml` (extended by slice 07). -- `/unic-dlc-plan` command file. -- **`specs` node — grill-with-docs style:** - - Loads `CONTEXT.md`, `CONTEXT-MAP.md` (if present), all existing ADRs from `docs/adr/`, and `docs/workflow//findings.md` if present. - - Conducts an adversarial interview, **one question at a time**, challenging terminology against the domain glossary. - - Proposes ADR entries for non-obvious decisions as they crystallise — not for every answer. Written live into `docs/adr/NNNN-.md` at the moment the decision is made. - - Configurable assumptions-first mode via `workflow.discuss_mode: assumptions` in `.archon/unic-dlc.config.json` (defaults to `interview`). Assumptions mode is for experienced developers in established codebases — surfaces a set of assumptions for the user to correct rather than asking from scratch. -- **`to-prd` node:** synthesises the interview transcript and live-written ADRs into `docs/workflow//PRD.md` with the agreed structure: Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes. -- **First human PR gate (`interactive: true`):** opens a PR against the working branch with `PRD.md` and any new ADRs staged for review. Workflow pauses until the gate is approved. - -Out of scope (slice 07 and 08): `to-issues`, `nyquist-map`, `plan-checker`, `yaml-gen`, second PR gate. - -## Acceptance criteria - -- [ ] `specs` loads CONTEXT.md and existing ADRs before the first interview question. -- [ ] Interview asks one question at a time (no multi-question batches) and rephrases when the user pushes back on terminology. -- [ ] At least one ADR is written into `docs/adr/` during a representative session that contains a non-obvious decision; sessions with only obvious answers produce zero ADRs. -- [ ] `to-prd` writes `docs/workflow//PRD.md` with all seven structural sections present. -- [ ] `workflow.discuss_mode: assumptions` flips the interview into assumptions mode; the default mode runs full interviews. -- [ ] First human PR gate blocks the workflow until approved; rejected approvals return control to `specs` for another iteration. -- [ ] Command file uses the `unic-dlc-` prefix. - -## Blocked by - -- `docs/issues/unic-archon-dlc/02-full-install-hook-and-agent-docs.md` diff --git a/docs/issues/unic-archon-dlc/07-plan-to-issues-and-nyquist.md b/docs/issues/unic-archon-dlc/07-plan-to-issues-and-nyquist.md deleted file mode 100644 index 5ce98e1d..00000000 --- a/docs/issues/unic-archon-dlc/07-plan-to-issues-and-nyquist.md +++ /dev/null @@ -1,38 +0,0 @@ -# Plan workflow — to-issues, nyquist-map, and validation gate - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -Decomposes the approved PRD into vertically-sliced issues with explicit dependencies and a test command for each issue, then asks the user to validate the breakdown before publication. - -In scope: - -- **`to-issues` node** extending `plan.yaml`: - - Reads `docs/workflow//PRD.md` and emits `docs/workflow//issues.json` with a list of issues; each issue carries `title`, `type` (canonical type label), `priority` (canonical priority label), `blocked_by: []` (array of issue IDs in this same file), `acceptance_criteria: []`, and `summary`. - - Slices are vertical tracer bullets — each slice cuts through every integration layer end-to-end, not horizontally by layer. - - Before writing the issues to the tracker, presents the breakdown to the user (numbered list with type/priority/blocked-by/summary) and asks the user to validate, split, merge, or relabel. Iterates until approved. - - After approval, publishes each issue to the configured tracker via the tracker adapter, in dependency order so blocker IDs are real. -- **`nyquist-map` node:** for each issue, attaches a `test_command` field (the exact shell command that proves the issue's acceptance criteria). For issues whose test command does not yet exist, attaches a `test_command_planned` flag so `plan-checker` (slice 08) can flag them. -- This slice publishes the issues to the tracker so the user can see them — but does **not** generate the build YAML (slice 08) and does **not** invoke the `plan-checker` loop (slice 08). It is acceptable for a user to stop here. - -Out of scope: `plan-checker` loop, `yaml-gen`, second PR gate (all in slice 08). - -## Acceptance criteria - -- [ ] `to-issues` reads PRD.md and writes `issues.json` whose structure matches the field set above. -- [ ] Issues are vertical slices — each entry's acceptance criteria can be demonstrated independently (verified by a representative example in tests). -- [ ] Validation gate is interactive and supports split/merge/relabel before publication. -- [ ] After approval, each issue exists in the configured tracker with correct type and priority labels (verified for the local-markdown backend at minimum). -- [ ] `nyquist-map` attaches a `test_command` (or `test_command_planned: true`) to every issue. -- [ ] Tracker publication is dependency-ordered: every `blocked_by` reference points to an issue that already exists in the tracker. - -## Blocked by - -- `docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md` -- `docs/issues/unic-archon-dlc/06-plan-specs-and-to-prd.md` diff --git a/docs/issues/unic-archon-dlc/08-plan-checker-and-yaml-gen.md b/docs/issues/unic-archon-dlc/08-plan-checker-and-yaml-gen.md deleted file mode 100644 index 24bc3309..00000000 --- a/docs/issues/unic-archon-dlc/08-plan-checker-and-yaml-gen.md +++ /dev/null @@ -1,41 +0,0 @@ -# Plan workflow — plan-checker loop, yaml-gen, and second PR gate - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -Closes out the `plan` workflow with a validating loop that hardens the issue plan, a runtime YAML generator that turns the dependency tree into a build DAG, and the second human PR gate. - -In scope: - -- **`plan-checker` loop node:** - - Max 3 iterations before escalation to a human gate. - - **Stall detection:** if the issue count does not decrease between consecutive iterations, escalate immediately to the human gate rather than burning the remaining retries. - - Validates four dimensions: - - **Consistency** — no orphaned `blocked_by` references, all PRD acceptance criteria are covered by at least one issue. - - **Completeness** — every mandatory field is present on every issue. - - **Decision coverage** — every trackable decision in `CONTEXT.md` (and any decisions captured during `specs`) appears in at least one issue. - - **Nyquist compliance** — every issue maps to a concrete test command (no lingering `test_command_planned: true` unless explicitly accepted at the gate). -- **`yaml-gen` bash node:** reads `issues.json`, builds the dependency DAG, detects parallel groups (issues with no shared `blocked_by`), and writes `.archon/workflows/build-.yaml`. Both `code-red` and `code-green` for independent issues are emitted as parallel-capable nodes. Linear chains produce serial nodes; circular dependencies are detected, reported, and abort the generation. Output YAML must be valid Archon syntax. -- **Dependency tree builder + YAML generator module:** pure data transformation, separately unit-tested. Test cases: linear chain → serial; independents → parallel; circular → reported; output round-trips through Archon's YAML parser. -- **Second human PR gate (`interactive: true`):** opens a PR containing `issues.json`, the generated `build-.yaml`, and the `plan-checker` report. Workflow pauses until approved. Rejected approvals return control to `plan-checker` for another validation pass (not a full re-decomposition). - -Out of scope: executing the generated build YAML (slice 09). - -## Acceptance criteria - -- [ ] `plan-checker` runs at most 3 iterations and escalates on stall (issue count stays equal between consecutive iterations). -- [ ] `plan-checker` reports failures across all four validation dimensions in a single structured report. -- [ ] `yaml-gen` produces a syntactically valid Archon YAML; circular dependencies abort with a clear error. -- [ ] Independent issues appear as parallel nodes; chained issues appear as serial nodes; both `code-red` and `code-green` carry parallel grouping when applicable. -- [ ] Dependency tree builder unit tests cover linear, parallel-fan, diamond, and circular cases. -- [ ] Second human PR gate stages `issues.json` + `build-.yaml` + `plan-checker` report in a PR and blocks until approved. - -## Blocked by - -- `docs/issues/unic-archon-dlc/07-plan-to-issues-and-nyquist.md` diff --git a/docs/issues/unic-archon-dlc/09-build-tdd-core-and-slopcheck.md b/docs/issues/unic-archon-dlc/09-build-tdd-core-and-slopcheck.md deleted file mode 100644 index 77abe16e..00000000 --- a/docs/issues/unic-archon-dlc/09-build-tdd-core-and-slopcheck.md +++ /dev/null @@ -1,43 +0,0 @@ -# Build workflow — TDD core and slopcheck - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -The TDD execution core of `build`: the generated `build-.yaml` is executed by Archon, enforcing `code-red` before `code-green` per issue, with both phases parallelisable across independent issues. A `slopcheck` gate sits in front of any package install to guard against AI-hallucinated dependencies. - -In scope: - -- **`/unic-dlc-build ` command** that executes the runtime-generated `.archon/workflows/build-.yaml` produced in slice 08. -- **Per-issue TDD discipline enforced by the DAG:** - - `code-red` writes failing acceptance tests for the issue. - - `code-green` writes the minimum implementation to pass those tests. - - `depends_on` edges in the generated YAML force red → green within an issue. -- **Cross-issue parallelism:** both `code-red` and `code-green` may run in parallel across issues whose `blocked_by` is empty (or whose blockers are already complete). The `yaml-gen` output from slice 08 must already encode this; this slice verifies the runtime honours it. -- **`slopcheck` bash node** placed before any `package install` step: - - Detects newly introduced package names by diffing manifest files (`package.json`, `pyproject.toml`, `Cargo.toml`, etc. depending on the project — start with the JS/TS ecosystem and document how to extend). - - For each new package, checks registry existence (npm registry HEAD request for JS; equivalent for the other ecosystems already in scope). - - Packages that fail the registry check are flagged `[ASSUMED]`. - - For each `[ASSUMED]` package, creates a `checkpoint:human-verify` task inline so the user explicitly approves before installation continues. - - If the optional `slopcheck` Python tool (GSD's slopsquatting gate) is on `PATH`, defer to it for the registry check; otherwise use the fallback registry HEAD checks. - - If neither path is available, default to marking every new package `[ASSUMED]` — stricter, not silently permissive. - -Out of scope: verification, goals-check, report, `/unic-dlc-review` (slices 10 and 11). - -## Acceptance criteria - -- [ ] Executing `/unic-dlc-build ` runs the runtime-generated YAML and produces commits in the order: failing test → passing implementation, per issue. -- [ ] Independent issues are observed to run `code-red` (and `code-green`) in parallel for at least one representative `issues.json` test case. -- [ ] `slopcheck` runs before any package install and creates a `checkpoint:human-verify` task for every `[ASSUMED]` package. -- [ ] Approving the checkpoint allows the install to proceed; rejecting it aborts the install for that package and surfaces a clear message. -- [ ] When neither the Python `slopcheck` tool nor the fallback registry check is available, every new package is treated as `[ASSUMED]`. -- [ ] Command file uses the `unic-dlc-` prefix. - -## Blocked by - -- `docs/issues/unic-archon-dlc/08-plan-checker-and-yaml-gen.md` diff --git a/docs/issues/unic-archon-dlc/10-build-verification-goals-check-and-report.md b/docs/issues/unic-archon-dlc/10-build-verification-goals-check-and-report.md deleted file mode 100644 index d2f82038..00000000 --- a/docs/issues/unic-archon-dlc/10-build-verification-goals-check-and-report.md +++ /dev/null @@ -1,42 +0,0 @@ -# Build workflow — verification, goals-check, report, and PR gate - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -Quality and consolidation phase of `build`: a verification node that catches low-quality implementations, a goals-check coverage matrix that ties code back to the PRD, a consolidated report, and the human PR gate that follows. - -In scope: - -- **`verification` node:** - - Runs the full test suite for the slug's touched packages. - - Checks coverage thresholds (from `.archon/unic-dlc.config.json`). - - Detects stub patterns: `TODO` / `FIXME` / empty function bodies that only `return` or `pass` / hardcoded sentinel values returned where logic was expected. - - Audits wiring across layers: component → API → DB; form → handler. Mismatches are reported with file:line references so the report is actionable. -- **`goals-check` node:** reads `docs/workflow//PRD.md` and produces a **coverage matrix** mapping each acceptance criterion (from every user story / issue) to implementation evidence (file paths, test names, or "MISSING"). The matrix is the artifact reviewers look at before merging. -- **`report` node:** writes `docs/workflow//report.md` consolidating: - - What was built (high-level summary of merged issues) - - Goals-check matrix (verbatim from the previous node) - - Test outcomes (pass/fail counts, coverage numbers) - - Decisions made during implementation (links to any new ADRs) - - Tech debt flagged for cleanup (consumed by slice 13) -- **Human PR gate (`interactive: true`)** after `report`: opens a PR with the implementation plus `report.md`. Workflow pauses until approved. Rejected approvals return control to `verification` for another pass. - -Out of scope: the `/unic-dlc-review` command itself (slice 11) — this slice's PR gate is the human review; slice 11 adds the automated AFK review. - -## Acceptance criteria - -- [ ] `verification` fails when coverage is below threshold, when stub patterns are present, or when a wiring mismatch is detected. -- [ ] `goals-check` produces a coverage matrix where each row maps an acceptance criterion to evidence or "MISSING"; matrices with any "MISSING" rows fail the node. -- [ ] `report.md` contains all five sections and is committed to `docs/workflow//`. -- [ ] Human PR gate blocks until approved; rejection returns control to `verification`. -- [ ] Tests cover the stub-pattern detector with at least three positive and three negative cases. - -## Blocked by - -- `docs/issues/unic-archon-dlc/09-build-tdd-core-and-slopcheck.md` diff --git a/docs/issues/unic-archon-dlc/11-build-self-contained-review-command.md b/docs/issues/unic-archon-dlc/11-build-self-contained-review-command.md deleted file mode 100644 index 3688660a..00000000 --- a/docs/issues/unic-archon-dlc/11-build-self-contained-review-command.md +++ /dev/null @@ -1,42 +0,0 @@ -# Build workflow — self-contained /unic-dlc-review command - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -A self-contained `/unic-dlc-review` command that performs a multi-aspect PR review as an AFK Archon node. It is independent of any external review plugin so users can run the full DLC without installing `pr-review-toolkit`. - -In scope: - -- **`/unic-dlc-review` command + workflow node** invoked after the human PR gate from slice 10 (the human gate approves the PR; the review runs automatically on the diff). -- **Four review aspects, each emitting a structured finding list:** - 1. **Code quality** — readability, naming, function length, project-convention adherence (reads `CLAUDE.md`/`AGENTS.md`). - 2. **Test coverage adequacy** — exercises through public interfaces, asserts on outputs not internals, no mocks of internal collaborators. - 3. **Silent failure patterns** — swallowed exceptions, empty `catch` blocks, fallbacks that hide bugs. - 4. **Type design quality** — encapsulation, invariants expressed in types, illegal-state-unrepresentable patterns. -- **Inspiration references** documented in the command file: - - This monorepo's `apps/claude-code/pr-review/` (patterns, not runtime dependency). - - Matt Pocock's `review` skill (https://github.com/mattpocock/skills/blob/main/skills/in-progress/review/SKILL.md). - - Note in the command file that this is a base review intended to evolve; later slices may deepen each aspect. -- **Output:** a structured review comment posted via the tracker adapter against the PR opened by slice 10. Findings are grouped by aspect with file:line references. -- **No runtime dependency** on `pr-review-toolkit` or any other plugin — verified by running the review in a project where `pr-review-toolkit` is not installed. - -Out of scope: integrating the review with the `qa` workflow's gates (slice 12 reads but does not depend on the review output). - -## Acceptance criteria - -- [ ] `/unic-dlc-review` runs to completion on a project that does not have `pr-review-toolkit` installed. -- [ ] The review posts a single structured comment grouped by the four aspects, each with at least one finding or an explicit "no findings" line. -- [ ] Findings include file:line references where applicable. -- [ ] Command file uses the `unic-dlc-` prefix and includes the inspiration references in its prologue. -- [ ] Re-running the review on the same PR updates the prior comment rather than appending a duplicate. - -## Blocked by - -- `docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md` -- `docs/issues/unic-archon-dlc/10-build-verification-goals-check-and-report.md` diff --git a/docs/issues/unic-archon-dlc/12-qa-workflow.md b/docs/issues/unic-archon-dlc/12-qa-workflow.md deleted file mode 100644 index 2cb506ef..00000000 --- a/docs/issues/unic-archon-dlc/12-qa-workflow.md +++ /dev/null @@ -1,37 +0,0 @@ -# QA workflow — e2e, coverage gate, UAT, merge - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -A `qa` workflow that runs the e2e suite first, fails fast on insufficient coverage, presents an informed UAT checklist, and merges the PR via the tracker's CLI after sign-off. - -In scope: - -- `/unic-dlc-qa ` command and `.archon/workflows/qa.yaml`. -- **E2e suite runs first.** Uses the `e2e_command` configured during install (slice 02). If unset, the workflow halts with a clear message asking the user to run install with `--reconfigure` and set the command. -- **`coverage-gate` bash node** enforces the coverage thresholds configured in `.archon/unic-dlc.config.json`. Fails fast — the human UAT gate never opens unless automated coverage already passes. -- **`uat-gate` interactive node:** presents e2e results alongside the UAT checklist extracted from the PRD's acceptance criteria. Approval continues to merge; rejection returns control to whoever owns the failing checklist item. -- **Merge step via tracker adapter:** after `uat-gate` approves, the workflow merges the PR using the configured tracker's CLI (no manual terminal commands required). Branch deletion follows the configured branching strategy (Gitflow vs GitHub Flow). -- All workflow YAML uses canonical label names; the adapter translates at write time. - -Out of scope: post-merge cleanup (slice 13). - -## Acceptance criteria - -- [ ] `/unic-dlc-qa ` runs the configured `e2e_command` before any human gate opens. -- [ ] If `e2e_command` is unset, the workflow halts with a clear, actionable message and a non-zero exit. -- [ ] `coverage-gate` blocks `uat-gate` when coverage is below threshold. -- [ ] `uat-gate` shows the PRD's acceptance criteria as a checklist alongside the e2e summary. -- [ ] After `uat-gate` approves, the PR is merged via the tracker adapter; branch handling matches the configured branching strategy. -- [ ] Command file uses the `unic-dlc-` prefix. - -## Blocked by - -- `docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md` -- `docs/issues/unic-archon-dlc/10-build-verification-goals-check-and-report.md` diff --git a/docs/issues/unic-archon-dlc/13-cleanup-workflow.md b/docs/issues/unic-archon-dlc/13-cleanup-workflow.md deleted file mode 100644 index 3f375a50..00000000 --- a/docs/issues/unic-archon-dlc/13-cleanup-workflow.md +++ /dev/null @@ -1,40 +0,0 @@ -# Cleanup workflow — arch-review, ADR consolidation, triage - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -Post-merge cleanup that catches drift, locks in architectural decisions, and refreshes project state. Ends by reusing the triage workflow from slice 03. - -In scope: - -- `/unic-dlc-cleanup ` command and `.archon/workflows/cleanup.yaml`. -- **`arch-review` node:** - - Reads both `docs/workflow//PRD.md` (intent) and `docs/workflow//report.md` (technical outcome) alongside the changed code. - - Catches **technical drift** (modules that became too shallow, tight coupling, leaky abstractions) and **intent drift** (delivered behaviour diverges from the PRD). - - Proposes **deepening opportunities** for modules that grew thin during implementation. - - Writes `docs/workflow//arch-review.md`. -- **`adr-consolidation` interactive node:** - - Reviews decisions logged during `build` (the "Decisions made during implementation" section of `report.md`) plus any ADR drafts proposed during `arch-review`. - - **Per-ADR approval gate**: each proposed ADR is presented individually for accept / reject / edit. Only accepted ADRs are written to `docs/adr/`. -- **Final node reuses slice 03's `triage` workflow** — the same `.archon/workflows/triage.yaml` is referenced via Archon's workflow-include mechanism. Both invocations (standalone vs as cleanup's final node) produce the same `HANDOFF.md` and the same `ROADMAP.md` update. - -Out of scope: changes to `triage` itself (any new behaviour belongs in slice 03's file). - -## Acceptance criteria - -- [ ] `/unic-dlc-cleanup ` writes `docs/workflow//arch-review.md` covering technical drift, intent drift, and at least one deepening opportunity (or "none identified"). -- [ ] `adr-consolidation` presents each proposed ADR individually; reject/accept choices are recorded; only accepted ADRs land in `docs/adr/`. -- [ ] Cleanup's final node reuses `.archon/workflows/triage.yaml` (no duplicate triage logic); `HANDOFF.md` is produced exactly once per cleanup run. -- [ ] The reused triage node updates `docs/workflow/ROADMAP.md` when invoked as cleanup's final node (no duplicate ROADMAP logic in cleanup itself). -- [ ] Command file uses the `unic-dlc-` prefix. - -## Blocked by - -- `docs/issues/unic-archon-dlc/12-qa-workflow.md` -- `docs/issues/unic-archon-dlc/03-triage-workflow-and-tracker-adapter.md` diff --git a/docs/issues/unic-archon-dlc/14-readme-and-documentation.md b/docs/issues/unic-archon-dlc/14-readme-and-documentation.md deleted file mode 100644 index 32d4eb7f..00000000 --- a/docs/issues/unic-archon-dlc/14-readme-and-documentation.md +++ /dev/null @@ -1,46 +0,0 @@ -# README and complete documentation - -**Status:** ready-for-agent -**Category:** docs - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -The plugin README — the only user-facing entry point for adopters. Final slice because it documents the shipped behaviour, not the intended behaviour. - -In scope (`apps/claude-code/unic-archon-dlc/README.md`): - -1. **Mermaid flowchart** showing all six workflows (`explore`, `plan`, `build`, `qa`, `cleanup`, `triage`), every node, and human gate markers (✓ on interactive nodes). -2. **Node reference table** — one row per node: - - Workflow · Node · Type (`prompt` / `loop` / `bash` / `interactive`) · Human gate (✓ / —) -3. **Quick-start** — install + first run in three steps. Example commands use the `unic-dlc-` prefix. -4. **Configuration reference** — every key in `.archon/unic-dlc.config.json` with default and valid values: `tracker`, `pr_strategy`, `branching`, `e2e_command`, `model_profile`, `tdd_mode`, `nyquist_validation`, `slopsquatting_gate`, label tier mappings, `repo_layout`, `workflow.discuss_mode`, coverage thresholds. -5. **`docs/workflow/` layout diagram** — visual of what gets created where and who owns each artifact. State the three-layer separation explicitly: transient (`$ARTIFACTS_DIR`) vs persistent (`docs/workflow//`) vs tracker. -6. **Dependency map:** Archon version requirement, no required peer plugins, optional `slopcheck` Python tool. -7. **Distribution note:** Archon has no marketplace; this plugin fills the gap by riding the Claude Code plugin marketplace and scaffolding workflows into the target project. - -Also in scope: - -- The plugin's `CHANGELOG.md` carries a dated `0.1.0` entry summarising the lifecycle (CI's `verify:changelog` will fail without it). -- The marketplace listing description matches the README's one-line summary. - -Out of scope: per-workflow deep-dive docs (those live in `.archon/commands/*.md` shipped by each workflow slice). - -## Acceptance criteria - -- [ ] README renders correctly (Mermaid block parses; tables render). -- [ ] Mermaid flowchart shows all 6 workflows, every node from slices 03–13, and human gates marked with ✓. -- [ ] Node reference table includes every node in the shipped workflows. -- [ ] Quick-start gets a developer from zero to a successful `/unic-dlc-triage` run in three steps. -- [ ] Every key written by the install hook (slices 01 and 02) appears in the configuration reference with default and valid values. -- [ ] `docs/workflow/` layout diagram names the three persistence layers explicitly. -- [ ] `CHANGELOG.md` has a dated `0.1.0` entry and `pnpm --filter unic-archon-dlc verify:changelog` passes. - -## Blocked by - -- `docs/issues/unic-archon-dlc/05-explore-prototype-and-spike-gate.md` -- `docs/issues/unic-archon-dlc/11-build-self-contained-review-command.md` -- `docs/issues/unic-archon-dlc/13-cleanup-workflow.md` diff --git a/docs/issues/unic-archon-dlc/15-fix-interactive-loop-fresh-context.md b/docs/issues/unic-archon-dlc/15-fix-interactive-loop-fresh-context.md deleted file mode 100644 index ec426fdd..00000000 --- a/docs/issues/unic-archon-dlc/15-fix-interactive-loop-fresh-context.md +++ /dev/null @@ -1,31 +0,0 @@ -# Fix interactive loop nodes: add fresh_context to prevent session expiry crashes - -**Status:** ready-for-agent -**Category:** bug - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -All interactive loop nodes in the six workflows (`explore.yaml`, `plan.yaml`, `cleanup.yaml`) crash on iteration 2+ when a human responds to a gate. The root cause is a known Archon bug (coleam00/Archon#1208): the DAG executor tries to resume an expired Claude SDK session from the previous iteration instead of starting a fresh one. The fix is to add `fresh_context: true` to every node that is both `interactive: true` and uses a `loop:` block, so each iteration gets a clean session. - -Affected nodes across the six workflows: - -- `explore.yaml` → `code-preserve-gate` -- `plan.yaml` → `specs` (grill loop), `prd-gate`, `plan-gate`, `stall-gate` -- `cleanup.yaml` → `adr-consolidation` -- `qa.yaml` → `uat-gate` - -No lib modules, tests, or install hook are touched — this is a YAML-only patch. - -## Acceptance criteria - -- [ ] Every `interactive: true` loop node in all six workflow YAMLs has `fresh_context: true` set. -- [ ] No non-interactive loop node (e.g. `plan-checker`) receives `fresh_context: true` — only interactive gates get it. -- [ ] `pnpm check` passes at repo root after the change. - -## Blocked by - -None — can start immediately. diff --git a/docs/issues/unic-archon-dlc/16-qa-verify-pr-base.md b/docs/issues/unic-archon-dlc/16-qa-verify-pr-base.md deleted file mode 100644 index 5903439d..00000000 --- a/docs/issues/unic-archon-dlc/16-qa-verify-pr-base.md +++ /dev/null @@ -1,35 +0,0 @@ -# QA workflow: add verify-pr-base guard after merge-pr - -**Status:** ready-for-agent -**Category:** feature - -## Parent - -`docs/issues/unic-archon-dlc/PRD.md` - -## What to build - -`qa.yaml` currently calls `merge-pr` (which runs the configured tracker's merge CLI command) but does not verify the PR targets the correct base branch first. If the PR was opened against the wrong target — e.g. `main` instead of `develop` on a Gitflow project — the merge silently ships to the wrong branch. - -Add a `verify-pr-base` bash node that runs before `merge-pr`: - -1. Reads the configured branching strategy from `.archon/unic-dlc.config.json`. -2. Derives the expected base branch (`develop` for Gitflow, `main` for GitHub Flow). -3. For GitHub tracker: calls `gh pr view --json baseRefName` and compares. -4. For ADO tracker: calls `az repos pr show` and compares `targetRefName`. -5. For Jira / local: logs a warning and continues (no CLI to query PR base). -6. If the base is wrong: logs a clear error with the expected vs actual branch names and exits non-zero, preventing `merge-pr` from running. - -This is a YAML-only addition of one `bash` node with an inline shell snippet — no lib modules or tests are added. - -## Acceptance criteria - -- [ ] `qa.yaml` has a `verify-pr-base` bash node with `depends_on: [uat-gate]`. -- [ ] `merge-pr` has `depends_on: [verify-pr-base]`. -- [ ] For GitHub and ADO trackers, the node exits non-zero with a clear message if the PR base does not match the expected branch. -- [ ] For Jira and local trackers, the node logs a warning and exits zero (no-op). -- [ ] `pnpm check` passes at repo root after the change. - -## Blocked by - -None — can start immediately.