avtc-pi-featyard 1.1.0

package/src/prompts/skill-expansion.ts

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Skill expansion — template substitution and skill command expansion.
+ * Handles all {{PI_FY_*}} placeholder resolution and finish instruction generation.
+ */
+
+import { getBranchOrShortSha } from "../git/git-queries.js";
+import { resolveMainRepoPathSync } from "../git/worktrees/worktree-lifecycle.js";
+import type { AutoAgentCallback } from "../kanban/auto-agent/auto-agent-state-machine.js";
+import { getLoopCountForPhase } from "../phases/phase-transitions.js";
+import {
+  buildCurrentBranchAutoAgentSection,
+  buildCurrentBranchInteractiveSection,
+  buildWorktreeAutoAgentSection,
+  buildWorktreeInteractiveSection,
+  type FinishContext,
+} from "../prompts/finish-instructions.js";
+import { expandSkillCommand as _expandSkillCommand } from "../prompts/skill-block-builder.js";
+import { substitutePlaceholders } from "../prompts/template-engine.js";
+import { IMPLEMENTER_GUIDANCE } from "../prompts/text-blocks.js";
+import { getSettings } from "../settings/settings-ui.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import { type FeatureState, flowToExecutionMode, isSubagentMode } from "../state/feature-state.js";
+
+/** Pass as `handler` when no handler reference is available. */
+export const NO_HANDLER: FeatureSession | null = null;
+/** Function type of the `getEmptyLoopsForSlug` skill-expansion param (empty-loop counts per slug, or null). */
+export type GetEmptyLoopsForSlug = ((slug: string) => Record<string, number> | undefined) | null;
+/** Function type of the `getAutoAgentCb` skill-expansion param (auto-agent callback provider, or null). */
+export type GetAutoAgentCb = (() => AutoAgentCallback | null) | null;
+/** Pass as `getEmptyLoopsForSlug` when no empty-loop tracking is available. */
+export const NO_EMPTY_LOOPS_FN: GetEmptyLoopsForSlug = null;
+/** Pass as `featureStateOverride` when no override is needed. */
+export const NO_FEATURE_STATE_OVERRIDE: FeatureState | null = null;
+/** Pass as `getAutoAgentCb` when no auto-agent callback is available. */
+export const NO_AUTO_AGENT_CB: GetAutoAgentCb = null;
+
+export interface SubstitutionResult {
+  text: string;
+}
+
+function buildWorktreeContextSection(
+  worktreePath: string,
+  slug: string,
+  baseBranch: string,
+  mainRepoPath: string | null,
+): string {
+  return [
+    "## Worktree Context",
+    "",
+    "You are working in a git worktree created by the extension.",
+    `- Worktree path: ${worktreePath}`,
+    ...(mainRepoPath ? [`- Main repo path: ${mainRepoPath}`] : []),
+    `- Feature branch: feature/${slug}`,
+    `- Base branch: ${baseBranch}`,
+    "",
+    "You are working in a git worktree. The extension rewrites all tool paths automatically — use relative paths as normal.",
+    "",
+    `All subagent dispatches MUST include \`cwd: "${worktreePath}"\` — this applies to all modes: single (\`cwd\`), parallel (\`tasks[].cwd\`), and chain (\`chain[].cwd\`). Subagents without \`cwd\` start in the main repo, not the worktree.`,
+    "",
+    "To sync from base branch:",
+    "1. `git remote` — check if remote exists",
+    `2. If remote exists: \`git fetch origin && git merge origin/${baseBranch}\``,
+    `3. If no remote: \`git merge ${baseBranch}\` (local branch only)`,
+    "",
+    "Do NOT create or remove worktrees — the extension manages them.",
+  ].join("\n");
+}
+
+/**
+ * Substitute all known PI_FY_* template placeholders in the given text.
+ * Returns the modified text (or original if no placeholders found) and
+ * metadata about whether the guardrail whitelist should be activated.
+ */
+export function substituteTemplates(
+  text: string,
+  handler: FeatureSession | null,
+  getEmptyLoopsForSlug: GetEmptyLoopsForSlug,
+  featureStateOverride: FeatureState | null,
+  getAutoAgentCb: GetAutoAgentCb,
+  agentName: string | null,
+): SubstitutionResult {
+  const settings = getSettings();
+
+  // Cache feature state for the active slug — avoids repeated disk reads + JSON.parse.
+  // Derive the slug from the handler when available, else from the override (so generic
+  // placeholders like {{PI_FY_WORTH_NOTES_PATH}} resolve in tests/dispatch without a handler).
+  const cachedFeatureState = featureStateOverride ?? handler?.getActiveFeatureState() ?? undefined;
+  const activeSlug = handler?.getActiveFeatureSlug() ?? cachedFeatureState?.featureSlug ?? undefined;
+
+  // {{PI_FY_IMPLEMENT_MODE}} — inject fy-implementer guidance (current-session) or orchestrator
+  // dispatch instructions (subagent) based on executionMode.
+  // - current-session: the main agent implements directly, so it gets the FULL fy-implementer guidance
+  //   (IMPLEMENTER_GUIDANCE — pre-resolved with architecture principles + attention inlined, so no
+  //   nested substitution; it carries Blockers, so fy-implement needs no separate When-to-Stop).
+  // - subagent: the main agent is the orchestrator (dispatches fy-implementer subagents that carry their
+  //   own guidance); it gets dispatch instructions + escalation (when to stop/escalate to the user).
+  if (text.includes("{{PI_FY_IMPLEMENT_MODE}}")) {
+    const subagent = isSubagentMode(flowToExecutionMode(getSettings().implementMode));
+    const instruction = subagent
+      ? [
+          "Dispatch an fy-implementer subagent:",
+          "",
+          "```ts",
+          'subagent({ agent: "fy-implementer", task: "... task prompt ..." })',
+          "```",
+          "",
+          "Task prompt should include: task number, design section, scene-setting context (dependencies from previous tasks), working directory.",
+          "",
+          "If the fy-implementer reports uncertainties or assumptions: re-dispatch with clarifications if critical, or accept and note for review.",
+          "",
+          "⚠️ Never dispatch multiple implementation subagents in parallel (file conflicts).",
+          "⚠️ Never write code yourself — you are the orchestrator.",
+          "",
+          "**Escalate to the user and stop if an fy-implementer subagent:** reports a blocker it cannot resolve, reports that the plan is wrong, or fails twice on the same task. Do not silently work around it.",
+        ].join("\n")
+      : IMPLEMENTER_GUIDANCE;
+    text = text.replaceAll("{{PI_FY_IMPLEMENT_MODE}}", instruction);
+  }
+
+  // {{PI_FY_WORTH_NOTES}} — worth-notes handling, branches on executionMode.
+  // Subagent mode: the implementer reports worth-notes; the orchestrator appends them.
+  // Direct mode: the in-session implementer appends its own worth-notes directly.
+  if (text.includes("{{PI_FY_WORTH_NOTES}}")) {
+    const subagent = isSubagentMode(flowToExecutionMode(getSettings().implementMode));
+    const instruction = subagent
+      ? "Collect worth-notes from each implementer subagent's final report and append them to `{{PI_FY_WORTH_NOTES_PATH}}`: out-of-scope code smells needing refactoring, bugs you could not fix, and anything strange (what and where)."
+      : "When you notice an out-of-scope code smell, a bug you cannot fix, or anything strange during your work, append it to `{{PI_FY_WORTH_NOTES_PATH}}` (what and where).";
+    text = text.replaceAll("{{PI_FY_WORTH_NOTES}}", instruction);
+  }
+
+  // {{PI_FY_WORKTREE_CONTEXT}} — worktree paths, subagent CWD, sync commands
+  if (text.includes("{{PI_FY_WORKTREE_CONTEXT}}")) {
+    if (settings.branchPolicy === "worktree") {
+      const slug = handler?.getActiveFeatureSlug() ?? null;
+      if (!slug) {
+        // No active feature — expand to empty (not a worktree failure)
+        text = text.replaceAll("{{PI_FY_WORKTREE_CONTEXT}}", "");
+      } else {
+        const fsData = cachedFeatureState;
+        if (fsData?.git?.worktreePath) {
+          const mainRepoPath = resolveMainRepoPathSync();
+          const baseBranch = fsData.git.baseBranch ?? settings.baseBranch ?? "main";
+          text = text.replaceAll(
+            "{{PI_FY_WORKTREE_CONTEXT}}",
+            buildWorktreeContextSection(fsData.git.worktreePath, slug, baseBranch, mainRepoPath),
+          );
+        } else {
+          // Worktree creation failed
+          text = text.replaceAll(
+            "{{PI_FY_WORKTREE_CONTEXT}}",
+            "⚠️ Worktree creation failed. You are working in the main repo directory. Do NOT set cwd on subagent dispatches — let them inherit the main repo path.",
+          );
+        }
+      }
+    } else {
+      // current-branch policy — no worktree context
+      text = text.replaceAll("{{PI_FY_WORKTREE_CONTEXT}}", "");
+    }
+  }
+
+  // {{PI_FY_FINISH_INSTRUCTIONS}}
+  // 4 variants: branchPolicy × autoAgentActive
+  const hasFinishPlaceholder = text.includes("{{PI_FY_FINISH_INSTRUCTIONS}}");
+  if (hasFinishPlaceholder) {
+    const autoAgentCb = getAutoAgentCb?.();
+    const isActive = autoAgentCb?.isActive?.();
+    const branchPolicy = settings.branchPolicy ?? "current-branch";
+    const settingsBaseBranch = settings.baseBranch ?? null;
+    // Feature state baseBranch takes precedence (set during worktree creation — see DD-11)
+    let baseBranch = settingsBaseBranch;
+    let featureWorktreePath: string | null = null;
+    if (activeSlug) {
+      const featureState = cachedFeatureState;
+      if (featureState?.git?.baseBranch) {
+        baseBranch = featureState.git.baseBranch;
+      }
+      if (featureState?.git?.worktreePath) {
+        featureWorktreePath = featureState.git.worktreePath;
+      }
+    }
+    const currentBranch = getBranchOrShortSha(process.cwd());
+
+    const finishCtx: FinishContext = {
+      baseBranch,
+      currentBranch,
+      worktreePath: featureWorktreePath,
+      mainRepoPath: null,
+      slug: activeSlug,
+      worktreeFallbackWarning:
+        branchPolicy === "worktree" && !featureWorktreePath
+          ? "⚠️ Worktree creation failed — code is on feature branch, NOT merged to baseBranch. Merge manually."
+          : null,
+    };
+
+    let section: string;
+
+    if (branchPolicy === "worktree" && featureWorktreePath) {
+      // --- Worktree policy ---
+      finishCtx.mainRepoPath = resolveMainRepoPathSync();
+
+      section = isActive ? buildWorktreeAutoAgentSection(finishCtx) : buildWorktreeInteractiveSection(finishCtx);
+    } else {
+      // --- Current-branch policy (or worktree without worktreePath — fallback) ---
+      section = isActive
+        ? buildCurrentBranchAutoAgentSection(finishCtx)
+        : buildCurrentBranchInteractiveSection(finishCtx);
+    }
+
+    text = text.replaceAll("{{PI_FY_FINISH_INSTRUCTIONS}}", section);
+  }
+
+  // Apply generic placeholder substitution (PI_FY_REVIEWER_SKIP, etc.)
+  const emptyLoops = activeSlug ? getEmptyLoopsForSlug?.(activeSlug) : undefined;
+
+  // Current workflow phase — drives review-iteration context placeholders
+  // (REVIEW_LOOP_CONTEXT, REVIEW_METHOD) and loop-index derivation.
+  const phase = handler?.getWorkflowState()?.currentPhase;
+
+  // Derive loop index from feature state based on current phase for report file naming
+  let loopIndex: number | undefined;
+  if (activeSlug && phase) {
+    loopIndex = getLoopCountForPhase(cachedFeatureState ?? null, phase);
+  }
+
+  return {
+    text: substitutePlaceholders(text, {
+      emptyLoops,
+      slug: activeSlug,
+      loopIndex,
+      baseCommitSha: cachedFeatureState?.git?.baseCommitSha ?? undefined,
+      agentName,
+      phase: phase ?? undefined,
+      taskName: cachedFeatureState?.implement.currentTask ?? undefined,
+    }),
+  };
+}
+
+/**
+ * Expand a /skill:name command into the <skill> XML block that pi core
+ * would produce via _expandSkillCommand(). Also substitutes {{PI_FY_*}}
+ * template placeholders in the skill body.
+ *
+ * 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,
+  handler: FeatureSession | null,
+  getEmptyLoopsForSlug: GetEmptyLoopsForSlug,
+  featureStateOverride: FeatureState | null,
+  getAutoAgentCb: GetAutoAgentCb,
+  agentName: string | null,
+): string {
+  const result = _expandSkillCommand(
+    text,
+    (t) => substituteTemplates(t, handler, getEmptyLoopsForSlug, featureStateOverride, getAutoAgentCb, agentName).text,
+  );
+  return result;
+}

package/src/prompts/task-gate-skill.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * The dispatched per-task gate mini-skill (`fy-task-gate`).
+ *
+ * In the dispatch model, `task_ready_advance` decides after each call whether to
+ * dispatch another gate round or advance. When it dispatches, it sends a fresh
+ * `<skill name="fy-task-gate">` block via `sendUserMessage({ deliverAs: "steer" })`
+ * — authoritative (survives compaction), arrives after turn-end or the next tool
+ * call (robust to the model not ending its turn).
+ *
+ * This is a CODE CONSTANT, NOT a registered `skills/` file: it is never
+ * `/skill`-invoked by the user. The non-empty `location=" "` makes the TUI
+ * collapse the block into one `fy-task-gate` item.
+ *
+ * `buildTaskGateSkill` assembles only the gates the caller selected to run
+ * (the caller decides which gates to run per the asymmetric respawn rule). It leaves `{{PI_FY_*}}` markers INTACT — the context
+ * handler substitutes them inside `<skill>` blocks at the next LLM call, with the
+ * real feature slug/phase; pre-substituting here (no slug/phase in scope) would
+ * lock in a wrong date-based path the context handler cannot fix.
+ */
+
+export interface TaskGateSkillInput {
+  /** 1-indexed round number being dispatched (round 1 on entry, then round+1 on reloop). */
+  round: number;
+  /** The current task the gate is gating (the model is told it is not ready to advance). */
+  task: string;
+  /** The next task to advance to, or undefined when on the last task (nextTask omitted in the example call). */
+  next: string | undefined;
+  /** Dispatch the #### Verify section (fy-task-verifier). */
+  runVerifier: boolean;
+  /** Dispatch the #### Review section (fy-general-reviewer). */
+  runReviewer: boolean;
+}
+
+/** Escape model-provided task names so they cannot break the `<skill>` tag boundary, the
+ *  `nextTask: "..."` quoting, or the markdown code spans in the skill body. The task/next
+ *  values originate from plan content; this is defense-in-depth, not an adversarial sink.
+ *  Exported because the same task name is interpolated into tool-result / compact
+ *  follow-up messages that also reach pi's message pipeline. */
+export function sanitizeSkillText(value: string): string {
+  return value.replace(/</g, "&lt;").replace(/"/g, "&quot;").replace(/`/g, "'");
+}
+
+/** Assemble the per-task gate skill body and wrap it as a collapsed `<skill>` block. */
+export function buildTaskGateSkill({ round, task, next, runVerifier, runReviewer }: TaskGateSkillInput): string {
+  const safeTask = sanitizeSkillText(task);
+  const safeNext = next === undefined ? undefined : sanitizeSkillText(next);
+  const nextParam = safeNext === undefined ? "" : `, nextTask: "${safeNext}"`;
+
+  const verifySection = runVerifier
+    ? `
+#### Verify
+Spawn fy-task-verifier — \`subagent({ agent: "fy-task-verifier", task: "..." })\`.
+Task prompt: diff base (the commit before this task's first commit — fixed across all verify rounds; if unknown, find it with \`git log\`), diff head (current HEAD).
+Treat \`⏭️ deferred\` like \`❌ missing\`: the work is not done.
+`
+    : "";
+
+  const reviewSection = runReviewer
+    ? `
+#### Review
+Spawn fy-general-reviewer — \`subagent({ agent: "fy-general-reviewer", task: "..." })\`.
+Task prompt: implementer's report, diff base (the commit before this task's first commit — fixed across all review rounds; if unknown, find it with \`git log\`), diff head (current HEAD).
+`
+    : "";
+
+  const body = `# Per-Task Gate — Round ${round}
+
+Task "${safeTask}" is not ready to advance. Run the gates below, triage, then call task_ready_advance again.
+${verifySection}${reviewSection}
+#### Triage
+- **Fixable** → fix it; count it (verifierIssuesFixed / reviewerIssuesFixed).
+- **False-positive** → append to {{PI_FY_KNOWN_ISSUES_PATH}}.
+- **Cannot-fix** (external blocker / missing dependency / breaking API contract) → escalate to the user.
+
+Then call \`task_ready_advance({ verifierIssuesFixed: <count>, reviewerIssuesFixed: <count>${nextParam} })\` and follow its result — end your turn if it asks.
+`;
+
+  return `<skill name="fy-task-gate" location=" ">
+${body}</skill>`;
+}