drive: cloud run ecf55208

ops/NEXT.md

@@ -1,49 +1,44 @@
-# NEXT — Gate 3: Build the work package consumer
+# NEXT — Gate 3: Harden backlog picker against malformed entries
 
-**Scope:** Gate 3 — close the Garden's loop. CODE task, SDK-side. The picker EMITS a work package (sdk/src/backlog-picker.ts + testdata/backlog-picker.flow.yaml, merged, four tested properties) and NOTHING consumes it — that is the missing half. Build the consumer: an SDK entrypoint taking an emitted package and turning it into something runnable, validating it has a title, a non-empty scope and a definition of done, and REFUSING with a typed reason when it does not, because a package that cannot be verified must not become work. NOTE: two previous attempts (ee5c9b3e, 06c0d6ab) did this correctly and their files were LOST before delivery by a platform fault — the build sandbox's .git points at a directory that does not exist, so writes cannot be captured. You are not duplicating live work.
+**Pinned to gate 3** per ops/TARGET.md.
 
 ## Objective
 
-Build the SDK entrypoint that takes an emitted work package and turns it into something runnable. The consumer must validate that the package has:
-- A title (non-empty string)
-- A non-empty scope
-- A definition of done
+The picker reads ops/BACKLOG.md and selects the first bold top-level bullet. Currently it handles well-formed entries but a malformed entry — a bold title with no body, an unterminated backtick, a bullet nested under another — can crash or produce a half-formed package. Add handling so malformed entries produce typed refusals, never crashes and never half-formed packages.
 
-When any of these is missing or invalid, the consumer REFUSES with a typed reason. A package that cannot be verified must not become work.
+## Scope from ops/TARGET.md
+
+> The picker reads whatever ops/BACKLOG.md contains. A malformed entry — a
+> bold title with no body, an unterminated backtick, a bullet nested under
+> another — should produce a typed refusal, never a crash and never a
+> half-formed package. Add the handling and the tests.
+
+Note: The consumer's file existence check (option b) is ALREADY implemented in sdk/src/work-package-consumer.ts:52-55 with the 'nonexistent_files' refusal reason. This work package implements option (a).
 
 ## Files in scope
 
-- `sdk/src/` (new consumer code)
-- `sdk/tests/` (new consumer tests)
-- NO changes to `kernel/` (PR #19 is open)
-- NO changes to `sdk/src/demo-hn-monitor.ts` (PR #19 is open)
+- sdk/src/backlog-picker.ts — add validation and typed refusal reasons
+- sdk/tests/backlog-picker-flow.test.ts — tests for malformed entry handling
+- sdk/src/index.ts — export new refusal types if needed
 
 ## Definition of done
 
-1. **SDK code exists** that consumes an emitted work package
-2. **Validation tests exist** for:
-   - Missing title → typed refusal
-   - Empty title → typed refusal
-   - Missing scope → typed refusal
-   - Empty scope → typed refusal
-   - Missing definition of done → typed refusal
-   - Empty definition of done → typed refusal
-   - Valid package → accepted
-3. **Every new test is confirmed to FAIL against current code** with literal output pasted
-4. **SDK test suite passes:**
+1. Code added to sdk/src/backlog-picker.ts that validates entries and returns typed refusal reasons
+2. Tests covering malformed cases: bold title with no body, unterminated backtick, nested bullet
+3. Tests covering existing behavior still passing
+4. Command passes:
    ```
-   cd sdk && npm test
+   cd /project/workflows/runs/fec0723e-4bcb-4512-a599-fc61e110dfa6/sdk && npm test
    ```
-   Paste the literal output showing all tests pass, 0 failed
-5. **Final verification** — as the LAST action, run:
+5. EVERY new test confirmed to FAIL against current code with literal failing output quoted in summary
+6. As LAST action, run and paste output:
    ```
    git status --porcelain
    ```
-   And paste the output to make lost writes visible immediately
 
-## Out of scope
+## Explicitly OUT of scope
 
-- Kernel changes (different PR)
-- Integration with hn-monitor (different PR)
-- Any changes to the backlog picker itself (already merged in PRs #20, #21, #22)
-- Changes to flow execution or scheduling
+- kernel/ changes
+- sdk/src/demo-hn-monitor.ts
+- anything under ops/
+- the consumer's file existence check (already implemented in work-package-consumer.ts:52-55)

sdk/src/backlog-picker.ts

@@ -13,22 +13,57 @@
  * reason about what the system decided or why.
  */
 
-/** First bold top-level bullet: `- **Title** rest`. */
-const ENTRY = /^- \*\*(.+?)\*\*\s*(.*(?:\n  .*)*)/m;
+/** Bold bullet candidate: `- **Title** rest`, with indentation retained. */
+const ENTRY_LINE = /^(\s*)- \*\*(.+?)\*\*\s*(.*)$/;
 
 export interface BacklogEntry {
   title: string;
   body: string;
 }
 
+export type BacklogPickerRefusalReason =
+  | 'missing_body'
+  | 'unterminated_backtick'
+  | 'nested_bullet';
+
+export type BacklogPickerResult =
+  | { ok: true; entry: BacklogEntry }
+  | { ok: false; reason: BacklogPickerRefusalReason }
+  | null;
+
+/** Select and validate the first bold bullet candidate. */
+export function pickBacklogEntry(markdown: string): BacklogPickerResult {
+  const lines = markdown.split(/\r?\n/);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = ENTRY_LINE.exec(lines[index] ?? '');
+    if (!match) continue;
+    if (match[1]) return { ok: false, reason: 'nested_bullet' };
+
+    const bodyLines = [match[3] ?? ''];
+    while (/^  \S/.test(lines[index + 1] ?? '')) {
+      index += 1;
+      bodyLines.push((lines[index] ?? '').slice(2));
+    }
+
+    const entry = { title: match[2] ?? '', body: bodyLines.join('\n').trim() };
+    if (!entry.body) return { ok: false, reason: 'missing_body' };
+    if ((`${entry.title} ${entry.body}`.match(/`/g)?.length ?? 0) % 2 !== 0) {
+      return { ok: false, reason: 'unterminated_backtick' };
+    }
+    return { ok: true, entry };
+  }
+
+  return null;
+}
+
 /**
  * Returns the selected entry, or null when the backlog holds no actionable
  * one. Null is a real answer — "nothing to do" — not a failure.
  */
 export function selectBacklogEntry(markdown: string): BacklogEntry | null {
-  const match = ENTRY.exec(markdown);
-  if (!match) return null;
-  return { title: match[1] ?? '', body: (match[2] ?? '').trim() };
+  const result = pickBacklogEntry(markdown);
+  return result?.ok ? result.entry : null;
 }
 
 /** Render the selected entry as a work package. */

sdk/src/index.ts

@@ -119,6 +119,14 @@ export {
   type WorkPackageConsumption,
   type WorkPackageRefusalReason,
 } from './work-package-consumer.js';
+export {
+  pickBacklogEntry,
+  renderWorkPackage,
+  selectBacklogEntry,
+  type BacklogEntry,
+  type BacklogPickerRefusalReason,
+  type BacklogPickerResult,
+} from './backlog-picker.js';
 
 // Hacker News adapter — deliberately outside kernel/ (see sdk/src/hn-poller.ts).
 export {

sdk/tests/backlog-picker-flow.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { load } from 'js-yaml';
 import { describe, expect, it } from 'vitest';
+import { pickBacklogEntry } from '../src/backlog-picker.js';
 
 /**
  * The backlog-picker flow's steps must agree with each other.
@@ -93,6 +94,29 @@ describe('backlog-picker flow', () => {
   });
 });
 
+describe('backlog-picker malformed entries', () => {
+  it('refuses a bold title with no body', () => {
+    expect(pickBacklogEntry('# Backlog\n\n- **Empty entry**\n')).toEqual({
+      ok: false,
+      reason: 'missing_body',
+    });
+  });
+
+  it('refuses an entry with an unterminated backtick', () => {
+    expect(pickBacklogEntry('# Backlog\n\n- **Broken command** run `npm test\n')).toEqual({
+      ok: false,
+      reason: 'unterminated_backtick',
+    });
+  });
+
+  it('refuses a bold bullet nested under another bullet', () => {
+    expect(pickBacklogEntry('# Backlog\n\n- Parent\n  - **Nested entry** must not be selected\n')).toEqual({
+      ok: false,
+      reason: 'nested_bullet',
+    });
+  });
+});
+
 describe('backlog-picker canonical spec', () => {
   it('stays in sync with the flow yaml', () => {
     // The canonical spec is what the kernel consumes. PR #22 fixed the path