ultimate-pi 0.20.0 → 0.22.0

package/.pi/lib/plan-debate-gate.ts

@@ -59,6 +59,143 @@ async function countJsonlKinds(
 	}
 }
 
+async function collectStrategyErrors(args: {
+	runDir: string;
+	coverage: any;
+	reviewStrategy: any;
+	dialogueOpts: { max_exchanges_per_round: number };
+}): Promise<string[]> {
+	const { runDir, coverage, reviewStrategy, dialogueOpts } = args;
+	const errors: string[] = [];
+	const consolidated = isConsolidatedReviewStrategy(reviewStrategy);
+	const parallelProbes = isParallelProbesReviewStrategy(reviewStrategy);
+
+	if (parallelProbes) {
+		for (const rel of laneArtifactPathsForParallelProbesRound()) {
+			if (!(await fileExists(join(runDir, rel)))) errors.push(`missing ${rel}`);
+		}
+		const messengerCheck = messengerRoundDebateReady(
+			await getMessengerRoundState(runDir, 1),
+			false,
+			dialogueOpts,
+		);
+		if (!messengerCheck.ok) {
+			for (const e of messengerCheck.errors) {
+				errors.push(`parallel_probes round messenger: ${e}`);
+			}
+		}
+		return errors;
+	}
+
+	if (consolidated) {
+		if (!(await fileExists(join(runDir, CONSOLIDATED_REVIEW_ARTIFACT)))) {
+			errors.push(`missing ${CONSOLIDATED_REVIEW_ARTIFACT}`);
+		}
+		for (const rel of laneArtifactPathsForConsolidatedRound()) {
+			if (!(await fileExists(join(runDir, rel)))) errors.push(`missing ${rel}`);
+		}
+		const messengerCheck = messengerRoundDebateReady(
+			await getMessengerRoundState(runDir, 1),
+			true,
+			dialogueOpts,
+		);
+		if (!messengerCheck.ok) {
+			for (const e of messengerCheck.errors) {
+				errors.push(`consolidated round messenger: ${e}`);
+			}
+		}
+		return errors;
+	}
+
+	const roundIndices = [
+		...new Set(
+			Object.values(coverage.rounds_by_focus).filter(
+				(v): v is number => typeof v === "number",
+			),
+		),
+	];
+	for (const r of roundIndices) {
+		const focus = coverage.focus_by_round[r] ?? null;
+		for (const rel of laneArtifactPathsForRound(r, focus)) {
+			if (!(await fileExists(join(runDir, rel)))) errors.push(`missing ${rel}`);
+		}
+		const messengerCheck = messengerRoundDebateReady(
+			await getMessengerRoundState(runDir, r),
+			focus === "quality" || r >= 4,
+			dialogueOpts,
+		);
+		if (!messengerCheck.ok) {
+			for (const e of messengerCheck.errors) {
+				errors.push(`round ${r} messenger: ${e}`);
+			}
+		}
+	}
+	return errors;
+}
+
+async function collectBusAndConsensusIssues(args: {
+	debateId: string;
+	debatesDir: string;
+	caps: ReturnType<typeof capsForDebate>;
+	requiredFocuses: readonly PlanDebateFocus[];
+	coverage: any;
+	debateProfile: string;
+}): Promise<{ errors: string[]; warnings: string[] }> {
+	const {
+		debateId,
+		debatesDir,
+		caps,
+		requiredFocuses,
+		coverage,
+		debateProfile,
+	} = args;
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const { rounds, hasConsensus } = await countJsonlKinds(
+		join(debatesDir, `${debateId}.jsonl`),
+	);
+	if (rounds < caps.min_focus_rounds) {
+		errors.push(
+			`${debateId}.jsonl has ${rounds}/${caps.min_focus_rounds} minimum round events — use harness_debate_submit_round per focus`,
+		);
+	}
+	if (!hasConsensus)
+		errors.push(
+			`missing consensus on ${debateId} — call harness_debate_consensus`,
+		);
+	if (
+		!planDebateOutcomeComplete(coverage, {
+			requiredFocuses,
+			minRoundIndex: caps.min_focus_rounds,
+		})
+	) {
+		errors.push(
+			`debate outcome incomplete: required focuses [${requiredFocuses.join(", ")}] with last review_gate_ready true (profile=${debateProfile})`,
+		);
+	}
+	const consensusPath = join(debatesDir, `${debateId}.consensus.json`);
+	if (!(await fileExists(consensusPath))) {
+		errors.push(`missing ${debateId}.consensus.json`);
+	} else {
+		try {
+			const packet = JSON.parse(await readFile(consensusPath, "utf-8")) as {
+				policy_decision?: string;
+			};
+			if (packet.policy_decision === "block") {
+				errors.push("consensus policy_decision is block — cannot approve");
+			}
+		} catch {
+			errors.push("invalid consensus json");
+		}
+	}
+	if (rounds > caps.max_rounds) {
+		warnings.push(
+			`bus round count ${rounds} exceeds soft max_rounds ${caps.max_rounds}`,
+		);
+	}
+	return { errors, warnings };
+}
+
 export interface PlanDebateGateResult {
 	ok: boolean;
 	errors: string[];
@@ -129,76 +266,14 @@ export async function validatePlanDebateGate(
 		errors.push("last submitted review round has review_gate_ready !== true");
 	}
 
-	if (parallelProbes) {
-		for (const rel of laneArtifactPathsForParallelProbesRound()) {
-			const abs = join(runDir, rel);
-			if (!(await fileExists(abs))) {
-				errors.push(`missing ${rel}`);
-			}
-		}
-		const roundState = await getMessengerRoundState(runDir, 1);
-		const messengerCheck = messengerRoundDebateReady(
-			roundState,
-			false,
+	errors.push(
+		...(await collectStrategyErrors({
+			runDir,
+			coverage,
+			reviewStrategy,
 			dialogueOpts,
-		);
-		if (!messengerCheck.ok) {
-			for (const e of messengerCheck.errors) {
-				errors.push(`parallel_probes round messenger: ${e}`);
-			}
-		}
-	} else if (consolidated) {
-		const absConsolidated = join(runDir, CONSOLIDATED_REVIEW_ARTIFACT);
-		if (!(await fileExists(absConsolidated))) {
-			errors.push(`missing ${CONSOLIDATED_REVIEW_ARTIFACT}`);
-		}
-		for (const rel of laneArtifactPathsForConsolidatedRound()) {
-			const abs = join(runDir, rel);
-			if (!(await fileExists(abs))) {
-				errors.push(`missing ${rel}`);
-			}
-		}
-		const roundState = await getMessengerRoundState(runDir, 1);
-		const messengerCheck = messengerRoundDebateReady(
-			roundState,
-			true,
-			dialogueOpts,
-		);
-		if (!messengerCheck.ok) {
-			for (const e of messengerCheck.errors) {
-				errors.push(`consolidated round messenger: ${e}`);
-			}
-		}
-	} else {
-		const roundIndices = [
-			...new Set(
-				Object.values(coverage.rounds_by_focus).filter(
-					(v): v is number => typeof v === "number",
-				),
-			),
-		];
-		for (const r of roundIndices) {
-			const focus = coverage.focus_by_round[r] ?? null;
-			for (const rel of laneArtifactPathsForRound(r, focus)) {
-				const abs = join(runDir, rel);
-				if (!(await fileExists(abs))) {
-					errors.push(`missing ${rel}`);
-				}
-			}
-			const roundState = await getMessengerRoundState(runDir, r);
-			const requireSprint = focus === "quality" || r >= 4;
-			const messengerCheck = messengerRoundDebateReady(
-				roundState,
-				requireSprint,
-				dialogueOpts,
-			);
-			if (!messengerCheck.ok) {
-				for (const e of messengerCheck.errors) {
-					errors.push(`round ${r} messenger: ${e}`);
-				}
-			}
-		}
-	}
+		})),
+	);
 
 	if (
 		isHarnessBudgetEnforceOn() &&
@@ -224,51 +299,16 @@ export async function validatePlanDebateGate(
 		errors.push(`messenger debate_id ${messenger.debate_id} !== ${debateId}`);
 	}
 
-	const jsonlPath = join(debatesDir, `${debateId}.jsonl`);
-	const { rounds, hasConsensus } = await countJsonlKinds(jsonlPath);
-	const minRounds = caps.min_focus_rounds;
-	if (rounds < minRounds) {
-		errors.push(
-			`${debateId}.jsonl has ${rounds}/${minRounds} minimum round events — use harness_debate_submit_round per focus`,
-		);
-	}
-	if (!hasConsensus) {
-		errors.push(
-			`missing consensus on ${debateId} — call harness_debate_consensus`,
-		);
-	}
-
-	if (
-		!planDebateOutcomeComplete(coverage, {
-			requiredFocuses,
-			minRoundIndex: caps.min_focus_rounds,
-		})
-	) {
-		errors.push(
-			`debate outcome incomplete: required focuses [${requiredFocuses.join(", ")}] with last review_gate_ready true (profile=${debateProfile})`,
-		);
-	}
-
-	const consensusPath = join(debatesDir, `${debateId}.consensus.json`);
-	if (!(await fileExists(consensusPath))) {
-		errors.push(`missing ${debateId}.consensus.json`);
-	} else {
-		try {
-			const raw = await readFile(consensusPath, "utf-8");
-			const packet = JSON.parse(raw) as { policy_decision?: string };
-			if (packet.policy_decision === "block") {
-				errors.push("consensus policy_decision is block — cannot approve");
-			}
-		} catch {
-			errors.push("invalid consensus json");
-		}
-	}
-
-	if (rounds > caps.max_rounds) {
-		warnings.push(
-			`bus round count ${rounds} exceeds soft max_rounds ${caps.max_rounds}`,
-		);
-	}
+	const busChecks = await collectBusAndConsensusIssues({
+		debateId,
+		debatesDir,
+		caps,
+		requiredFocuses,
+		coverage,
+		debateProfile,
+	});
+	errors.push(...busChecks.errors);
+	warnings.push(...busChecks.warnings);
 
 	return {
 		ok: errors.length === 0,

package/.pi/lib/plan-task-clarification.ts

@@ -0,0 +1,158 @@
+/**
+ * Task clarification artifact (Phase 0) — readiness, hashing, write-order guards.
+ */
+
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+export const TASK_CLARIFICATION_ARTIFACT = "artifacts/task-clarification.yaml";
+
+/** Plan artifacts blocked until task clarification is ready. */
+export const PLAN_ARTIFACTS_REQUIRING_CLARIFICATION = new Set([
+	"artifacts/planning-context.yaml",
+	"artifacts/decomposition.yaml",
+	"artifacts/hypothesis.yaml",
+	"artifacts/implementation-research.yaml",
+	"artifacts/stack.yaml",
+	"artifacts/plan-phase-status.yaml",
+	"artifacts/plan-phase-waiver.yaml",
+	"artifacts/execution-plan-draft.yaml",
+	"artifacts/sentrux-manifest-proposal.yaml",
+	"artifacts/ls-lint-manifest-proposal.yaml",
+	"research-brief.yaml",
+	"plan-packet.yaml",
+]);
+
+export function isPlanArtifactRequiringClarification(relPath: string): boolean {
+	const normalized = relPath.replace(/\\/g, "/");
+	if (PLAN_ARTIFACTS_REQUIRING_CLARIFICATION.has(normalized)) {
+		return true;
+	}
+	if (
+		/^artifacts\/review-round(-r\d+|-consolidated)?\.yaml$/i.test(normalized)
+	) {
+		return true;
+	}
+	if (
+		/^artifacts\/(adversary|evaluator|sprint-audit|validation)-.*\.yaml$/i.test(
+			normalized,
+		)
+	) {
+		return true;
+	}
+	return false;
+}
+
+export function computeTaskInputHash(input: {
+	sourceTask: string;
+	riskLevel?: string;
+	quick?: boolean;
+}): string {
+	const payload = [
+		input.sourceTask.trim(),
+		String(input.riskLevel ?? "").toLowerCase(),
+		input.quick ? "quick" : "",
+	].join("\n");
+	return createHash("sha256")
+		.update(payload, "utf8")
+		.digest("hex")
+		.slice(0, 16);
+}
+
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function readTaskClarificationDoc(
+	runDir: string,
+): Promise<Record<string, unknown> | null> {
+	const path = join(runDir, TASK_CLARIFICATION_ARTIFACT);
+	if (!(await fileExists(path))) return null;
+	try {
+		const raw = await readFile(path, "utf-8");
+		const doc = parseYaml(raw) as unknown;
+		return doc && typeof doc === "object" && !Array.isArray(doc)
+			? (doc as Record<string, unknown>)
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+export interface TaskClarificationReadiness {
+	ok: boolean;
+	errors: string[];
+}
+
+export function validateTaskClarificationDoc(
+	doc: Record<string, unknown> | null,
+	opts?: { requireReady?: boolean },
+): TaskClarificationReadiness {
+	const errors: string[] = [];
+	if (!doc) {
+		errors.push(`missing ${TASK_CLARIFICATION_ARTIFACT}`);
+		return { ok: false, errors };
+	}
+	const status = String(doc.status ?? "").toLowerCase();
+	const requireReady = opts?.requireReady !== false;
+	if (requireReady && status !== "ready") {
+		errors.push(
+			`${TASK_CLARIFICATION_ARTIFACT}: status must be ready (got "${status || "missing"}")`,
+		);
+	}
+	const clarified = String(doc.clarified_task ?? "").trim();
+	if (requireReady && clarified.length < 8) {
+		errors.push(
+			`${TASK_CLARIFICATION_ARTIFACT}: clarified_task too short or missing`,
+		);
+	}
+	const unresolved = doc.unresolved_questions;
+	if (requireReady) {
+		if (!Array.isArray(unresolved)) {
+			errors.push(
+				`${TASK_CLARIFICATION_ARTIFACT}: unresolved_questions must be an array`,
+			);
+		} else if (unresolved.length > 0) {
+			errors.push(
+				`${TASK_CLARIFICATION_ARTIFACT}: unresolved_questions must be empty before ready (${unresolved.length} remaining)`,
+			);
+		}
+	}
+	return { ok: errors.length === 0, errors };
+}
+
+export async function isTaskClarificationReady(
+	runDir: string,
+): Promise<TaskClarificationReadiness> {
+	const doc = await readTaskClarificationDoc(runDir);
+	return validateTaskClarificationDoc(doc, { requireReady: true });
+}
+
+export async function assertTaskClarificationReadyForPlanWrite(
+	runDir: string,
+	relPath: string,
+): Promise<{ ok: boolean; message?: string }> {
+	const normalized = relPath.replace(/\\/g, "/");
+	if (normalized === TASK_CLARIFICATION_ARTIFACT) {
+		return { ok: true };
+	}
+	if (!isPlanArtifactRequiringClarification(normalized)) {
+		return { ok: true };
+	}
+	const readiness = await isTaskClarificationReady(runDir);
+	if (!readiness.ok) {
+		return {
+			ok: false,
+			message: `Blocked: ${normalized} requires ${TASK_CLARIFICATION_ARTIFACT} with status ready. ${readiness.errors.join("; ")}`,
+		};
+	}
+	return { ok: true };
+}

package/.pi/prompts/harness-auto.md

@@ -20,11 +20,11 @@ If task missing:
 
 Follow **harness-plan** performance rules (`subagent` with `agentScope: "both"`). Use parallel `tasks` only for Phase 3.5 research (≤2 lanes) when subprocesses are needed. Never parallelize decompose∥hypothesis or debate lanes — precheck enforces this.
 
-1. **Plan** — follow `/harness-plan` (context → lakes/synthesis or sequential framing → research → plan-verify → `approve_plan()` + `create_plan()`). One approval.
+1. **Plan** — follow `/harness-plan` (task clarification gate → context → lakes/synthesis or sequential framing → research → plan-verify → `approve_plan()` + `create_plan()`). One approval.
 2. **Execute** — `harness/running/executor` with `executor_strategy` from packet (default `single_pass` for low/med).
 3. **Review** — always **`/harness-review`** after execute (no benchmark fail-fast).
 4. **Steer loop** — while `review-outcome.remediation_class === implementation_gap` and `steer_attempt < HARNESS_STEER_MAX_ATTEMPTS`: `/harness-steer` → `/harness-review` (tiered adversary on attempts 2+).
-5. **Parent** — apply locked strict gates; commit/PR only when `remediation_class: pass`.
+5. **Parent** — apply locked strict gates; commit/PR only when `remediation_class: pass`. For commits, invoke **harness-git-commit** skill (never raw `git commit`).
 
 Do **not** call separate `/harness-eval` or `/harness-critic` (deprecated aliases of `/harness-review`).
 

package/.pi/prompts/harness-ls-lint-steward.md

@@ -0,0 +1,43 @@
+---
+description: Ad-hoc naming convention review — spawn harness/ls-lint-steward with graphify evidence.
+argument-hint: "[--run <run-id>]"
+---
+
+# harness-ls-lint-steward
+
+You are the **chair** for ls-lint **intent** evolution (manifest → `.ls-lint.yml`). Spawn **`harness/ls-lint-steward`** only — do not edit the manifest inline without a proposal artifact.
+
+**Skill:** `harness-ls-lint-setup` — bootstrap vs steward vs sync.
+
+## When to run
+
+- Plan or run adds paths/extensions not covered by `naming.manifest.json`
+- Post-run `ls-lint` failures suggesting missing scoped rules (before replan)
+- User requests naming convention change
+
+## Spawn
+
+```
+subagent({
+  agentScope: "both",
+  agent: "harness/ls-lint-steward",
+  task: "<HarnessSpawnContext + planning-context + execution-plan-draft + ls-lint output if any>"
+})
+```
+
+Gate: `harness_artifact_ready({ paths: ["artifacts/ls-lint-manifest-proposal.yaml"] })`
+
+## Chair applies (after `human_required` cleared)
+
+Read `artifacts/ls-lint-manifest-proposal.yaml`.
+
+If `change_class` is `none`, report and stop.
+
+Otherwise:
+
+1. Apply `manifest_patch` to `.pi/harness/ls-lint/naming.manifest.json`.
+2. `node "$UP_PKG/.pi/scripts/harness-ls-lint-bootstrap.mjs" --force`
+3. Append session entry `harness-naming-changed` (triggers extension sync on `agent_end`).
+4. Optional: `node "$UP_PKG/.pi/scripts/harness-ls-lint-cli.mjs"` to confirm pass.
+
+Report `change_class`, whether manifest was updated, and ls-lint outcome if run after sync.

package/.pi/prompts/harness-plan.md

@@ -11,6 +11,8 @@ You are the **planning orchestrator** (agent-native; ADR 0042). Produce an execu
 
 Subagents persist artifacts via scoped **`submit_*`** tools (deterministic YAML under the run dir). Parent uses **`harness_artifact_ready`** to gate phases (no JSON parsing). Parent merges still use **`write_harness_yaml`** for `research-brief.yaml`, `plan-packet.yaml`, `planning-context.yaml`, and integrator patches.
 
+**Phase 0 is mandatory** before reconnaissance or any planning subagent. `write_harness_yaml` and spawn topology enforce `artifacts/task-clarification.yaml` with `status: ready` (ADR 0053).
+
 ## Allowed subagents
 
 - `harness/planning/planning-context` (optional — prefer parent tools for Phase 1)
@@ -53,22 +55,53 @@ Read **harness-debate-plan** skill before Review Gate rounds.
 
 Use `[HarnessActivePlan]` / `[HarnessRunContext]` only. On revise: preserve `plan_id` / `task_id`. Canonical paths: `plan-packet.yaml`, `research-brief.yaml`, `artifacts/*.yaml`.
 
-## Phase 0 — Tooling / fast feedback (automatic)
+## Phase 0 — Task clarification (mandatory; parent-led)
+
+**Practice:** Collect requirements / pool of shared meaning before WBS (PMBOK; Crucial Conversations). **ADR 0053.**
+
+**Goal:** `artifacts/task-clarification.yaml` with `status: ready`, `unresolved_questions: []`, and a canonical `clarified_task`. No full planning until gated.
+
+### Phase 0a — Tooling (automatic)
+
+Do **not** run `ccc index` or `ccc search --refresh`. Incremental `ccc index` runs before subagent spawns when you use subprocesses later.
+
+### Allowed during Phase 0
+
+- **Codebase:** `Read`, `sg -p`, `ccc search`, `graphify query` / `explain` / `path`, `GRAPH_REPORT.md` — to disambiguate what the user wants and what “done” means
+- **Web:** **web-retrieval** — linked specs, APIs, tickets (disambiguate the **task**, not Phase 3.5 landscape/stack commitment)
+- **`ask_user`** — harness-decisions; **one tool call per clarification round** (flat `options` or questionnaire `questions[]`, ≤8 sub-questions). Prefer questionnaire when scope, success, and risk are independent. After answers, merge via `applyAskUserToTaskClarification` — do not hand-edit structured YAML fields.
+
+Prefer minimum investigation; codebase and web are **not** forbidden.
+
+### Not allowed until `task-clarification` is `ready`
+
+- Any **`subagent`** spawn
+- `artifacts/planning-context.yaml`, `decomposition.yaml`, `hypothesis.yaml`, Phase 3.5 research artifacts, `plan-packet.yaml`, debate rounds, `approve_plan` / `create_plan`, DAG validation, Review Gate
+
+### Algorithm
 
-**Practice:** Invest in iteration speed (Pragmatic Programmer).
+1. Parse task + `--risk` / `--quick`.
+2. **`mode: revise`:** If `artifacts/task-clarification.yaml` exists with `status: ready` and `task_input_hash` matches current args (hash = source task + risk + quick flag), skip to Phase 1. If `last_outcome` is `needs_clarification`, do **not** skip.
+3. Investigate as needed; log `grounding` + `evidence_refs` on the artifact.
+4. Draft `artifacts/task-clarification.yaml` via `write_harness_yaml` (`schema_version: "1.0.0"`, fields per `plan-task-clarification.schema.json`). Set `task_input_hash` from source task + flags. List `unresolved_questions` when scope, success criteria, risk, or target surface are ambiguous.
+5. While `unresolved_questions` non-empty → `ask_user` (batch related forks in one call when possible); merge answers into `task-clarification.yaml` using the merge helper; increment `clarification_rounds`. On cancel → `plan_status: needs_clarification` and stop.
+6. When ready → `status: ready`, empty `unresolved_questions`, copy `acceptance_checks_draft`, set `risk_level` (CLI `--risk` wins when provided).
+7. Gate: `harness_artifact_ready({ paths: ["artifacts/task-clarification.yaml"] })` — updates `task_summary` to `clarified_task` when valid.
 
-Do **not** run `ccc index` or `ccc search --refresh`. The harness runs incremental `ccc index` before subagent spawns when you use subprocesses. Proceed to Phase 1.
+**`--quick`:** Same gate. At most **one** `ask_user` tool call (questionnaire allowed) when the task already states explicit acceptance; if still ambiguous after that round, set `needs_clarification` and **do not** enter Phase 1.
 
 ## Phase 1 — Reconnaissance before WBS (parent-led, default)
 
 **Practice:** Shared context before scope decomposition — use the right tools for the job (graphify → sg → ccc → read per `AGENTS.md`).
 
-**Default (no subprocess):** As parent, gather reconnaissance with tools as needed for the task:
+**Requires** Phase 0 gate. Read `artifacts/task-clarification.yaml` first; set `task_ref: artifacts/task-clarification.yaml` on planning context.
+
+**Default (no subprocess):** Extend Phase 0 grounding — do **not** repeat `evidence_refs` or re-fetch URLs unless scope changed after `ask_user`:
 
 1. Read `graphify-out/GRAPH_REPORT.md` when present; use `graphify query` / `explain` / `path` for architecture and cross-module relationships.
 2. Use `sg -p '…'` for structural surfaces (handlers, types, exports).
 3. Use `ccc search` for semantic implementation matches (unless `--quick` — set `coverage.semantic.status: skipped`).
-4. Write `artifacts/planning-context.yaml` via `write_harness_yaml` with `schema_version: "1.0.0"`, `status`, `summary`, `coverage` (architecture + structure required; semantic per risk/quick), `findings`, `evidence_refs`, `open_questions`.
+4. Write `artifacts/planning-context.yaml` via `write_harness_yaml` with `schema_version: "1.0.0"`, `status`, `summary`, `coverage` (architecture + structure required; semantic per risk/quick), `findings`, `evidence_refs`, `open_questions` (**technical** unknowns only — do not re-ask scope closed in Phase 0).
 
 **Optional subprocess:** Spawn **at most one** `harness/planning/planning-context` when the brief is large or you need context isolation.
 
@@ -79,12 +112,12 @@ Gate: `harness_artifact_ready({ paths: ["artifacts/planning-context.yaml"] })`.
 **Practice:** PMBOK scope / WBS; Berkun — how the team divides work.
 
 ```
-subagent({ agentScope: "both", agent: "harness/planning/decompose", task: "<HarnessSpawnContext + path to planning-context.yaml>" })
+subagent({ agentScope: "both", agent: "harness/planning/decompose", task: "<HarnessSpawnContext + planning-context.yaml + task-clarification.yaml (clarified_task, in_scope, out_of_scope, acceptance_checks_draft)>" })
 ```
 
 Gate: `harness_artifact_ready({ paths: ["artifacts/decomposition.yaml"] })`.
 
-Decompose **prior_art** is **internal only** (from Phase 1). External prior art arrives in Phase 3.5.
+Decompose treats **`task-clarification.yaml` as authoritative** for scope; §1.1 is **delta-only** (tensions/gaps), not a second full restatement. **prior_art** is **internal only** (from Phase 1). External prior art arrives in Phase 3.5.
 
 ## Phase 2b — Hypothesis-driven approach (sequential)
 
@@ -137,7 +170,9 @@ Build draft `PlanPacket` (`contract_version: "1.1.0"`):
 
 Initialize `research-brief.yaml` with decomposition + hypothesis + Phase 3.5 merges (`write_harness_yaml`).
 
-**`ask_user` on material `dialectical_fork`** after Phase 3.5 merge (evidence-backed — conflicting external patterns may trigger `human_required` from eligibility).
+Copy `acceptance_checks` from `task-clarification.acceptance_checks_draft` unless debate patches change them.
+
+**`ask_user` on material `dialectical_fork`** after Phase 3.5 merge (evidence-backed research fork — **not** a substitute for Phase 0 task contract).
 
 ## Phase 4b — Schedule + WBS detail
 
@@ -179,6 +214,21 @@ If `change_class` ≠ `none` and `human_required` → `ask_user` before manifest
 
 Do **not** spawn on every plan or when changes stay inside existing layer globs.
 
+### Phase 4e′ — Naming intent (optional)
+
+Spawn **`harness/ls-lint-steward`** when **any** apply (after Phase 4b, before Phase 4c):
+
+- Execution plan adds top-level paths or file types not covered by `naming.manifest.json`
+- Prior run reported `ls-lint` failures on new directories or extensions
+
+```
+subagent({ agentScope: "both", agent: "harness/ls-lint-steward", task: "<HarnessSpawnContext + planning-context + execution-plan-draft + scope paths>" })
+```
+
+Gate: `harness_artifact_ready({ paths: ["artifacts/ls-lint-manifest-proposal.yaml"] })`.
+
+If `change_class` ≠ `none` and `human_required` → `ask_user` before manifest edits. Chair applies patch, runs `harness-ls-lint-bootstrap.mjs --force`, emits `harness-naming-changed`. See `/harness-ls-lint-steward`.
+
 ## Phase 4d — Tailor process to risk
 
 **Practice:** PMBOK tailoring.