devflow-kit 2.3.0 → 2.5.0

package/dist/targets/claude-code/tracker-install.js

@@ -0,0 +1,161 @@
+/**
+ * Tracker artifact installer for the Claude Code target.
+ *
+ * Convergence function for the ONE artifact whose presence advertises the
+ * selected tracker provider: the Tracker agent file. The generated reference
+ * subtree converges too, but through {@link overlayInstalledReferences} in
+ * installer.ts — that is the installer's one overlay spelling, and a mode flag
+ * on this function would have made it a second (design review M2).
+ *
+ * Applies ADR-013: I/O orchestration in src/targets/; pure helpers in src/core/.
+ * Applies PF-009: warn-not-throw, so one failing artifact never aborts an install.
+ * Applies PF-015: the biconditional converges in BOTH directions — selecting a
+ * provider installs the agent, returning to github removes it.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { agentSourceDirs } from '../../core/assets.js';
+import { mdFileName } from '../../core/orphan-sweep.js';
+/**
+ * The agent whose presence is conditional on the provider.
+ *
+ * It stays DECLARED in `devflow-core-skills.agents` and is filtered at install
+ * time rather than being lifted into a feature-owned set: the compliance
+ * precedent does not transfer, because compliance's plugin was deleted while
+ * `devflow-core-skills` is a live, non-optional owner. A feature-owned set would
+ * cost three new union sites and a rewrite of the pinned agent-roster floor to
+ * solve a problem the agent SWEEP does not have — the sweep keys on the full
+ * registry, so it never sees this file as an orphan.
+ *
+ * Exported because the filter has more than one reader and may have only one
+ * authority (D-TRACKER-AGENT-OWNER): {@link convergeTrackerArtifacts} below,
+ * which decides whether the file exists, and, in installer.ts, both the generic
+ * agent copy loop — which has to skip the one agent it does not own — and the
+ * full-install pre-clean, which has to empty the agent directory around it. A
+ * second literal at any of those sites is the shape this export exists to forbid.
+ */
+export const TRACKER_AGENT_NAME = 'tracker';
+// ── Internals ──────────────────────────────────────────────────────────────
+/**
+ * The provider whose mechanics need no Tracker agent.
+ *
+ * GitHub conventions are not inferred: the Git agent runs `gh`, whose issue
+ * grammar this repo already speaks. The agent exists to infer conventions from a
+ * connected tool-call server, which is a thing only the other providers have.
+ */
+const AGENTLESS_PROVIDER = 'github';
+function agentTarget(claudeDir) {
+    return path.join(claudeDir, 'agents', 'devflow', mdFileName(TRACKER_AGENT_NAME));
+}
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** First path in `candidates` that exists, or undefined when none do. */
+async function firstExisting(candidates) {
+    for (const candidate of candidates) {
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Would copying `source` over `target` change anything?
+ *
+ * Asked once, between resolving the source and copying it, so a run that would write a
+ * byte-identical copy of the installed agent reports `unchanged` instead of `installed`
+ * — the same question the reference overlay asks per unit, for the same reason: a
+ * summary that can only ever say "installed" says nothing, and a steady-state re-init
+ * announcing "tracker agent installed" is the noise this closes (QA S2).
+ *
+ * It does NOT weaken the self-heal. A hand-edited or truncated agent differs from its
+ * source, so it is copied and reported as written; only an identical file is skipped,
+ * and skipping a copy of what is already there changes nothing on disk.
+ *
+ * Any error — an absent target, an unreadable one — answers "no". The fallback is the
+ * copy that was going to happen anyway, so a failure to compare costs a write, never
+ * correctness.
+ */
+async function copyWouldChangeNothing(source, target) {
+    try {
+        const [from, to] = await Promise.all([fs.readFile(source), fs.readFile(target)]);
+        return from.equals(to);
+    }
+    catch {
+        return false;
+    }
+}
+// ── Convergence ────────────────────────────────────────────────────────────
+/**
+ * Converge the Tracker agent file onto the resolved provider.
+ *
+ * Convergence matrix:
+ *   provider !== github → copy the agent in, unless the installed file is already
+ *                         byte-identical to the source. Compared rather than trusted
+ *                         for existing, so a truncated or hand-edited file self-heals;
+ *                         compared rather than re-copied blind, so a run that changes
+ *                         nothing reports `unchanged` and the summary stays quiet
+ *                         (see {@link copyWouldChangeNothing})
+ *   provider === github → remove it, absent or not
+ *
+ * Never throws. A caller gates on `converged`; it does not catch. The one
+ * refusal that is not an I/O degradation — a claudeDir that is not absolute —
+ * is reported the same way rather than thrown, because it reaches here from a
+ * manifest read and an install must not die on it.
+ */
+export async function convergeTrackerArtifacts(opts) {
+    const { claudeDir, provider, warn } = opts;
+    // Precondition, asserted in production code rather than only in tests: an
+    // empty or relative claudeDir would make the target resolve somewhere
+    // unexpected, and the removal branch runs fs.rm against it.
+    if (!path.isAbsolute(claudeDir)) {
+        warn(`tracker: claudeDir is not an absolute path ("${claudeDir}") — skipping convergence`);
+        return { converged: false, agentPresent: false, agent: 'unchanged' };
+    }
+    const target = agentTarget(claudeDir);
+    if (provider === AGENTLESS_PROVIDER) {
+        const existed = await pathExists(target);
+        if (!existed)
+            return { converged: true, agentPresent: false, agent: 'unchanged' };
+        try {
+            await fs.rm(target, { force: true });
+        }
+        catch (err) {
+            warn(`tracker: failed to remove the Tracker agent (${target}) — ${String(err)}`);
+            return { converged: false, agentPresent: true, agent: 'unchanged' };
+        }
+        return { converged: true, agentPresent: false, agent: 'removed' };
+    }
+    const dirs = opts.agentSourceDirs ?? agentSourceDirs();
+    const candidates = dirs.map(dir => path.join(dir, mdFileName(TRACKER_AGENT_NAME)));
+    const source = await firstExisting(candidates);
+    if (source === undefined) {
+        warn(`tracker: agent source not found for "${TRACKER_AGENT_NAME}" (searched: ${candidates.join(', ')}) — ` +
+            `run \`npm run build:mds\` if it is compiled from an .mds generator host`);
+        // Probed rather than assumed: a previous run may have left a copy that is
+        // still spawnable, and that is the difference between "this run did nothing"
+        // and "there is nothing there".
+        return { converged: false, agentPresent: await pathExists(target), agent: 'unchanged' };
+    }
+    // Already converged — nothing to write, and nothing for the summary to announce.
+    // The directory is not created either: an identical file at the target means it is
+    // already there (see {@link copyWouldChangeNothing}).
+    if (await copyWouldChangeNothing(source, target)) {
+        return { converged: true, agentPresent: true, agent: 'unchanged' };
+    }
+    try {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.copyFile(source, target);
+    }
+    catch (err) {
+        warn(`tracker: failed to install the Tracker agent (${target}) — ${String(err)}`);
+        return { converged: false, agentPresent: await pathExists(target), agent: 'unchanged' };
+    }
+    return { converged: true, agentPresent: true, agent: 'installed' };
+}
+//# sourceMappingURL=tracker-install.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {
@@ -26,7 +26,8 @@
     "version:bump": "npx tsx scripts/bump-version.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:integration": "vitest run --config vitest.integration.config.ts"
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:golden:update": "npx tsx scripts/update-golden.ts"
   },
   "keywords": [
     "claude",
@@ -63,7 +64,7 @@
     "@clack/prompts": "^0.9.1",
     "commander": "^12.0.0",
     "picocolors": "^1.1.1",
-    "subswitch": "0.2.0"
+    "subswitch": "0.5.0"
   },
   "devDependencies": {
     "@mdscript/mds": "0.2.0",

package/src/assets/agents/code.md

@@ -28,11 +28,14 @@ You receive from orchestrator:
 - **EXECUTION_PLAN**: Synthesized plan with steps, files, tests
 - **PATTERNS**: Codebase patterns to follow
 - **CREATE_PR**: Whether to create PR when done (true/false)
-- **OPERATION** (optional): `implement` (default) | `issue-fix` | `validation-fix` | `alignment-fix` | `qa-fix` — selects operating mode (see below)
+- **OPERATION** (optional): `implement` (default) | `issue-fix` | `validation-fix` | `alignment-fix` | `qa-fix` | `pr-create` — selects operating mode (see below)
 - **ISSUES** (when OPERATION: issue-fix): Pre-classified issues from Triage agent with disposition FIX_NOW; do not re-litigate
 - **SCOPE** (when OPERATION: issue-fix): Blast-radius scope hint (Standard | Careful) per issue from Triage agent
 - **PUSH** (optional): `true` (default) | `false` — when false, commit only; orchestrator owns push/CI gate
-- **ISSUE_NUMBER** (optional): GitHub issue number linked to this task — when provided, include `## Related Issues` / `Closes #{n}` in the PR body
+- **ISSUE_NUMBER** (optional): the provider-canonical identifier of the issue linked to this task — the same value the Git agent emits as `- **Issue ID**: {ISSUE_ID}` under `### Handoff Values`. When provided, include a `## Related Issues` section in the PR body, closed by the line Responsibility 7's paste gate admits
+- **ISSUE_PR_LINK** (optional): the already-rendered closing line for `## Related Issues`, forwarded verbatim from the Git agent's `- **PR link line**: {rendered}` under `### Handoff Values`. `(none)`, or absent, means no rendered line was captured — the section then carries its heading and no reference. Paste it only after the shape re-check in Responsibility 7; it is never a substitute for `ISSUE_NUMBER`, which stays the spawn key
+- **PR_EXCEPTIONS** (optional): the pre-rendered `## Evidence Exceptions` section — a self-attested evidence exception /implement recorded when no ticket was linked — forwarded verbatim from its handoff file. `(none)`, or absent, means none was recorded and the body carries no such section. Paste it only after the shape re-check in Responsibility 7
+- **PR_TEST_PLAN_BLOCK** (optional): the pre-rendered test-plan block — the task's test plan as /implement rendered it with `verify-evidence.cjs render --plan` — forwarded verbatim. `(none)`, or absent, means there is no test plan to show and the body carries no block. Paste it only after the `check block` gate in Responsibility 7
 
 **Domain hint** (optional):
 - **DOMAIN**: `backend` | `frontend` | `tests` | `fullstack` - Load/apply relevant domain skills
@@ -90,9 +93,33 @@ When you apply a decision from `.devflow/learning/decisions.md` or avoid a pitfa
    | Key Changes to Highlight | Changes |
    | Breaking Changes | Breaking Changes |
    | Reviewer Focus Areas | Reviewer Focus Areas |
-   | Related Issues (ISSUE_NUMBER provided) | `## Related Issues` · `Closes #{n}` |
+   | Related Issues (ISSUE_NUMBER provided) | `## Related Issues` · the admitted link line |
 
-   When `ISSUE_NUMBER` is provided, always include `## Related Issues` / `Closes #{n}` in the PR body — whether composing from guidance or generating from context.
+   When `ISSUE_NUMBER` is provided, always include a `## Related Issues` section in the PR body — whether composing from guidance or generating from context.
+
+   **Pasting the handoff values.** The Git agent's `setup-task` and `fetch-issue` Output blocks end with a `### Handoff Values` block: `- **PR link line**: {rendered}` is the already-rendered closing line for `## Related Issues`, and `- **Branch token**:` is the branch name it created or suggested. Paste `ISSUE_PR_LINK` verbatim — **after re-checking its shape against the tracker reference grammars**: paste it only if it matches **one row** of this table as the WHOLE line:
+
+   | Tracker grammar | `ISSUE_PR_LINK` must match |
+   |---|---|
+   | `github` | `^Closes #[1-9][0-9]{0,8}$` |
+   | `jira` | `^Refs [A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$` |
+   | `linear` | `^Refs [A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` |
+
+   This is a sink check, not a provider check: the Git agent resolved the provider and rendered the line, you are not told which provider it was, and you never decide it. Two bounds sit outside the pattern because an anchor cannot express them, and you apply both: the value is **rejected if it carries a newline** — anchors are read as end-of-LINE by some engines, and everything after the first line would land in the PR body as free text — and rejected if it exceeds **60 characters**, which no valid line approaches.
+
+   `(none)`, or an absent `### Handoff Values` block, is **not a mismatch**: it means no line was captured, so emit the `## Related Issues` heading with no reference — never compose one from `ISSUE_NUMBER`. A bare issue number is not a reference at all — the same digits name a different issue under each provider — which is why `TRACEABILITY: DEGRADED (ambiguous issue reference)` exists rather than a `#`-prefixed guess. On a MISMATCH, do not paste it and do not repair it — emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)` and emit the heading with no reference.
+
+   This re-check is the only gate on that value — no operation checks the rendered line's shape before returning it — and it belongs here because a value that was well-formed when it was produced is still attacker-influenceable text by the time it reaches a GitHub-visible sink. Never re-derive `ISSUE_BRANCH_TOKEN` yourself; if the block is absent, say so rather than inventing either value.
+
+   **Pasting `PR_EXCEPTIONS`.** When `PR_EXCEPTIONS` is provided (not `(none)`), append it verbatim as the body's last section — it is scrubbed with the body. Re-check its shape first: its first line must be exactly `## Evidence Exceptions`, and every line after it must match this pattern as the WHOLE line:
+
+   ```
+   ^- `(ticket-link|test-plan)` self-attested by (@[A-Za-z0-9][A-Za-z0-9-]{0,38}|\(login unavailable\)) at [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z: [!"%'()*+,.0-9:;=?A-Z^_a-z{|}~-][ !"%'()*+,.0-9:;=?A-Z^_a-z{|}~-]{0,199}$
+   ```
+
+   The value holds that heading and one or more such lines, and nothing else — no blank line, no second heading, no free text — with each kind at most once. The pattern bounds every line: the reason is at most 200 characters, and it admits no `<`, `>`, backtick, bracket, backslash, `/`, `#`, `@`, `&`, `$` or non-ASCII character, so no markup, mention, issue reference (a full issue URL included), marker or shell expansion rides in on it. `(none)`, or absent, is **not a mismatch**: add no section. On a MISMATCH anywhere, paste none of it and do not repair it — emit `TRACEABILITY: DEGRADED (evidence exception does not match its grammar)`. The scrubber-failure minimal body below never carries the section.
+
+   **Pasting `PR_TEST_PLAN_BLOCK`.** When `PR_TEST_PLAN_BLOCK` is provided (not `(none)`), save it byte for byte to a fresh `mktemp` file with the Write tool — never through an interpolated shell string — and run `node "${DEVFLOW_DIR:-$HOME/.devflow}/scripts/verify-evidence.cjs" check block <that file>; echo "exit=$?"`. The script holds the block's whole grammar; only `exit=0` admits the value. Then append it verbatim, before any `## Evidence Exceptions` section — it is scrubbed with the body. Any other result is a MISMATCH: omit the block, never repair or partly paste it, and emit `TRACEABILITY: DEGRADED (test-plan block does not match its grammar)`. `(none)`, or absent, is **not a mismatch**: add no block. The scrubber-failure minimal body below never carries the block.
 
    If `PR_DESCRIPTION_GUIDANCE` is absent, generate the PR body from implementation context.
 
@@ -170,6 +197,17 @@ When `OPERATION: qa-fix`, you are fixing scenario-based acceptance test failures
 1. Fix only what is listed in `QA_FAILURES` — no scope expansion
 2. Commit and push; orchestrator re-runs Validate agent then Test agent after each attempt (max 2 attempts total)
 
+## Mode: pr-create
+
+When `OPERATION: pr-create`, earlier Code agents have already committed the implementation and you only open the pull request. Make no code changes.
+
+**Inputs:** `TASK_ID`, `BASE_BRANCH`, `CREATE_PR: true`, `PR_DESCRIPTION_GUIDANCE`, `ISSUE_NUMBER`, `ISSUE_PR_LINK`, `PR_EXCEPTIONS`, `PR_TEST_PLAN_BLOCK`
+
+**Protocol:**
+1. Push the current feature branch.
+2. Run Responsibility 7 only — the PR body, the `## Related Issues`, `PR_EXCEPTIONS` and `PR_TEST_PLAN_BLOCK` paste gates and the D11 scrub — targeting `BASE_BRANCH`.
+3. Return the PR URL.
+
 ## Principles
 
 1. **Work on feature branch** - All operations happen on the current feature branch

package/src/assets/agents/design.md

@@ -1,6 +1,6 @@
 ---
 name: Design
-description: Design analysis agent with preloaded mode skills. Modes: gap-analysis (completeness, architecture, security, performance, compliance, consistency, dependencies), design-review (anti-pattern detection).
+description: "Design analysis agent with preloaded mode skills. Modes: gap-analysis (completeness, architecture, security, performance, compliance, consistency, dependencies), design-review (anti-pattern detection)."
 model: opus
 skills:
   - devflow:worktree-support