@jwilger/pi-development-system 0.57.0 → 0.59.0

package/package.json

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

package/src/jev/questions/readiness.ts

@@ -27,6 +27,9 @@ export const READINESS_QUESTIONS = {
   steps: vague(
     "`task.steps` should be small steps a reviewer could reject independently. Are any steps large, combined ('implement and wire everything'), or out of order with the test-first step?",
   ),
+  check: vague(
+    "`task.run` should be an actual command a person can type, and `task.expected` an observable result such as a count, output or exit status. Is `run` prose or a placeholder rather than a command (for example 'run the tests'), or is `expected` a restatement of success (for example 'tests pass', 'should work') rather than something observed?",
+  ),
   tooBig: {
     type: "bool",
     instructions:
@@ -60,6 +63,8 @@ export async function judgeTaskReadiness(
         interfaces: clip(record.interfaces, 1500),
         firstFailingTest: clip(record.firstFailingTest, 600),
         steps: record.steps.slice(0, 10).map((s) => clip(s, 300)),
+        run: clip(record.run, 300),
+        expected: clip(record.expected, 300),
       },
     },
     READINESS_QUESTIONS,

package/src/planning/task-record.ts

@@ -28,11 +28,13 @@ type Section = (typeof SECTIONS)[number];
 
 const HEADER = /^## (\S+) [—-] (.+)$/;
 const SECTION_LINE = /^\*\*([^:*]+)(?::\*\*|\*\*:)\s*(.*)$/;
-const STEP = /^\s*(?:\d+[.)]|[-*])\s+(.*)$/;
+/** Top-level list items only; indented sub-items belong to the step above them. */
+const STEP = /^(?:\d+[.)]|[-*])\s+(.*)$/;
 const STEPS_MIN = 3;
 const STEPS_MAX = 7;
 /** Words that stand in for a command or an observable result. */
-const PLACEHOLDER = /^(?:n\/?a|none|todo|tbc|-|…|\.\.\.|works?|it works|passes|ok)\.?$/i;
+const PLACEHOLDER =
+  /^(?:(?:tbd|tbc)\b.*|todo\s*(?::.*)?|n\/?a|none|-|…|\.\.\.|works?|it works|passes|ok)\.?$/i;
 
 const isSection = (name: string): name is Section => SECTIONS.some((s) => s === name);
 
@@ -85,7 +87,7 @@ const stepsOf = (text: string): string[] =>
 
 function concrete(name: "Run" | "Expected", text: string): string | undefined {
   const bare = stripTicks(text);
-  if (PLACEHOLDER.test(bare))
+  if (bare === "" || PLACEHOLDER.test(bare))
     return `${name} must be a concrete ${name === "Run" ? "command" : "observable result"}, not "${bare}"`;
   if (name === "Expected" && bare.split(/\s+/).length < 2) {
     return "Expected must say what is observed (at least two words, e.g. a count, output or exit status)";
@@ -142,7 +144,7 @@ function locate(markdown: string, id: string | undefined): Located | ParseError
 
 /** 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);
+  const found = locate(markdown.replace(/\r\n?/g, "\n"), id);
   if (isParseError(found)) return found;
   const split = splitSections(found.lines);
   const problems = problemsOf(found.lines.join("\n"), split);

package/src/tracker/github.ts

@@ -1,5 +1,6 @@
 import type { Exec } from "../core/exec.ts";
 import { ok } from "../core/result.ts";
+import { unwritable } from "./item-format.ts";
 import {
   type ItemFilter,
   type NewWorkItem,
@@ -94,27 +95,55 @@ const bindGh =
     return trackerError(`gh ${args.slice(0, 2).join(" ")} failed: ${why}`);
   };
 
-const view = async (gh: Gh, id: string): Promise<TrackerResult<WorkItem>> => {
+const viewRaw = async (gh: Gh, id: string): Promise<TrackerResult<GhIssue>> => {
   if (!ISSUE_NUMBER.test(id)) return notNumber(id);
   const out = await gh(["issue", "view", id, "--json", FIELDS]);
   if (!out.ok) return out;
   const parsed = parseIssue(out.value);
-  return parsed === undefined
-    ? trackerError(`gh issue view ${id}: unexpected output`)
-    : ok(toItem(parsed));
+  return parsed === undefined ? trackerError(`gh issue view ${id}: unexpected output`) : ok(parsed);
+};
+
+const view = async (gh: Gh, id: string): Promise<TrackerResult<WorkItem>> => {
+  const raw = await viewRaw(gh, id);
+  return raw.ok ? ok(toItem(raw.value)) : raw;
+};
+
+const LIST_LIMIT = 500;
+
+/** The `gh issue list` arguments that select exactly the wanted status where gh can, so the limit bites last. */
+const listArgs = (status: WorkStatus | undefined): string[] => {
+  const state = status === undefined ? "all" : STATE_ARG[status];
+  const marker = status === "in-progress" ? ["--label", IN_PROGRESS] : [];
+  return [
+    "issue",
+    "list",
+    "--state",
+    state,
+    ...marker,
+    "--limit",
+    String(LIST_LIMIT),
+    "--json",
+    FIELDS,
+  ];
 };
 
 const listIssues = async (gh: Gh, filter: ItemFilter): Promise<TrackerResult<WorkItem[]>> => {
-  const state = filter.status === undefined ? "all" : STATE_ARG[filter.status];
-  const out = await gh(["issue", "list", "--state", state, "--limit", "200", "--json", FIELDS]);
+  const out = await gh(listArgs(filter.status));
   if (!out.ok) return out;
   const parsed = parseIssues(out.value);
   if (parsed === undefined) return trackerError("gh issue list: unexpected output");
+  if (parsed.length >= LIST_LIMIT) {
+    return trackerError(
+      `gh issue list returned ${LIST_LIMIT} issues, so the list may be cut short; ask for one status (open, in-progress or done) to narrow it`,
+    );
+  }
   const items = parsed.map(toItem);
   return ok(filter.status === undefined ? items : items.filter((i) => i.status === filter.status));
 };
 
 const createIssue = async (gh: Gh, input: NewWorkItem): Promise<TrackerResult<WorkItem>> => {
+  const problem = unwritable({ title: input.title, labels: input.labels ?? [] });
+  if (problem !== undefined) return trackerError(problem);
   const labels = (input.labels ?? []).flatMap((l) => ["--label", l]);
   const out = await gh([
     "issue",
@@ -132,16 +161,16 @@ const createIssue = async (gh: Gh, input: NewWorkItem): Promise<TrackerResult<Wo
 };
 
 /** 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 labelFlags = (current: WorkItem, hadMarker: boolean, 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] : []),
+    ...(marked && !hadMarker ? [IN_PROGRESS] : []),
   ];
   const remove = [
     ...current.labels.filter((l) => !wanted.includes(l)),
-    ...(marked ? [] : [IN_PROGRESS]),
+    ...(!marked && hadMarker ? [IN_PROGRESS] : []),
   ];
   return [
     ...add.flatMap((l) => ["--add-label", l]),
@@ -149,10 +178,12 @@ const labelFlags = (current: WorkItem, patch: WorkItemPatch): string[] => {
   ];
 };
 
-const editFlags = (current: WorkItem, patch: WorkItemPatch): string[] => [
+const editFlags = (current: WorkItem, hadMarker: boolean, patch: WorkItemPatch): string[] => [
   ...(patch.title === undefined ? [] : ["--title", patch.title]),
   ...(patch.body === undefined ? [] : ["--body", patch.body]),
-  ...(patch.labels === undefined && patch.status === undefined ? [] : labelFlags(current, patch)),
+  ...(patch.labels === undefined && patch.status === undefined
+    ? []
+    : labelFlags(current, hadMarker, patch)),
 ];
 
 /** Closing or reopening only when the issue is not already in the wanted state. */
@@ -172,18 +203,23 @@ const updateIssue = async (
   id: string,
   patch: WorkItemPatch,
 ): Promise<TrackerResult<WorkItem>> => {
-  const current = await view(gh, id);
-  if (!current.ok) return current;
+  const problem = unwritable({ title: patch.title ?? "x", labels: patch.labels ?? [] });
+  if (problem !== undefined) return trackerError(problem);
+  const raw = await viewRaw(gh, id);
+  if (!raw.ok) return raw;
+  const current = toItem(raw.value);
+  const hadMarker = (raw.value.labels ?? []).some((l) => l.name === IN_PROGRESS);
   if (patch.status === "in-progress") {
-    const made = await gh(["label", "create", IN_PROGRESS, "--force"]);
-    if (!made.ok) return made;
+    // No --force: that would recolour the team's existing label. "Already exists" is success.
+    const made = await gh(["label", "create", IN_PROGRESS]);
+    if (!(made.ok || /already exists/i.test(made.error.message))) return made;
   }
-  const flags = editFlags(current.value, patch);
+  const flags = editFlags(current, hadMarker, patch);
   if (flags.length > 0) {
     const edited = await gh(["issue", "edit", id, ...flags]);
     if (!edited.ok) return edited;
   }
-  const command = stateCommand(current.value, patch.status);
+  const command = stateCommand(current, patch.status);
   if (command !== undefined) {
     const changed = await gh(["issue", command, id]);
     if (!changed.ok) return changed;

package/src/tracker/item-format.ts

@@ -54,7 +54,8 @@ const commentsOf = (section: string): string[] =>
     .slice(1)
     .map((c) => unquote(c.replace(/\n+$/, "")));
 
-export const parseItem = (id: string, text: string): TrackerResult<WorkItem> => {
+export const parseItem = (id: string, raw: string): TrackerResult<WorkItem> => {
+  const text = raw.replace(/\r\n?/g, "\n");
   const marker = text.lastIndexOf(COMMENTS);
   const main = marker < 0 ? text : text.slice(0, marker);
   const comments = marker < 0 ? [] : commentsOf(text.slice(marker + COMMENTS.length));

package/src/tracker/repo-files.ts

@@ -46,7 +46,9 @@ const readItem = async (root: string, id: string): Promise<TrackerResult<WorkIte
 const itemIds = async (root: string): Promise<string[]> => {
   try {
     const files = await readdir(itemsDir(root));
-    return files.flatMap((f) => (f.endsWith(".md") ? [f.slice(0, -3)] : []));
+    return files.flatMap((f) =>
+      f.endsWith(".md") && ID.test(f.slice(0, -3)) ? [f.slice(0, -3)] : [],
+    );
   } catch (cause) {
     if (isMissing(cause)) return [];
     throw cause;
@@ -66,11 +68,14 @@ 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);
+  const others = await readAll(root);
+  if (!others.ok) return others;
   await mkdir(itemsDir(root), { recursive: true });
   await writeFile(fileOf(root, item.id), renderItem(item));
-  const items = await readAll(root);
-  if (!items.ok) return items;
-  await writeFile(join(root, "work", "backlog.md"), renderBacklog(items.value));
+  const items = [...others.value.filter((i) => i.id !== item.id), item].toSorted((a, b) =>
+    byCodeUnit(a.id, b.id),
+  );
+  await writeFile(join(root, "work", "backlog.md"), renderBacklog(items));
   return ok(item);
 };