FE-705: Agent CLI capabilities and workflow documentation

[lunelson]

Summary

Adds the FE-705 agent-facing CLI capability substrate and probe harness, then reconciles the surrounding design/planning docs and ln-* skill workflow so the branch is reviewable as one implementation + methodology update.

What changed

• Added server-side agent capability primitives for JSONL lifecycle, chat readiness/read access, turn response handling, and capability registration.
• Added scripts/agent-probes/ with process-backed probe runner coverage, fixture-candidate validation, packaged smoke helpers, and model-backed LLM user policy seams.
• Consolidated the conversational workspace design docs: archived the broad intent-spec synthesis, clarified multi-chat / side-chat / changeset-ledger authority, added strategy docs, and refreshed the design index.
• Restructured memory/PLAN.md and added memory/SPEC_RESTRUCTURE.md to reduce planning conflicts and clarify the new frontier/sequencing model.
• Expanded and tightened the local skill workflow: added d3k, ln-diagnose, and ln-prototype; refined ln-build, ln-scope, ln-review, ln-sync, and planning-pr; added the pre-release change posture to AGENTS.md.
• Moved dev-workflow evolution rationale under docs/design/ln-skills/ so skill design notes are separate from executable skills and product specs.

Validation

• npm run fix passes with the existing unrelated unused-variable warnings in interview-view tests.

[lunelson]

• FE-705: Planning extensions and persistence facade cleanup #133
• FE-705: Agent CLI capabilities and workflow documentation #132 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
Documentation-only changes that adjust agent workflow guidance; low risk aside from potentially shifting team process if the updated planning vocabulary or templates are adopted incorrectly.

Overview
Adds new agent skill docs for debugging and iteration workflows (d3k command guide, plus new ln-diagnose and ln-prototype skills).

Refactors the ln-* skill guidance to standardize frontier item vs slice vocabulary, with an updated ln-plan template that introduces Context, Sequencing by stable frontier id, and Frontier Definitions, and corresponding updates across ln-scope, ln-build, ln-oracles, ln-review, ln-spec, ln-spike, ln-sync, and AGENTS.md.

Reconciles surrounding design/archive docs (e.g., PLAN_HISTORY.md additions, design-doc authority/status notes, link fixes, and an audited/trimmed DEFERRED_RECONCILIATIONS.md) and narrows planning-pr into an advisory skill that recommends (not auto-creates) separate planning PRs only when explicitly needed.

^{Reviewed by Cursor Bugbot for commit 1bcd5a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[augmentcode]

This pull request is abnormally large and would use a significant amount of tokens to review. If you still wish to review it, comment "augment review" and we will review it.

[kostandinang]

Code review

Found 2 issues:

1. Temp workspace directory leaked in runProcessBackedProbe. The finally block only calls spawned.endStdin() and never removes the mkdtempSync(...) workspace at workspaceCwd. Tests manually rmSync(result.workspaceCwd), but production callers (e.g. packaged-smoke.ts) don't — every probe run leaves a /tmp/brunch-probe-workspace-* directory behind, accumulating without bound across CI/smoke runs.

brunch/scripts/agent-probes/probe-runner.ts

Lines 182 to 207 in 1bcd5a7

	turnBudget,
	}: ProcessBackedProbeOptions): Promise<ProbeRunResult> {
	const workspaceCwd = mkdtempSync(join(tmpdir(), 'brunch-probe-workspace-'));
	const spawned = spawnProcess({ cwd: workspaceCwd, command, args, env });
	const transport = createProcessJsonlTransport(spawned);
	try {
	const result = await runScriptedProbe({
	transport,
	scenario,
	scriptedAnswers,
	responsePolicy,
	simulatedUserEvents,
	turnBudget,
	});
	result.workspaceCwd = workspaceCwd;
	if (preserveWorkspaceState) {
	result.preservedWorkspaceStatePath = copyWorkspaceState({ workspaceCwd, outputDir });
	}
	writeProbeArtifacts(outputDir, result);
	return result;
	} finally {
	spawned.endStdin();
	}
	}

2. chat.ensureReady capability is registered with authority: 'runtime_replay', but the slice "Generate agent chat readiness" in this PR changes the handler to invoke streamInterviewer (a live LLM call). runtime_replay is documented as "writes replay/status artifacts tied to an existing durable unit" — i.e. deterministic and replay-safe. An LLM call is neither. Downstream adapters or audits that key off authority to decide whether a call is safe to retry/replay will draw the wrong conclusion. Either reclassify (likely commit_truth) or document why runtime_replay still holds.

brunch/src/server/capability-registry.ts

Lines 134 to 142 in 1bcd5a7

	},
	{
	id: 'chat.ensureReady',
	authority: 'runtime_replay',
	summary: 'Ensure an explicit chat has an answerable generated frontier.',
	inputSchema: 'chat.ensureReady.input.v1',
	outputSchema: 'chat.ensureReady.output.v1',
	handler: null,
	},

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[lunelson]

augment review

[augmentcode]

🤖 Augment PR Summary

Summary: This PR adds agent-facing CLI capability substrate and probe harness for the FE-705 frontier, plus reconciles surrounding design/planning docs and ln-* skill workflows.

Code changes:

• Added server-side agent capability primitives: JSONL session protocol (agent-jsonl.ts), capability dispatcher (capabilities.ts), and expanded capability registry with executable contracts for spec/chat/turn operations
• Added scripts/agent-probes/ with process-backed probe runner, fixture-candidate validation, packaged smoke helpers, and model-backed LLM-as-user policy seams
• Updated CLI (cli.ts) to support brunch agent subcommand for JSONL stdin/stdout sessions
• Extended build/lint/test tooling to include scripts/ directory

Documentation changes:

• Added new agent skill docs: d3k, ln-diagnose, ln-prototype
• Standardized frontier-item vs slice vocabulary across all ln-* skills and planning docs
• Restructured memory/PLAN.md into conflict-resistant shape with Sequencing/Frontier Definitions sections
• Consolidated design docs: archived broad synthesis, added strategy/runtime-cluster docs, refreshed design index
• Moved dev-workflow evolution docs under docs/design/ln-skills/

Technical Notes: The JSONL capability adapter drives the real Brunch interview flow through Brunch-owned contracts; the probe runner exercises this surface only through a JSONL client, maintaining the import boundary that probe code must not import DB/product handlers directly.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 3 suggestions posted.

Comment augment review to trigger a new review at any time.

[augmentcode]

This currentPhase fallback only considers grounding vs design, but the workflow has four phases (grounding, design, requirements, criteria). If grounding is closed and the spec is in requirements or criteria, the idle-no-frontier phase will still report design. Consider reusing the existing getCurrentWorkflowPhase from src/shared/phase-close.ts or iterating workflowPhaseOrder to find the first unclosed phase.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

The temp workspace directory created by mkdtempSync is never cleaned up in runProcessBackedProbe. The finally block only calls spawned.endStdin() but never removes workspaceCwd. Tests manually rmSync the returned result.workspaceCwd, but production callers like packaged-smoke.ts do not, leaking a /tmp/brunch-probe-workspace-* directory on every probe run.

Severity: medium

Other Locations

• scripts/agent-probes/packaged-smoke.ts:36

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[augmentcode]

turn.chat_id may be null for pre-multi-chat turns (the column is nullable per the schema). When turn.chat_id is null, the condition turn.chat_id !== chat.id is always true (since null !== number), causing the guard to reject legitimate turns that belong to the spec but were created before chat association was backfilled. Consider also checking turn.specification_id === chat.specification_id as a sufficient ownership proof when chat_id is null.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}