avtc-pi-featyard 1.1.0

package/src/phases/phase-transitions.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Phase transition helpers — model override resolution, loop index calculation,
+ * and phase-aware loop count lookup.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  cleanupWorktreeOnFinishWrapper as _cleanupWorktreeOnFinish,
+  syncWorktreeStatus,
+} from "../git/worktrees/worktree-helpers.js";
+import { moveFeatureToLane } from "../kanban/data/kanban-move-feature.js";
+import { log, NO_ERROR } from "../log.js";
+import { DEFAULT_GLOBAL_DIR, loadFeatyardConfig, resolveModelOverride } from "../settings/settings-ui.js";
+import { NO_AGENT_NAME, NO_FEATURE_STATE_OVERRIDE } from "../shared/workflow-refs.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import {
+  DEFAULT_DIR,
+  type ExpandSkillCommandFn,
+  type FeatureState,
+  markFeatureDone,
+  saveFeatureState,
+  syncAndSaveFeatureState,
+} from "../state/feature-state.js";
+import { schedulePostTurnFollowUp } from "../state/post-turn-dispatch.js";
+import { persistState } from "../state/state-persistence.js";
+import { notifyFeatureCompleted } from "../state/worth-notes.js";
+import { NO_FEATURE_STATE, updateWidget } from "../ui/featyard-widget.js";
+
+/**
+ * Get the appropriate loop count for a given phase from feature state.
+ */
+export function getLoopCountForPhase(featureState: FeatureState | null, phase: string): number {
+  if (!featureState) return 0;
+  if (phase === "design") return featureState.design.reviewLoopCount ?? 0;
+  if (phase === "plan") return featureState.plan.reviewLoopCount ?? 0;
+  return featureState.review.reviewLoopCount ?? 0;
+}
+
+/**
+ * Parse a "provider/id" model reference string.
+ */
+export function parseModelRef(ref: string): { provider: string; id: string } {
+  const idx = ref.indexOf("/");
+  return { provider: ref.slice(0, idx), id: ref.slice(idx + 1) };
+}
+
+/**
+ * Apply model override for in-session skill dispatch (review, design).
+ * Resolves override from config, looks up full Model via modelRegistry,
+ * and calls pi.setModel. No-op when no override is configured.
+ */
+export async function applyModelOverride(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  stage: string,
+  loopIndex: number,
+): Promise<void> {
+  const config = loadFeatyardConfig(DEFAULT_GLOBAL_DIR, process.cwd());
+  const ref = resolveModelOverride(stage, loopIndex, config);
+  if (!ref) return;
+
+  const { provider, id } = parseModelRef(ref);
+  const model = ctx.modelRegistry?.find?.(provider, id);
+  if (!model) {
+    log.warn(`[workflow] Model override not found in registry: ${provider}/${id}`);
+    return;
+  }
+
+  await pi.setModel(model);
+  log.info(`[workflow] Model override applied for stage '${stage}': ${provider}/${id}`);
+}
+
+/** Dependencies for transitionToFinishPhase. */
+export interface FinishTransitionDeps {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  handler: FeatureSession;
+  applyModelOverrideForPhase: (pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>;
+  expandSkillCommand: ExpandSkillCommandFn;
+}
+
+/**
+ * Execute the finish-phase transition sequence shared by the review loop and the workflow commands.
+ *
+ * Encapsulates: advance to finish, model override, feature state sync, persistence, widget
+ * update, and dispatch of the fy-finish skill as a followUp. Does NOT touch UAT — callers
+ * handle the UAT decision (skip / hand off) separately, before or instead of this call.
+ */
+export async function transitionToFinishPhase(
+  featureState: FeatureState | null,
+  deps: FinishTransitionDeps,
+): Promise<void> {
+  const { pi, ctx, handler, applyModelOverrideForPhase, expandSkillCommand } = deps;
+
+  handler.setCurrentPhase("finish");
+  await applyModelOverrideForPhase(pi, ctx, "finish");
+  if (featureState) {
+    syncAndSaveFeatureState(featureState, handler);
+  }
+  persistState(pi, handler);
+  updateWidget(handler, NO_FEATURE_STATE);
+  schedulePostTurnFollowUp(expandSkillCommand("/skill:fy-finish", NO_FEATURE_STATE_OVERRIDE, NO_AGENT_NAME));
+}
+
+/** Dependencies for completeFeature. */
+export interface CompleteFeatureDeps {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  handler: FeatureSession;
+  getAutoAgentCallback: () => { onFeatureComplete?: (slug: string) => void } | null | undefined;
+}
+
+/**
+ * Finalize a completed feature — the completion side-effects shared by every
+ * terminal routing path (fy:next from the terminal phase, uat-accept after-finish).
+ *
+ * Clears the finish-phase guardrail flag, cleans up the worktree, marks the
+ * feature done, clears the active-feature pointer + env, notifies the user, and
+ * fires the auto-agent onFeatureComplete callback. Idempotent in effect: callers
+ * route here ONLY on a {completed:true} RouteResult.
+ */
+export async function completeFeature(
+  slug: string,
+  featureState: FeatureState,
+  deps: CompleteFeatureDeps,
+): Promise<void> {
+  const { pi, ctx, handler, getAutoAgentCallback } = deps;
+
+  await _cleanupWorktreeOnFinish(featureState, ctx);
+  // Mark done (completedAt) and keep the slot active with the done state, so the
+  // widget renders a terminal DONE line until the next feature displaces it.
+  // (done = visible: do NOT clear the active feature / env on completion)
+  const doneState = markFeatureDone(featureState);
+  saveFeatureState(doneState, DEFAULT_DIR);
+  handler.setActiveFeatureState(doneState);
+  // Sync the worktree status icon for the done state (completion is the off-signal
+  // clears the icon regardless of whether worktree removal succeeded).
+  syncWorktreeStatus(doneState);
+  // Emit the completion notify with the worth-notes pointer merged in.
+  notifyFeatureCompleted(slug);
+
+  try {
+    const autoAgentCb = getAutoAgentCallback();
+    if (autoAgentCb?.onFeatureComplete) {
+      autoAgentCb.onFeatureComplete(slug);
+    }
+  } catch (err) {
+    log.error(`[workflow] auto-agent callback error on feature completion: ${err}`, NO_ERROR);
+  }
+
+  persistState(pi, handler);
+  updateWidget(handler, NO_FEATURE_STATE);
+}
+export interface UatTransitionDeps {
+  pi: ExtensionAPI;
+  handler: FeatureSession;
+  applyModelOverrideForPhase: (pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>;
+  getAutoAgentCallback: () => { onFeatureUatHandoff?: (slug: string) => void } | null | undefined;
+}
+
+/**
+ * Execute the full UAT phase transition sequence.
+ *
+ * Encapsulates: handler transition, model override, feature state sync,
+ * kanban lane move, persistence, widget update, user notification,
+ * and auto-agent callback.
+ *
+ * @param opts.skipUat - If true, marks UAT as complete/bypassed (no kanban move, no notification)
+ * @param opts.kanbanNote - Custom note for kanban lane move
+ * @param opts.notifyMessage - Custom notification message; if omitted, no notification is sent
+ * @param opts.notifyLevel - Level for the notifyMessage ("info" | "warning"); defaults to "info".
+ *  Used by the worth-notes merge to preserve a review report's warning level when the
+ *  merged notify had cannot-fix issues.
+ */
+export async function transitionToUatPhase(
+  ctx: ExtensionContext,
+  slug: string,
+  featureState: FeatureState | null,
+  deps: UatTransitionDeps,
+  opts: { skipUat?: boolean; kanbanNote?: string; notifyMessage?: string; notifyLevel?: "info" | "warning" } = {},
+): Promise<void> {
+  const { pi, handler, applyModelOverrideForPhase, getAutoAgentCallback } = deps;
+
+  handler.setCurrentPhase(opts.skipUat ? "finish" : "uat");
+  await applyModelOverrideForPhase(pi, ctx, "uat");
+
+  if (featureState) {
+    syncAndSaveFeatureState(featureState, handler);
+
+    if (!opts.skipUat && featureState.featureId != null) {
+      try {
+        await moveFeatureToLane({
+          featureId: featureState.featureId,
+          toLane: "uat",
+          fromLane: undefined,
+          note: opts.kanbanNote ?? "review complete — UAT handoff",
+        });
+      } catch (err) {
+        log.warn(`[workflow] kanban lane move to uat failed: ${err}`);
+      }
+    }
+  }
+
+  persistState(pi, handler);
+  updateWidget(handler, NO_FEATURE_STATE);
+
+  if (opts.notifyMessage) {
+    const guard = globalThis.__piCtx;
+    if (guard?.hasUI && guard?.ui?.notify) {
+      guard.ui.notify(opts.notifyMessage, opts.notifyLevel ?? "info");
+    }
+  }
+
+  try {
+    const autoAgentCb = getAutoAgentCallback();
+    if (autoAgentCb?.onFeatureUatHandoff) {
+      log.info(`[workflow] notifying auto-agent UAT handoff for ${slug}`);
+      autoAgentCb.onFeatureUatHandoff(slug);
+    }
+  } catch (err) {
+    log.error(`[workflow] auto-agent UAT handoff callback error: ${err}`, NO_ERROR);
+  }
+}

package/src/phases/workflow-router.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * WorkflowRouter — sub-loop-aware phase routing policy.
+ *
+ * Owns the "advance one step" routing decision (review/UAT-aware per settings),
+ * kept separate from PhaseProgression (pure pointer math: advance/jump/status/
+ * derive). The router reads the current pointer from a PhaseProgression, decides
+ * the next phase via {@link routeNext}, and applies the move via the progression's
+ * setCurrentPhase — keeping the pointer as the single phase-state source.
+ *
+ * Routing order: design→plan→implement→verify→{review?}→{uat?}→finish→{uat?}→done.
+ * The review phase is skipped when `maxFeatureReviewRounds` is 0. UAT position is
+ * honored per `uatMode`.
+ */
+
+import { log } from "../log.js";
+import type { FeatyardSettings } from "../settings/settings-ui.js";
+import type { Phase, PhaseProgression } from "./phase-progression.js";
+
+export type UatMode = "after-review" | "after-finish" | "off";
+
+/** Whether/how many feature-review rounds run; 0 skips the review phase entirely. */
+export type MaxFeatureReviewRounds = number;
+
+/** Routing configuration derived from featyard settings. The machine routes one
+ *  step per extension advance, honoring both the UAT position and whether the review
+ *  phase is enabled. */
+export interface RouteConfig {
+  uatMode: UatMode;
+  maxFeatureReviewRounds: MaxFeatureReviewRounds;
+}
+
+/** Build the routing config from featyard settings. Centralizes the field selection so
+ *  every phase-advance call site stays in sync with the settings rename. */
+export function toRouteConfig(settings: FeatyardSettings): RouteConfig {
+  return {
+    uatMode: settings.uatMode,
+    maxFeatureReviewRounds: settings.maxFeatureReviewRounds,
+  };
+}
+
+/** Result of routing: advance to a phase, or mark the feature completed. */
+export type RouteResult = { phase: Phase } | { completed: true } | null;
+
+/**
+ * Decide the next phase when the current phase is done (extension-initiated).
+ * User moves call PhaseProgression.setCurrentPhase directly; this encodes ONLY the
+ * "advance one step" rule, routed per settings. Returns null when there is no
+ * current phase.
+ */
+export function routeNext(currentPhase: Phase | null, config: RouteConfig): RouteResult {
+  if (currentPhase === null) return null;
+  switch (currentPhase) {
+    case "design":
+      return { phase: "plan" };
+    case "plan":
+      return { phase: "implement" };
+    case "implement":
+      return { phase: "verify" };
+    case "verify":
+      // Skip the review phase entirely when code review is disabled; otherwise review.
+      return config.maxFeatureReviewRounds === 0 ? routeNext("review", config) : { phase: "review" };
+    case "review":
+      return config.uatMode === "after-review" ? { phase: "uat" } : { phase: "finish" };
+    case "uat":
+      return config.uatMode === "after-finish" ? { completed: true } : { phase: "finish" };
+    case "finish":
+      return config.uatMode === "after-finish" ? { phase: "uat" } : { completed: true };
+  }
+}
+
+/**
+ * Sub-loop-aware phase router. Wraps a {@link PhaseProgression} (the pointer owner)
+ * and applies one-step routing decisions, moving the pointer forward or signaling
+ * completion. Stateless beyond the injected progression — all phase state lives on
+ * the progression.
+ */
+export class WorkflowRouter {
+  constructor(private readonly progression: PhaseProgression) {}
+
+  /**
+   * Extension-initiated advance: the caller has verified the current phase is
+   * done. Routes one step forward (review/uat-aware per settings) and either moves
+   * the pointer or signals completion. Does NOT check completion criteria itself —
+   * that is the caller's responsibility (artifact/task/verification gates).
+   * Returns the routing decision for the handler to apply.
+   */
+  completeCurrent(config: RouteConfig): RouteResult {
+    const result = routeNext(this.progression.getState().currentPhase, config);
+    if (result && "phase" in result) {
+      this.progression.setCurrentPhase(result.phase);
+    }
+    log.info(`[phase] WorkflowRouter.completeCurrent → ${JSON.stringify(result)}`);
+    return result;
+  }
+}

package/src/prompts/finish-instructions.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Finish instruction variant builders.
+ *
+ * Generates branch-specific finish-phase instructions for the agent,
+ * covering worktree and current-branch policies in both auto-agent
+ * and interactive modes.
+ */
+
+export interface FinishContext {
+  baseBranch: string | null;
+  currentBranch: string | null;
+  worktreePath: string | null;
+  mainRepoPath: string | null;
+  slug: string | undefined;
+  /** Non-null when branchPolicy=worktree but no worktreePath exists (creation failed) */
+  worktreeFallbackWarning: string | null;
+}
+
+export function buildWorktreeAutoAgentSection(ctx: FinishContext): string {
+  if (!ctx.baseBranch) {
+    return "### Error\n\nbaseBranch not configured. Set baseBranch in settings before using auto-agent with worktree policy.";
+  }
+  return [
+    "### Auto-Agent Mode",
+    "",
+    "branchPolicy: worktree",
+    `baseBranch: ${ctx.baseBranch}`,
+    `currentBranch: ${ctx.currentBranch ?? "(unknown)"}`,
+    `worktreePath: ${ctx.worktreePath}`,
+    `mainRepoPath: ${ctx.mainRepoPath ?? "(unknown)"}`,
+    "",
+    "1. Verify tests in worktree — if fail, report error and stop",
+    "2. Sync from baseBranch (in worktree — guardrail-relaxed):",
+    `   a. If remote exists: \`git fetch origin\` then \`git merge origin/${ctx.baseBranch}\``,
+    `   b. If no remote: \`git merge ${ctx.baseBranch}\` (local branch)`,
+    "   c. If conflicts → resolve intelligently (see Conflict Resolution section), NOT --theirs",
+    "   d. Re-run tests — the sync merge can break things. If tests fail, investigate whether the merge caused it, fix the merge-induced breakage, and re-run before continuing. If you cannot fix it, report and stop.",
+    "3. Check for uncommitted changes. If present: `git add -A && git commit -m 'feat: <descriptive summary>'`",
+    "4. Merge into baseBranch (guardrail whitelisted during finish phase — see DD-9):",
+    "   a. cd to main repo directory using injected mainRepoPath above",
+    `   b. git checkout ${ctx.baseBranch}`,
+    `   c. git merge feature/${ctx.slug}`,
+    "   d. If conflicts → resolve intelligently (see Conflict Resolution section)",
+    "5. Post-merge verification (see Post-Merge Verification section)",
+    "6. Call phase_ready — extension handles branch deletion and worktree removal",
+    "",
+    "Note: For all uatModes, the agent performs the full merge + verification before calling phase_ready.",
+  ].join("\n");
+}
+
+export function buildWorktreeInteractiveSection(ctx: FinishContext): string {
+  const bb = ctx.baseBranch;
+  return [
+    "### Interactive Mode",
+    "",
+    "branchPolicy: worktree",
+    `baseBranch: ${bb ?? "(not set — will auto-detect)"}`,
+    `currentBranch: ${ctx.currentBranch ?? "(unknown)"}`,
+    `worktreePath: ${ctx.worktreePath}`,
+    `mainRepoPath: ${ctx.mainRepoPath ?? "(unknown)"}`,
+    "",
+    "If baseBranch was auto-detect (not set in settings): run `git branch --show-current` and ask user to confirm the base branch.",
+    "",
+    "Select an option:",
+    `  1. Merge into ${bb ?? "<baseBranch>"} and clean up ← recommended`,
+    "     Note: for `after-finish` UAT mode, the worktree persists between merge and UAT acceptance.",
+    "  2. Push and create a Pull Request (keep worktree)",
+    "  3. Keep as-is (worktree preserved)",
+    '     After selecting: report "Worktree preserved at <path>. Feature remains active." Do NOT call phase_ready.',
+    '  4. Discard (requires typed "discard" confirmation — shows branch, commits, worktree path)',
+    "",
+    "For Option 1 (Merge into baseBranch):",
+    "  a. Sync from baseBranch (in worktree):",
+    `     - If remote exists: \`git fetch origin\` then \`git merge origin/${bb ?? "<baseBranch>"}\``,
+    `     - If no remote: \`git merge ${bb ?? "<baseBranch>"}\` (local branch)`,
+    "     - If conflicts → present to user for resolution",
+    "     - Re-run tests after merge. If tests fail → report, ask whether to proceed",
+    "  b. Merge into baseBranch (from main repo directory, NOT worktree) — guardrail whitelisted during finish phase",
+    "  c. Post-merge verification (see Post-Merge Verification section)",
+    "For Options 2, 3, 4: follow instructions for selected option.",
+  ].join("\n");
+}
+
+export function buildCurrentBranchAutoAgentSection(ctx: FinishContext): string {
+  const onBaseBranch = ctx.currentBranch && ctx.baseBranch && ctx.currentBranch === ctx.baseBranch;
+  const branchNote = onBaseBranch
+    ? '   - Note: "Changes are already on the base branch."'
+    : ctx.baseBranch
+      ? `   - Note: "Work is committed on ${ctx.currentBranch} but NOT merged to ${ctx.baseBranch}. Merge manually when ready."`
+      : '   - Note: "Work is committed on the current branch. Set baseBranch in settings and merge manually."';
+
+  return [
+    ...(ctx.worktreeFallbackWarning ? [ctx.worktreeFallbackWarning, ""] : []),
+    "### Auto-Agent Mode",
+    "",
+    "branchPolicy: current-branch",
+    `baseBranch: ${ctx.baseBranch ?? "(not set)"}`,
+    `currentBranch: ${ctx.currentBranch ?? "(unknown)"}`,
+    "",
+    "1. Verify tests — if fail, report error and stop",
+    "2. Check for uncommitted changes (`git status`). If present: `git add -A && git commit -m 'feat: <descriptive summary>'`",
+    "3. Report done with summary:",
+    `   - Current branch: ${ctx.currentBranch ?? "(unknown)"}`,
+    `   - Base branch: ${ctx.baseBranch ?? "(not set)"}`,
+    "   - Commits on this branch: <count>",
+    "   - Files changed: <list>",
+    branchNote,
+    "4. Call phase_ready",
+    "5. NO merge. NO branch deletion. NO worktree cleanup.",
+  ].join("\n");
+}
+
+export function buildCurrentBranchInteractiveSection(ctx: FinishContext): string {
+  const bb = ctx.baseBranch;
+  return [
+    "### Interactive Mode",
+    "",
+    "branchPolicy: current-branch",
+    `baseBranch: ${bb ?? "(not set — will auto-detect)"}`,
+    "",
+    "1. Run `git branch --show-current` to detect current branch",
+    "2. If baseBranch was auto-detected (not set in settings), confirm with user before proceeding",
+    "3. Present options based on current branch:",
+    "",
+    "  If on baseBranch:",
+    "    1. Done — work is already on baseBranch",
+    '       After selecting: report "Work complete on <branch>." and call phase_ready.',
+    "",
+    "  If on feature branch:",
+    "    1. Keep as-is (I'll handle merging) ← recommended",
+    '       After selecting: report "Work preserved on <branch>." Do NOT call phase_ready.',
+    `    2. Merge into ${bb ?? "<baseBranch>"} locally`,
+    "       If merge is blocked by guardrail, report to user and suggest changing guardrail to 'ask' or 'off', or running the merge manually.",
+    "       After selecting: merge, verify, then call phase_ready.",
+    "    3. Push and create a Pull Request",
+    "       After selecting: push, then call phase_ready.",
+    "    4. Discard this work",
+    "       After selecting: confirm, discard, then call phase_ready.",
+  ].join("\n");
+}

package/src/prompts/skill-block-builder.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+import fs from "node:fs";
+import path from "node:path";
+// stripFrontmatter imported from pi core — handles CRLF normalization correctly
+import { stripFrontmatter } from "@earendil-works/pi-coding-agent";
+import { log } from "../log.js";
+
+/**
+ * Resolve a skill name to its absolute file path.
+ * Only resolves skills from this extension's skills/ directory.
+ * Returns null if the skill file does not exist.
+ */
+function resolveSkillPath(name: string): string | null {
+  // Defense in depth: reject path traversal attempts
+  if (name.includes("/") || name.includes("\\") || name.includes("..")) return null;
+
+  // Skills live at <project-root>/skills/<name>/SKILL.md. This file is at src/prompts/,
+  // so project root is two levels up.
+  const skillsDir = path.resolve(path.join(__dirname, "..", "..", "skills"));
+  const candidate = path.join(skillsDir, name, "SKILL.md");
+  const resolved = path.resolve(candidate);
+
+  // Verify resolved path is contained within the skills directory (logical check)
+  if (!resolved.startsWith(skillsDir + path.sep)) return null;
+
+  // Resolve symlinks to prevent symlink escape attacks
+  try {
+    const realResolved = fs.realpathSync(resolved);
+    const realSkillsDir = fs.realpathSync(skillsDir);
+    if (!realResolved.startsWith(realSkillsDir + path.sep)) return null;
+  } catch {
+    return null;
+  }
+
+  return resolved;
+}
+
+/**
+ * Expand a /skill:name command into the <skill> XML block that pi core
+ * would produce via _expandSkillCommand().
+ *
+ * If `substituteFn` is provided, it's called on the skill body before wrapping
+ * (used by workflow-monitor for {{PI_FY_*}} template substitution).
+ *
+ * Returns the expanded text, or the original text if the skill is not found
+ * or on error (matching pi core's _expandSkillCommand behavior).
+ */
+export function expandSkillCommand(text: string, substituteFn: ((text: string) => string) | null): string {
+  if (!text.startsWith("/skill:")) return text;
+
+  // Find the first whitespace (space or newline) separating skill name from args
+  const rest = text.slice(7);
+  const match = rest.match(/^[a-z0-9-]+/);
+  if (!match) return text;
+  const skillName = match[0];
+  const args = text.slice(7 + skillName.length).trim();
+
+  const skillPath = resolveSkillPath(skillName);
+  if (!skillPath) return text;
+
+  try {
+    const raw = fs.readFileSync(skillPath, "utf-8");
+    let body = stripFrontmatter(raw);
+    if (substituteFn) body = substituteFn(body);
+    const block = `<skill name="${skillName}" location="${skillPath}">\n${body}\n</skill>`;
+    return args ? `${block}\n\n${args}` : block;
+  } catch (err) {
+    log.error(`[skill] Failed to expand skill command: ${skillName}`, err instanceof Error ? err.message : err);
+    return text;
+  }
+}