gentle-pi 1.0.3 → 1.0.4

package/README.md

@@ -13,9 +13,9 @@
 
 **Turn Pi from a powerful coding agent into a controlled development harness.**
 
-`gentle-pi` installs **el Gentleman** in Pi: a senior-architect operating layer for Spec-Driven Development, focused subagents, strict TDD evidence, reviewable work units, safety guards, and project/user skill discovery.
+`gentle-pi` installs **el Gentleman** in Pi: a senior-architect operating layer for Spec-Driven Development, focused subagents, strict TDD evidence, reviewable work units, safety guards, project/user skill discovery, and bounded native review.
 
-Pi already has strong tools. `gentle-pi` adds the discipline for using them well.
+Pi already has strong tools. `gentle-pi` adds the discipline for using them well, then binds review and delivery decisions to Git-derived evidence instead of agent narration.
 
 `gentle-pi` is the Pi-native package from the [Gentle-AI ecosystem](https://github.com/Gentleman-Programming/gentle-ai), built by [Gentleman Programming](https://github.com/Gentleman-Programming): the broader open-source project for turning AI coding agents into disciplined engineering environments with SDD workflows, skills, memory integrations, model routing, and review guardrails across multiple agents.
 
@@ -57,6 +57,8 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Skill discovery registry**   | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill.          |
 | **Skill creation workflow**    | Provides the `gentle-ai-skill-creator`/`gentle-ai-skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills. |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
+| **Bounded native review**      | Freezes one candidate, dispatches only controller-selected lenses, records native authority, and reuses the same content-bound receipt at delivery gates. |
+| **Verified native runtime**    | Provisions the exact package-local Gentle AI v2.1.4 binary, verifies pinned archive/binary integrity, and rejects PATH, global, sibling, symlink, and mode fallbacks. |
 | **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
 ## Install
@@ -107,6 +109,16 @@ Typical flow:
 4. For a substantial change, ask Pi to use SDD. Natural-language requests are classified by the parent agent, not by brittle runtime regexes.
 5. Review the phase artifacts instead of trusting floating chat context.
 
+## Core workflow
+
+1. **Install and inspect.** Install `gentle-pi`, open Pi in the target repository, then run `/gentle:status` or `/gentle:doctor`.
+2. **Plan when risk justifies it.** Small work stays direct; substantial work uses SDD with Engram, OpenSpec, or both so requirements and decisions survive compaction.
+3. **Build with evidence.** One focused writer implements the approved scope. When Strict TDD is available, apply and verify preserve RED → GREEN → TRIANGULATE → REFACTOR evidence.
+4. **Review one candidate.** Native START derives and freezes the Git candidate, risk tier, selected lenses, authored-line budget, and correction allowance. Review actors assess that immutable view; they do not grant authority.
+5. **Deliver the same candidate.** FINALIZE records native authority and an approved receipt. Commit, push, PR, and release gates validate that same receipt and live Git target with zero review actors; they never silently reopen review or reset its budget.
+
+> **Trust what the system can derive, not what an agent claims.** Agents analyze the candidate. The package-local Gentle AI runtime owns scope, risk, findings, receipts, and lifecycle gates. This protects against accidental scope and identity drift, not a malicious same-user process that can replace local code or authority. See Gentle AI's [review authority threat model](https://github.com/Gentleman-Programming/gentle-ai/blob/main/docs/review-authority-threat-model.md) and [Chapter 21 — Verifiable Trust](https://the-amazing-gentleman-programming-book.vercel.app/en/book/Chapter21_Verifiable-Trust).
+
 ## How the harness decides what to do
 
 `gentle-pi` routes through the smallest safe workflow:
@@ -128,7 +140,7 @@ The goal is not ceremony. The goal is to avoid accidental chaos. Once a task sto
 | Reading 4+ files to understand a flow                                                                                       | Launch `scout`, `context-builder`, or the closest read-only mapping subagent. |
 | Touching 2+ non-trivial code files                                                                                          | Delegate one writer; do not continue inline unless delegation is unavailable. |
 | Commit, push, or PR after code changes                                                                                      | Validate the approved receipt and exact typed target with zero actors.        |
-| Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue                                                  | Stop and run a fresh audit through the relevant review lens before continuing. |
+| Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue                                                  | Stop, preserve the frozen scope, investigate separately, and validate the existing receipt; never launch a fresh review lens or reopen review as incident handling. |
 | Long monolithic session with accumulating complexity, roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits | Pause and delegate the remaining work, or stop and explain the exact blocker. |
 
 The intended balanced loop for a bounded bugfix is:
@@ -161,7 +173,7 @@ Pre-commit, pre-push, pre-PR, and release gates revalidate the recovered source,
 | Security, permissions, data exposure/loss, architecture, dependencies | `review-risk` |
 | Large PR, hot path, or >400 changed lines | Full 4R: `review-risk`, `review-resilience`, `review-readability`, `review-reliability` |
 
-If multiple rows match, run the narrow set that covers the risk. For example, shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.
+Risk selection is deterministic: documentation/comment/formatting-only changes use zero lenses; every other standard change uses exactly one dominant-risk lens; security/auth/update/payment paths, data-loss or exposure risk, shell/process integration, or more than 400 authored changed lines use the full 4R set. A standard review never accumulates multiple lenses ad hoc.
 
 ### Bounded review transactions
 
@@ -169,6 +181,8 @@ New ordinary review uses compact `gentle_review` `start -> finalize -> validate`
 
 Native contract pairing is exact: this adapter supports `gentle-ai 2.1.4` only from its package-local verified binary and rechecks that version before every native operation. Production native operations resolve an absolute package-owned path and never fall back to `PATH` or a global executable. Once v2.1.4 has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
 
+Gentle AI v2.1.4 supports `gentle-ai review start --projection staged`, and upstream `main` now documents that focused-index workflow. The current `gentle-pi` adapter intentionally submits `projection: "workspace"` and does not expose staged projection yet. Native binary capability is not automatically a Pi adapter contract; package support still requires an adapter update, parity fixtures, and bounded validation.
+
 ### FINALIZE wrapper input
 
 `gentle_review` accepts `input` as a JSON-serialized object string. For initial results, provide `review_result.lens_results[]`; each selected lens appears exactly once with `lens`, `findings`, and non-empty `evidence`. A clean lens uses `findings: []`. `final_evidence` and `final_verification_passed` are paired: provide both or neither.
@@ -558,7 +572,11 @@ Memory contract for SDD delegation:
 
 | Path                           | Purpose                                                                                                    |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `extensions/gentle-ai.ts`      | Injects identity, auto-refreshes global SDD assets, registers commands, applies model/persona config, exports/restores model routing, and enforces runtime safety. |
+| `extensions/gentle-ai.ts`      | Injects identity, orchestrates native review authority and lifecycle gates, refreshes global SDD assets, registers commands, applies model/persona config, and enforces runtime safety. |
+| `lib/native-review-cli.ts`     | Strict package-local adapter for Gentle AI START, FINALIZE, VALIDATE, SDD binding, and status contracts.     |
+| `lib/review-candidate-view.ts` | Builds immutable changed-scope actor views while preserving full-tree, path, mode, symlink, and index integrity. |
+| `lib/gentle-ai-binary.ts`      | Resolves and verifies the confined package-local Gentle AI runtime without global or PATH fallback.          |
+| `scripts/gentle-ai-installer.mjs` | Downloads, verifies, extracts, and atomically promotes the pinned native runtime for six platform targets. |
 | `extensions/startup-banner.ts` | Shows and configures the startup intro, color presets, compact runtime panel, and collaboration credit.     |
 | `extensions/sdd-init.ts`       | Registers `/sdd-init` for OpenSpec initialization.                                                         |
 | `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills and closes file watchers on shutdown.          |

package/assets/migrations/managed-assets-v0.10.7.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "packageVersion": "0.10.7",
+  "assets": {
+    "agents/sdd-apply.md": "c74cb338999537395da45577d221a4f784e3fbc0664d15758801a45ff4371177"
+  }
+}

package/lib/native-review-cli.ts

@@ -181,6 +181,10 @@ function stringValue(value: unknown): string { if (typeof value !== "string") th
 function booleanValue(value: unknown): boolean { if (typeof value !== "boolean") throw new Error("expected boolean"); return value; }
 function nonNegativeInteger(value: unknown): number { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error("expected safe non-negative integer"); return value; }
 function stringArray(value: unknown): readonly string[] { if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.length === 0)) throw new Error("expected string array"); return value; }
+function decodeSelectedLenses(value: unknown, riskLevel: string, lensesRequired: boolean): readonly string[] {
+	if (value === null && riskLevel === "low" && !lensesRequired) return [];
+	return stringArray(value);
+}
 function enumString(value: unknown, allowed: readonly string[]): string { const parsed = stringValue(value); if (!allowed.includes(parsed)) throw new Error("unsupported enum"); return parsed; }
 function parseJson(stdout: string, operation: NativeReviewOperation, mutating: boolean): Record<string, unknown> {
 	if (stdout.length === 0) throw new NativeReviewCliError(NATIVE_REVIEW_ERROR_CODE.EMPTY_OUTPUT, operation, true, mutating, "native command returned empty output");
@@ -399,9 +403,9 @@ export class NativeReviewCliV214 {
 			const lineageId = requiredString(body.lineage_id);
 			if (request.lineageId && lineageId !== request.lineageId) throw nativeError(NATIVE_REVIEW_ERROR_CODE.IDENTITY_MISMATCH, NATIVE_REVIEW_OPERATION.START, true, "native start lineage mismatch");
 			const riskLevel = requiredString(body.risk_level);
-			const selectedLenses = stringArray(body.selected_lenses);
 			const action = enumString(body.action, NATIVE_START_ACTION_VALUES) as NativeStartAction;
 			const lensesRequired = booleanValue(body.lenses_required);
+			const selectedLenses = decodeSelectedLenses(body.selected_lenses, riskLevel, lensesRequired);
 			if (
 				!(NATIVE_RISK_LEVEL as readonly string[]).includes(riskLevel) ||
 				selectedLenses.some((lens) => !(NATIVE_REVIEW_LENS as readonly string[]).includes(lens)) ||

package/lib/sdd-preflight.ts

@@ -13,6 +13,7 @@ const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
 const MANAGED_ASSETS_MANIFEST = "managed-assets.json";
 const MANAGED_ASSETS_SCHEMA_VERSION = 1;
 const LEGACY_MANAGED_ASSET_MANIFESTS = Object.freeze([
+	{ path: join(ASSETS_DIR, "migrations", "managed-assets-v0.10.7.json"), version: "0.10.7" },
 	{ path: join(ASSETS_DIR, "migrations", "managed-assets-v0.13.json"), version: "0.13.0" },
 	{ path: join(ASSETS_DIR, "migrations", "managed-assets-v0.14.json"), version: "0.14.0" },
 ]);
@@ -318,7 +319,7 @@ function copyDirectoryFiles(
 	ownershipPrefix: string,
 	force: boolean,
 	manifest: ManagedAssetsManifest,
-	legacyAssetHashes: Readonly<Record<string, readonly string[]>> | undefined,
+	legacyAssetHashes: (() => Readonly<Record<string, readonly string[]>>) | undefined,
 ): { copied: number; skipped: number } {
 	if (!existsSync(sourceDir)) return { copied: 0, skipped: 0 };
 	mkdirSync(targetDir, { recursive: true });
@@ -360,7 +361,7 @@ function copyDirectoryFiles(
 				? undefined
 				: managedAssetHash(installedContent);
 			if (managedHash === undefined) {
-				const legacyHashes = legacyAssetHashes?.[ownershipKey];
+				const legacyHashes = legacyAssetHashes?.()[ownershipKey];
 				const comparableLegacyHash = installedContent === undefined
 					? undefined
 					: managedAssetHash(
@@ -399,9 +400,12 @@ export function installSddAssets(
 ): { agents: number; chains: number; support: number; skipped: number } {
 	const agentHome = gentlePiAgentHome();
 	const manifestPath = join(agentHome, "gentle-ai", MANAGED_ASSETS_MANIFEST);
-	const legacyAssetHashes = force && !existsSync(manifestPath)
-		? readLegacyManagedAssetHashes()
-		: undefined;
+	let legacyAssetHashes: (() => Readonly<Record<string, readonly string[]>>) | undefined;
+	if (force) {
+		let cachedLegacyAssetHashes: Record<string, readonly string[]> | undefined;
+		legacyAssetHashes = () =>
+			(cachedLegacyAssetHashes ??= readLegacyManagedAssetHashes());
+	}
 	const manifest = readManagedAssetsManifest(manifestPath);
 	const agents = copyDirectoryFiles(
 		join(ASSETS_DIR, "agents"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/scripts/verify-package-files.mjs

@@ -27,6 +27,7 @@ const requiredPaths = [
   "assets/chains/sdd-full.chain.md",
   "assets/chains/sdd-plan.chain.md",
   "assets/chains/sdd-verify.chain.md",
+  "assets/migrations/managed-assets-v0.10.7.json",
   "assets/migrations/managed-assets-v0.13.json",
   "assets/migrations/managed-assets-v0.14.json",
   "assets/support/sdd-status-contract.md",

package/tests/fixtures/v0.10.7/assets/agents/sdd-apply.md

@@ -0,0 +1,132 @@
+---
+name: sdd-apply
+description: Implement SDD tasks with strict TDD evidence and review workload guard.
+tools: read, grep, glob, edit, write, bash, mem_search, mem_get_observation, mem_save, mem_update
+---
+
+You are the SDD apply executor for Gentle AI.
+
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer parent-injected `## Skills to load before work` paths; read those exact `SKILL.md` files before work. Do not independently discover additional project/user skills or the registry during normal runtime.
+
+If skill paths are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `paths-injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should pass indexed paths next time.
+
+## Memory Contract
+
+Read your own input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
+
+Inputs to read (`engram`/`both`: `mem_search("<topic-key>")` then `mem_get_observation`; `openspec`: read the file under `openspec/changes/{change}/`):
+- Tasks (required): `sdd/{change}/tasks`
+- Spec (required): `sdd/{change}/spec`
+- Design (required): `sdd/{change}/design`
+- Previous apply-progress (if it exists): `sdd/{change}/apply-progress` — read and MERGE with your new progress; do NOT overwrite.
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call `mem_save` with title and `topic_key` `"sdd/{change}/apply-progress"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- Also update the tasks artifact checkboxes via `mem_update` (`engram`/`both`) or file edit (`openspec`).
+- `openspec`: write/update the apply-progress and tasks files under `openspec/changes/{change}/`.
+- `none`: return progress inline.
+
+Never claim persistence you did not perform.
+
+## Status and Action Context Guard
+
+Before writing code, consume structured SDD status from the parent prompt. If missing, produce the same fields using this lookup order: project override `.pi/gentle-ai/support/sdd-status-contract.md`, then globally installed `~/.pi/agent/gentle-ai/support/sdd-status-contract.md`, then the embedded status contract. Do not use `assets/support/...` as a runtime path; that is only the package source path before installation.
+
+**Non-authoritative store carve-out:** when the native status JSON shows `nextRecommended: "resolve-via-engram"` (covers `artifactStore: engram`, `artifactStore: none`, and `artifactStore: both` without an `openspec/` directory), the status is non-authoritative. Do not treat `applyState`, `dependencies`, or `blockedReasons` from that status as real blockers. Resolve readiness as follows:
+- `engram` (or `both` without openspec/): search Engram for `sdd/{change}/tasks`, `sdd/{change}/spec`, and `sdd/{change}/design` using `mem_search` + `mem_get_observation`. Proceed with implementation once those artifacts are confirmed present.
+- `none`: there is no persistent backend. Return artifacts inline and ask the user to provide required inputs (tasks, spec, design) or acknowledge that no persistent artifact store is available.
+
+Stop with `blocked` before editing if:
+
+- active change selection is missing or ambiguous;
+- `applyState: blocked` **and the status is authoritative** (openspec or both store);
+- required apply artifacts are missing (confirmed by artifact store);
+- `actionContext.mode: workspace-planning` and no `allowedEditRoots` are provided;
+- any target file is outside the authoritative workspace or allowed edit roots.
+
+If status says `applyState: all_done`, do not edit. Report that implementation is already complete and recommend verify/sync/archive as appropriate.
+
+## Before Writing Code
+
+Read structured status, proposal, specs, design, tasks, existing code, tests, `apply-progress.md` if present, and `openspec/config.yaml` when present.
+
+## Review Workload Gate
+
+Before implementing, inspect `tasks.md` for `Review Workload Forecast` and these guard lines:
+
+```text
+Decision needed before apply: Yes|No
+Chained PRs recommended: Yes|No
+Chain strategy: stacked-to-main|feature-branch-chain|size-exception|pending
+400-line budget risk: Low|Medium|High
+```
+
+If any of these are true:
+
+- `Decision needed before apply: Yes`
+- `Chained PRs recommended: Yes`
+- `400-line budget risk: High`
+
+then continue only when the parent prompt gives a resolved delivery path:
+
+- `auto-chain` or chosen chained/stacked PR mode: implement only the assigned work-unit slice and report the PR boundary.
+- `exception-ok` or `size:exception`: continue only if the prompt explicitly says the maintainer accepts the exception.
+- `single-pr` above budget: continue only after explicit `size:exception` approval.
+
+If no delivery decision is provided, STOP before writing code and return `blocked` with the exact decision needed.
+
+## Strict TDD Gate
+
+If `openspec/config.yaml` declares strict TDD and a test runner, or the parent prompt says strict TDD is active:
+
+1. Read the global Gentle AI strict-TDD support guidance when available. If a project-local `.pi/gentle-ai/support/strict-tdd.md` exists, treat it as an override.
+2. Follow RED → GREEN → TRIANGULATE → REFACTOR for every assigned task.
+3. Do not write production code before a failing test or equivalent RED test is written.
+4. Run relevant focused tests during GREEN and after refactors.
+5. Write a `TDD Cycle Evidence` table in `apply-progress.md`.
+
+If strict TDD is active and no external support file is available, follow the RED/GREEN/TRIANGULATE/REFACTOR contract from this prompt. Do not silently fall back to standard mode.
+
+## Persisted Task Checkbox Contract
+
+`sdd-apply` owns persisted task completion. In all modes, including strict TDD, mark each completed implementation task in the persisted tasks artifact immediately after completion:
+
+- `openspec` / `both`: update `openspec/changes/{change}/tasks.md` from `- [ ]` to `- [x]` for completed tasks.
+- `engram`: update the `sdd/{change}/tasks` observation when memory tools are explicitly available.
+- `none`: report task progress inline and state that no persisted task artifact was updated.
+
+Internal todos and `apply-progress.md` are not enough completion evidence.
+
+Before returning, re-read the persisted tasks artifact and confirm every task you report as completed is visibly marked `- [x]`. If the artifact still shows a completed task as `- [ ]`, fix the checkbox before returning or return `blocked` explaining why it cannot be reconciled. Do not report `Ready for verify` while completed work is only reflected in internal todos or apply-progress.
+
+## Standard Mode
+
+If strict TDD is not active, implement assigned tasks against specs and design, update persisted task checkboxes as work completes, and record verification evidence.
+
+## Apply Progress
+
+Update `openspec/changes/{change}/apply-progress.md` cumulatively. If previous progress exists, merge it with new progress; never overwrite completed work.
+
+Include:
+
+- completed tasks and the matching persisted task checkbox updates;
+- files changed;
+- test commands run;
+- TDD evidence when strict TDD is active;
+- deviations from design;
+- remaining tasks, including exact unchecked `- [ ]` lines when any remain;
+- workload / PR boundary;
+- structured status consumed or produced, including `actionContext` warnings.
+
+Do NOT launch child subagents. Parent/orchestrator owns delegation. Never commit unless the user explicitly asks.
+
+Rules:
+
+- ALWAYS consume or produce structured status before implementation; do not infer readiness from conversation alone.
+- STOP on unsafe `actionContext` or edit roots.
+- Mark completed tasks in the persisted tasks artifact as you go, not only at the end.
+- Before returning, re-read the persisted tasks artifact and ensure completed tasks are visibly marked `- [x]`; internal todos are not completion evidence.
+
+Return the standard phase envelope with status, executive_summary, artifacts, next_recommended, risks, and skill_resolution.

package/tests/native-review-cli.test.ts

@@ -72,6 +72,28 @@ test("native client re-verifies the pinned version before every operation and us
 	assert.equal(queue.calls.every((call) => call.cwd === "/repo with spaces"), true);
 });
 
+test("native START normalizes null selected lenses only for low-risk no-lens responses", async () => {
+	const start = JSON.parse(START.stdout) as Record<string, unknown>;
+	const valid = queuedAdapter([VERSION, {
+		stdout: JSON.stringify({
+			...start,
+			risk_level: "low",
+			selected_lenses: null,
+			lenses_required: false,
+		}),
+	}]);
+	assert.deepEqual((await new NativeReviewCliV213(valid.adapter).start({ cwd: "/repo" })).selectedLenses, []);
+
+	for (const scenario of [
+		{ risk_level: "low", lenses_required: true },
+		{ risk_level: "medium", lenses_required: false },
+		{ risk_level: "high", lenses_required: false },
+	]) {
+		const queue = queuedAdapter([VERSION, { stdout: JSON.stringify({ ...start, ...scenario, selected_lenses: null }) }]);
+		await assert.rejects(() => new NativeReviewCliV213(queue.adapter).start({ cwd: "/repo" }), NativeReviewCliError);
+	}
+});
+
 test("native START action/lenses_required matrix accepts only authoritative dispatch combinations", async () => {
 	const start = JSON.parse(START.stdout) as Record<string, unknown>;
 	const valid = [

package/tests/package-manifest.test.ts

@@ -1015,9 +1015,9 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("v1.0.3 release package and runtime stop before delivery or publication", () => {
+test("v1.0.4 release package and runtime stop before delivery or publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "1.0.3", "the release manifest must remain explicitly pinned to v1.0.3");
+	assert.equal(packageJson.version, "1.0.4", "the release manifest must remain explicitly pinned to v1.0.4");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run test:harness",

package/tests/sdd-preflight.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
 import {
 	existsSync,
 	mkdtempSync,
@@ -120,6 +121,83 @@ test("writeSddPreflightToDisk is non-fatal when directory is not writable (no th
 	});
 });
 
+test("forced asset refresh migrates the exact v0.10.7 malformed sdd-apply asset and preserves user edits", () => {
+	const packageRoot = join(import.meta.dirname, "..");
+	const legacySource = readFileSync(
+		join(
+			packageRoot,
+			"tests",
+			"fixtures",
+			"v0.10.7",
+			"assets",
+			"agents",
+			"sdd-apply.md",
+		),
+		"utf8",
+	);
+	const currentSource = readFileSync(
+		join(packageRoot, "assets", "agents", "sdd-apply.md"),
+		"utf8",
+	);
+	const temporaryAgentHome = mkdtempSync(join(tmpdir(), "gentle-pi-v0107-preflight-"));
+	const temporaryUserAgentHome = mkdtempSync(join(tmpdir(), "gentle-pi-v0107-user-preflight-"));
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const installed = join(temporaryAgentHome, "agents", "sdd-apply.md");
+	const userInstalled = join(temporaryUserAgentHome, "agents", "sdd-apply.md");
+	const userEdited = legacySource.replace(
+		"You are the SDD apply executor for Gentle AI.",
+		"You are the user-customized SDD apply executor for Gentle AI.",
+	);
+	try {
+		process.env.GENTLE_PI_AGENT_HOME = temporaryAgentHome;
+		mkdirSync(join(temporaryAgentHome, "agents"), { recursive: true });
+		writeFileSync(installed, legacySource);
+		mkdirSync(join(temporaryAgentHome, "gentle-ai"), { recursive: true });
+		writeFileSync(
+			join(temporaryAgentHome, "gentle-ai", "managed-assets.json"),
+			JSON.stringify({ schemaVersion: 1, assets: {} }),
+		);
+
+		installSddAssets(packageRoot, true);
+
+		assert.equal(readFileSync(installed, "utf8"), currentSource);
+		assert.match(readFileSync(installed, "utf8"), /^tools:\n  - read$/m);
+		const managedAssets = JSON.parse(
+			readFileSync(
+				join(temporaryAgentHome, "gentle-ai", "managed-assets.json"),
+				"utf8",
+			),
+		) as { assets: Record<string, string> };
+		assert.equal(
+			managedAssets.assets["agents/sdd-apply.md"],
+			createHash("sha256").update(currentSource).digest("hex"),
+			"the migrated asset must record current package ownership",
+		);
+
+		installSddAssets(packageRoot, true);
+		assert.equal(
+			readFileSync(installed, "utf8"),
+			currentSource,
+			"a current package-managed asset must remain refreshable",
+		);
+
+		process.env.GENTLE_PI_AGENT_HOME = temporaryUserAgentHome;
+		mkdirSync(join(temporaryUserAgentHome, "agents"), { recursive: true });
+		writeFileSync(userInstalled, userEdited);
+		installSddAssets(packageRoot, true);
+		assert.equal(
+			readFileSync(userInstalled, "utf8"),
+			userEdited,
+			"a user-edited variant of the malformed legacy asset must remain untouched",
+		);
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		rmSync(temporaryAgentHome, { recursive: true, force: true });
+		rmSync(temporaryUserAgentHome, { recursive: true, force: true });
+	}
+});
+
 test("forced asset refresh migrates only untouched v0.14 package contracts and preserves user edits", () => {
 	const packageRoot = join(import.meta.dirname, "..");
 	const fixture = readFileSync(