@jwilger/pi-development-system 0.56.0 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/prompts/devsys-plan.md

@@ -5,8 +5,8 @@ argument-hint: "<slug> [what the plan covers]"
 Write the plan for the current work with the work-intake-and-slicing skill.
 
 1. Slug and scope come from: $ARGUMENTS. If the slug is missing, derive one from the active slice and say which you chose.
-2. Write `docs/plan/<slug>.md` with these sections: Goal and why; Constraints (what must not change); Increments, each shippable on its own and small enough to release; for every task a task record in the format `## <id> — <title>` with **Goal**, **Files**, **Interfaces**, **First failing test**, **Steps**, **Run**, **Expected**, **Out of scope**; a Progress checklist with one box per increment.
+2. Write `docs/plan/<slug>.md` with these sections: Goal and why; Constraints (what must not change); Increments, each shippable on its own and small enough to release, each with an **Acceptance** list (observable checks that say the increment is done) and a final Release step (commit, push, CI green, publish, update) followed by a STOP for the user; for every task a task record whose header is `## <id> — <title>` and whose sections are written exactly as `**Goal:**`, `**Files:**`, `**Interfaces:**`, `**First failing test:**`, `**Steps:**`, `**Run:**`, `**Expected:**`, `**Out of scope:**` (label and colon inside the bold, one section per label); a Progress checklist with one box per increment.
 3. Write each task so that someone who sees only that task could finish it. Never write `TBD`.
 4. Run `devsys_task_check` on every task record you wrote and fix each one until it says ready. Split any that come back too-big.
-5. If a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.
+5. If a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.
 6. Stop and ask the user to review the plan before any implementation starts.

package/skills/work-intake-and-slicing/SKILL.md

@@ -39,7 +39,7 @@ If the plan spells out every line, it has become the implementation, and a revie
 
 ## Task records
 
-Format: `## <id> — <title>` then **Goal**, **Files**, **Interfaces**, **First failing test**, **Steps** (3 to 7, each reviewable alone), **Run**, **Expected**, **Out of scope**.
+Format: `## <id> — <title>` then the sections, each written as a bold label with the colon inside, `**Goal:**`, `**Files:**`, `**Interfaces:**`, `**First failing test:**`, `**Steps:**` (3 to 7, each reviewable alone), `**Run:**`, `**Expected:**`, `**Out of scope:**`.
 
 - Goal is one observable sentence.
 - Run is a command and Expected is its concrete result.

package/src/planning/intake-tool.ts

@@ -1,11 +1,11 @@
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { parseSizing } from "../core/sizing.ts";
-import { isParseError, type Sizing, type SliceRef } from "../core/types.ts";
+import { type DevsysState, isParseError, type Sizing, type SliceRef } from "../core/types.ts";
 import type { Jev } from "../jev/client.ts";
 import { judgeSizing } from "../jev/questions/sizing.ts";
 import type { SessionState } from "../state/session-state.ts";
-import { phaseFor, proposeArtifacts, renderProposal, sliceSlug } from "./intake.ts";
+import { phaseFor, proposeArtifacts, renderProposal, sliceSlug, uniqueSlice } from "./intake.ts";
 
 const Parameters = Type.Object({
   request: Type.String({ description: "What the user asked for, in their words." }),
@@ -28,6 +28,13 @@ const sizeChoices = (proposed: Sizing): string[] => [
   ...SIZES.filter((s) => s !== proposed),
 ];
 
+const slicesInUse = (state: DevsysState): Set<string> =>
+  new Set([
+    ...(state.activeSlice === undefined ? [] : [state.activeSlice]),
+    ...(state.reviews ?? []).map((r) => r.slice),
+    ...state.openDepartures.flatMap((d) => (d.scope.kind === "slice" ? [d.scope.slice] : [])),
+  ]);
+
 /** `devsys_intake`: Jev proposes a size and artifact set; the user confirms; state moves to the first phase. */
 export function createIntakeTool(deps: {
   state: SessionState;
@@ -65,7 +72,7 @@ export function createIntakeTool(deps: {
       if (picked === undefined) return reply(`${proposal}\nIntake cancelled; nothing changed.`);
       const sizing = parseSizing(picked);
       if (isParseError(sizing)) return reply(sizing.message, true);
-      const slice = sliceSlug(request) as SliceRef;
+      const slice = uniqueSlice(sliceSlug(request), slicesInUse(deps.state.get())) as SliceRef;
       deps.state.update((s) => ({
         ...s,
         phase: phaseFor(sizing),

package/src/planning/intake.ts

@@ -5,6 +5,13 @@ const SLUG_MAX = 40;
 /** Jev need at or above this offers an artifact the sizing table did not list. */
 const CONSIDER_AT = 0.5;
 
+/** `base`, or `base-2`, `base-3`… when earlier work already used the name, so a new slice never inherits old review or departure state. */
+export const uniqueSlice = (base: string, taken: ReadonlySet<string>): string => {
+  let slice = base;
+  for (let n = 2; taken.has(slice); n++) slice = `${base}-${n}`;
+  return slice;
+};
+
 export const sliceSlug = (request: string): string => {
   const slug = request
     .toLowerCase()
@@ -20,14 +27,26 @@ export type ArtifactProposal = {
   readonly consider: readonly ArtifactId[];
 };
 
+/** Light and full forms of one artifact; offering several of a family at once is noise. */
+const FAMILIES: readonly (readonly ArtifactId[])[] = [
+  ["brief-lite", "brief", "decision-register"],
+  ["lens-review-optional", "lens-review"],
+];
+
+const familyOf = (id: ArtifactId): readonly ArtifactId[] =>
+  FAMILIES.find((f) => f.includes(id)) ?? [id];
+
 export const proposeArtifacts = (
   sizing: Sizing,
   artifactNeed: Readonly<Partial<Record<ArtifactId, number>>>,
 ): ArtifactProposal => {
   const recommended = recommendedArtifacts(sizing);
-  const consider = ARTIFACTS.filter(
-    (id) => !recommended.includes(id) && (artifactNeed[id] ?? 0) >= CONSIDER_AT,
-  );
+  const consider = ARTIFACTS.filter((id) => {
+    const family = familyOf(id);
+    if (family.some((member) => recommended.includes(member))) return false;
+    const first = family.find((member) => (artifactNeed[member] ?? 0) >= CONSIDER_AT);
+    return first === id;
+  });
   return { recommended, consider };
 };
 

package/src/planning/task-check-tool.ts

@@ -11,6 +11,11 @@ const Parameters = Type.Object({
   path: Type.String({
     description: "Path to the task record markdown file, inside the repository.",
   }),
+  id: Type.Optional(
+    Type.String({
+      description: "Which task record to check when the file (such as a plan) holds several.",
+    }),
+  ),
 });
 
 const reply = (text: string, isError = false) => ({
@@ -50,7 +55,7 @@ export function createTaskCheckTool(deps: {
           true,
         );
       }
-      const record = parseTaskRecord(markdown);
+      const record = parseTaskRecord(markdown, params.id);
       if (isParseError(record))
         return reply(`${params.path} is not ready: ${record.message}`, true);
       const judged = await judgeTaskReadiness(deps.jev(ctx), record);

package/src/planning/task-record.ts

@@ -1,4 +1,4 @@
-import { type ParseError, parseError } from "../core/types.ts";
+import { isParseError, type ParseError, parseError } from "../core/types.ts";
 
 /** Appendix C of the plan: the one-task-per-implementer format a weaker model can follow. */
 export type TaskRecord = {
@@ -27,7 +27,7 @@ const SECTIONS = [
 type Section = (typeof SECTIONS)[number];
 
 const HEADER = /^## (\S+) [—-] (.+)$/;
-const SECTION_LINE = /^\*\*([^:*]+):\*\*\s*(.*)$/;
+const SECTION_LINE = /^\*\*([^:*]+)(?::\*\*|\*\*:)\s*(.*)$/;
 const STEP = /^\s*(?:\d+[.)]|[-*])\s+(.*)$/;
 const STEPS_MIN = 3;
 const STEPS_MAX = 7;
@@ -36,19 +36,43 @@ const PLACEHOLDER = /^(?:n\/?a|none|todo|tbc|-|…|\.\.\.|works?|it works|passes
 
 const isSection = (name: string): name is Section => SECTIONS.some((s) => s === name);
 
+type Sections = { readonly text: Map<Section, string>; readonly duplicates: Section[] };
+
 /** Splits the body into section texts keyed by name; text may continue over several lines. */
-function splitSections(lines: readonly string[]): Map<Section, string> {
+function splitSections(lines: readonly string[]): Sections {
   const found = new Map<Section, string[]>();
+  const duplicates: Section[] = [];
   let current: string[] | undefined;
   for (const line of lines) {
     const match = SECTION_LINE.exec(line);
     const name = match?.[1]?.trim();
     if (match !== null && name !== undefined && isSection(name)) {
+      if (found.has(name)) duplicates.push(name);
       current = match[2] === "" ? [] : [match[2] ?? ""];
       found.set(name, current);
     } else current?.push(line);
   }
-  return new Map([...found].map(([name, text]) => [name, text.join("\n").trim()]));
+  const text = new Map([...found].map(([name, body]) => [name, body.join("\n").trim()] as const));
+  return { text, duplicates };
+}
+
+type Located = { readonly id: string; readonly title: string; readonly lines: readonly string[] };
+
+/** Every `## <id> — <title>` block; any other `## ` heading ends the block before it. */
+function recordsIn(lines: readonly string[]): Located[] {
+  const records: { id: string; title: string; lines: string[] }[] = [];
+  let open: { id: string; title: string; lines: string[] } | undefined;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      const header = HEADER.exec(line);
+      open =
+        header === null
+          ? undefined
+          : { id: header[1] ?? "", title: header[2]?.trim() ?? "", lines: [] };
+      if (open !== undefined) records.push(open);
+    } else open?.lines.push(line);
+  }
+  return records;
 }
 
 const stripTicks = (text: string): string => text.replace(/^`+|`+$/g, "").trim();
@@ -72,8 +96,12 @@ function concrete(name: "Run" | "Expected", text: string): string | undefined {
 const get = (sections: ReadonlyMap<Section, string>, s: Section): string => sections.get(s) ?? "";
 
 /** Every readiness problem in the sections, so the author fixes them in one pass. */
-function problemsOf(markdown: string, sections: ReadonlyMap<Section, string>): string[] {
+function problemsOf(markdown: string, split: Sections): string[] {
+  const sections = split.text;
   const problems: string[] = [];
+  if (split.duplicates.length > 0) {
+    problems.push(`duplicate section: ${[...new Set(split.duplicates)].join(", ")}`);
+  }
   const missing = SECTIONS.filter((s) => get(sections, s) === "");
   if (missing.length > 0) problems.push(`missing section: ${missing.join(", ")}`);
   if (/\bTBD\b/.test(markdown)) problems.push("contains TBD; decide it or split the task");
@@ -94,21 +122,35 @@ const filesOf = (text: string): string[] =>
     .map((f) => stripTicks(f.trim()))
     .filter((f) => f !== "");
 
-/** Parses one task record, reporting every problem together. */
-export function parseTaskRecord(markdown: string): TaskRecord | ParseError {
-  const lines = markdown.split("\n");
-  const headerAt = lines.findIndex((l) => l.startsWith("## "));
-  const header = headerAt < 0 ? null : HEADER.exec(lines[headerAt] ?? "");
-  if (header === null) {
-    return parseError("header must be `## <id> — <title>` (an id, an em dash, then the title)");
+const NO_HEADER = "header must be `## <id> — <title>` (an id, an em dash, then the title)";
+
+function locate(markdown: string, id: string | undefined): Located | ParseError {
+  const records = recordsIn(markdown.split("\n"));
+  const names = records.map((r) => r.id).join(", ");
+  if (id !== undefined) {
+    return (
+      records.find((r) => r.id === id) ??
+      parseError(`no task record "${id}" (found: ${names || "none"})`)
+    );
   }
-  const sections = splitSections(lines.slice(headerAt + 1));
-  const problems = problemsOf(markdown, sections);
+  const [only, ...rest] = records;
+  if (only === undefined) return parseError(NO_HEADER);
+  return rest.length === 0
+    ? only
+    : parseError(`the file holds ${records.length} task records (${names}); name the one to check`);
+}
+
+/** Parses one task record (the only one in the file, or the one named by `id`), reporting every problem together. */
+export function parseTaskRecord(markdown: string, id?: string): TaskRecord | ParseError {
+  const found = locate(markdown, id);
+  if (isParseError(found)) return found;
+  const split = splitSections(found.lines);
+  const problems = problemsOf(found.lines.join("\n"), split);
   if (problems.length > 0) return parseError(problems.join("; "));
-  const text = (s: Section): string => get(sections, s);
+  const text = (s: Section): string => get(split.text, s);
   return {
-    id: header[1] ?? "",
-    title: header[2]?.trim() ?? "",
+    id: found.id,
+    title: found.title,
     goal: text("Goal"),
     files: filesOf(text("Files")),
     interfaces: text("Interfaces"),

package/src/tracker/github.ts

@@ -131,37 +131,61 @@ const createIssue = async (gh: Gh, input: NewWorkItem): Promise<TrackerResult<Wo
   return view(gh, number);
 };
 
-const applyStatus = async (
-  gh: Gh,
-  id: string,
-  status: WorkStatus,
-): Promise<TrackerResult<string>> => {
-  if (status === "done") return gh(["issue", "close", id]);
-  // Reopening an issue that is already open fails; only the label change below decides the result.
-  await gh(["issue", "reopen", id]);
-  const flag = status === "in-progress" ? "--add-label" : "--remove-label";
-  return gh(["issue", "edit", id, flag, IN_PROGRESS]);
+/** Label changes that make the issue's labels exactly `wanted` (plus the in-progress marker when asked for). */
+const labelFlags = (current: WorkItem, patch: WorkItemPatch): string[] => {
+  const wanted = patch.labels ?? current.labels;
+  const marked = (patch.status ?? current.status) === "in-progress";
+  const add = [
+    ...wanted.filter((l) => !current.labels.includes(l)),
+    ...(marked ? [IN_PROGRESS] : []),
+  ];
+  const remove = [
+    ...current.labels.filter((l) => !wanted.includes(l)),
+    ...(marked ? [] : [IN_PROGRESS]),
+  ];
+  return [
+    ...add.flatMap((l) => ["--add-label", l]),
+    ...remove.flatMap((l) => ["--remove-label", l]),
+  ];
 };
 
-const editArgs = (patch: WorkItemPatch): string[] => [
+const editFlags = (current: WorkItem, patch: WorkItemPatch): string[] => [
   ...(patch.title === undefined ? [] : ["--title", patch.title]),
   ...(patch.body === undefined ? [] : ["--body", patch.body]),
-  ...(patch.labels ?? []).flatMap((label) => ["--add-label", label]),
+  ...(patch.labels === undefined && patch.status === undefined ? [] : labelFlags(current, patch)),
 ];
 
+/** Closing or reopening only when the issue is not already in the wanted state. */
+const stateCommand = (current: WorkItem, status: WorkStatus | undefined): string | undefined => {
+  if (status === undefined) return undefined;
+  if (status === "done") return current.status === "done" ? undefined : "close";
+  return current.status === "done" ? "reopen" : undefined;
+};
+
+/**
+ * Labels are replaced, as in the repo-files tracker. Order: make sure the marker label exists, apply every
+ * edit in one `gh issue edit`, then close or reopen last, so a failure before the state change leaves the
+ * issue's open/closed state alone.
+ */
 const updateIssue = async (
   gh: Gh,
   id: string,
   patch: WorkItemPatch,
 ): Promise<TrackerResult<WorkItem>> => {
-  if (!ISSUE_NUMBER.test(id)) return notNumber(id);
-  const edits = editArgs(patch);
-  if (edits.length > 0) {
-    const edited = await gh(["issue", "edit", id, ...edits]);
+  const current = await view(gh, id);
+  if (!current.ok) return current;
+  if (patch.status === "in-progress") {
+    const made = await gh(["label", "create", IN_PROGRESS, "--force"]);
+    if (!made.ok) return made;
+  }
+  const flags = editFlags(current.value, patch);
+  if (flags.length > 0) {
+    const edited = await gh(["issue", "edit", id, ...flags]);
     if (!edited.ok) return edited;
   }
-  if (patch.status !== undefined) {
-    const changed = await applyStatus(gh, id, patch.status);
+  const command = stateCommand(current.value, patch.status);
+  if (command !== undefined) {
+    const changed = await gh(["issue", command, id]);
     if (!changed.ok) return changed;
   }
   return view(gh, id);

package/src/tracker/item-format.ts

@@ -9,8 +9,31 @@ import {
 
 const COMMENTS = "\n## Comments\n";
 
+/** Comment lines are quoted so nothing a comment says can look like one of our headings. */
+const quote = (text: string): string =>
+  text
+    .split("\n")
+    .map((line) => (line === "" ? ">" : `> ${line}`))
+    .join("\n");
+
+const unquote = (text: string): string =>
+  text
+    .split("\n")
+    .map((line) => line.replace(/^> ?/, ""))
+    .join("\n");
+
+/** What the file format cannot hold, or undefined when the item can be written and read back. */
+export const unwritable = (item: Pick<WorkItem, "title" | "labels">): string | undefined => {
+  if (/[\r\n]/.test(item.title)) return "a work item title must be a single line";
+  if (item.title.trim() === "") return "a work item title cannot be blank";
+  const bad = item.labels.find((l) => /[\r\n,]/.test(l) || l.trim() === "");
+  return bad === undefined
+    ? undefined
+    : `label ${JSON.stringify(bad)} is blank or holds a comma or line break`;
+};
+
 export const renderItem = (item: WorkItem): string => {
-  const comments = item.comments.map((c) => `\n### Comment\n\n${c}\n`).join("");
+  const comments = item.comments.map((c) => `\n### Comment\n\n${quote(c)}\n`).join("");
   return [
     `# ${item.title}`,
     "",
@@ -29,7 +52,7 @@ const commentsOf = (section: string): string[] =>
   section
     .split(/^### Comment\n\n/m)
     .slice(1)
-    .map((c) => c.replace(/\n$/, "").replace(/\n$/, ""));
+    .map((c) => unquote(c.replace(/\n+$/, "")));
 
 export const parseItem = (id: string, text: string): TrackerResult<WorkItem> => {
   const marker = text.lastIndexOf(COMMENTS);

package/src/tracker/repo-files.ts

@@ -1,7 +1,7 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { ok } from "../core/result.ts";
-import { parseItem, renderBacklog, renderItem } from "./item-format.ts";
+import { parseItem, renderBacklog, renderItem, unwritable } from "./item-format.ts";
 import {
   type ItemFilter,
   type NewWorkItem,
@@ -64,6 +64,8 @@ const readAll = async (root: string): Promise<TrackerResult<WorkItem[]>> => {
 };
 
 const save = async (root: string, item: WorkItem): Promise<TrackerResult<WorkItem>> => {
+  const problem = unwritable(item);
+  if (problem !== undefined) return trackerError(problem);
   await mkdir(itemsDir(root), { recursive: true });
   await writeFile(fileOf(root, item.id), renderItem(item));
   const items = await readAll(root);
@@ -88,6 +90,8 @@ const listItems = async (root: string, filter: ItemFilter): Promise<TrackerResul
 };
 
 const createItem = async (root: string, input: NewWorkItem): Promise<TrackerResult<WorkItem>> => {
+  const problem = unwritable({ title: input.title, labels: input.labels ?? [] });
+  if (problem !== undefined) return trackerError(problem);
   const id = await freshId(root, input.title);
   if (id === undefined) return trackerError("a work item title needs letters or digits");
   return save(root, {