@jwilger/pi-development-system 0.58.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.58.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,12 +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 =
-  /^(?:(?:todo|tbd|tbc)\b.*|n\/?a|none|-|…|\.\.\.|works?|it works|passes|ok)\.?$/i;
+  /^(?:(?: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);
 

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,10 +161,9 @@ 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 hadMarker = current.status === "in-progress";
   const add = [
     ...wanted.filter((l) => !current.labels.includes(l)),
     ...(marked && !hadMarker ? [IN_PROGRESS] : []),
@@ -150,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. */
@@ -173,19 +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") {
     // 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));