@blxzer/pactile 0.6.0-beta.2 → 0.6.0-beta.5

package/dist/commands/init.js

@@ -11,15 +11,14 @@ import { getInitToolChoices } from "../configurators/index.js";
 import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
 import { VERSION } from "../constants/version.js";
 import { setWriteMode, startRecordingWrites, stopRecordingWrites, } from "../utils/file-writer.js";
-import { applyKernelCreate, applyKernelStart, writeWaveCConfirmed, } from "../core/task/index.js";
-import { emptyTaskJson } from "../utils/task-json.js";
+import { writeWaveCConfirmed, createTaskKernel, readTaskKernel, } from "../core/task/index.js";
+import { canonicalProjectRoot } from "../core/task/task-kernel-paths.js";
 import { initializeDeveloper, readDeveloper } from "../utils/developer.js";
 import { detectProjectType, detectMonorepo, sanitizePkgName, } from "../utils/project-detector.js";
 import { initializeHashes, removeHash } from "../utils/template-hash.js";
 import { NATIVE_WORKFLOW_ID, resolveWorkflowTemplate, } from "../utils/workflow-resolver.js";
 import { isCwdHomedir, homedirGuardMessage, homedirBypassEnabled, } from "../utils/cwd-guard.js";
 import { fetchTemplateIndex, probeRegistryIndex, downloadTemplateById, downloadRegistryDirect, parseRegistrySource, TIMEOUTS, TEMPLATE_INDEX_URL, } from "../utils/template-fetcher.js";
-import { setupProxy, maskProxyUrl } from "../utils/proxy.js";
 import { reportInitReadiness, snapshotReadinessForRollout, } from "../utils/readiness.js";
 import { getProjectCapability, getProjectCapabilityChoices, loadProjectCapabilities, parseProjectCapabilities, writeProjectCapabilityFiles, } from "../utils/project-capabilities.js";
 import { collectCanonicalGenerationFiles, collectLegacyCstlLifecycleFiles, discoverCanonicalGenerationPaths, installedPactilePlatforms, materializeCanonicalGeneration, materializePreparedLegacyUserState, prepareLegacyCstlImport, readLegacyCstlVersion, runLifecycleCommand, seedCanonicalBuildRoot, } from "../pactile/lifecycle/index.js";
@@ -47,47 +46,368 @@ export function slugifyDeveloperName(name) {
     return slug || "user";
 }
 /**
- * Write a task skeleton (task.json + prd.md).
- *
- * Idempotent: if the task dir already exists, returns true without touching
- * anything. Shared by both creator bootstrap and joiner onboarding flows.
+ * Task Kernel IDs are lowercase ASCII slugs, while legacy task directory names
+ * intentionally preserve Unicode developer names. Encode non-ASCII code points
+ * so both identities remain deterministic without changing an existing path.
  */
-function writeTaskSkeleton(cwd, taskName, taskJson, prdContent) {
-    const taskDir = path.join(cwd, PATHS.TASKS, taskName);
-    if (fs.existsSync(taskDir))
-        return true; // idempotent
+function taskKernelIdForDirectoryName(taskName) {
+    let encoded = "";
+    for (const character of taskName.toLowerCase()) {
+        if (/[a-z0-9]/u.test(character) || character === "-") {
+            encoded += character;
+        }
+        else {
+            encoded += `-u${character.codePointAt(0)?.toString(16) ?? "0"}-`;
+        }
+    }
+    return encoded.replace(/-+/gu, "-").replace(/^-|-$/gu, "") || "task";
+}
+const INIT_TASK_MARKER_TEXT = "Task creation was interrupted; retry pactile init.\n";
+const INIT_JOINER_MARKER_PREFIX = `${INIT_TASK_MARKER_TEXT}joiner:v1:`;
+const MAX_INIT_JOINER_DEVELOPER_NAME_LENGTH = 256;
+const MAX_INIT_TASK_MARKER_BYTES = 2048;
+function containsInitJoinerControlCharacters(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (codePoint < 0x20 || codePoint === 0x7f)
+            return true;
+    }
+    return false;
+}
+function normalizeInitJoinerDeveloperName(value, taskName) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_INIT_JOINER_DEVELOPER_NAME_LENGTH ||
+        value.trim() !== value ||
+        value === "." ||
+        value === ".." ||
+        containsInitJoinerControlCharacters(value) ||
+        Buffer.byteLength(value, "utf8") > MAX_INIT_JOINER_DEVELOPER_NAME_LENGTH * 4 ||
+        taskName !== `00-join-${slugifyDeveloperName(value)}`) {
+        return null;
+    }
+    return value;
+}
+function initTaskMarkerContent(taskName, developerName) {
+    if (!developerName)
+        return INIT_TASK_MARKER_TEXT;
+    const normalizedName = normalizeInitJoinerDeveloperName(developerName.trim(), taskName);
+    if (!normalizedName)
+        return INIT_TASK_MARKER_TEXT;
+    return `${INIT_JOINER_MARKER_PREFIX}${JSON.stringify(normalizedName)}\n`;
+}
+function pathExists(pathname) {
+    return fs.lstatSync(pathname, { throwIfNoEntry: false }) !== undefined;
+}
+function assertSafeInitTaskPaths(cwd, extraDirectories = []) {
+    const projectRoot = canonicalProjectRoot(cwd, cwd);
+    const tasksRoot = path.resolve(projectRoot, PATHS.TASKS);
+    const tasksRelative = path.relative(projectRoot, tasksRoot);
+    if (!tasksRelative ||
+        tasksRelative === ".." ||
+        tasksRelative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(tasksRelative)) {
+        throw new Error("Init Task root must stay inside the canonical project root");
+    }
+    const pactileRoot = path.resolve(projectRoot, DIR_NAMES.WORKFLOW);
+    const checkedDirectories = [pactileRoot, tasksRoot, ...extraDirectories];
+    for (const directory of checkedDirectories) {
+        const relative = path.relative(tasksRoot, directory);
+        if (directory !== pactileRoot &&
+            directory !== tasksRoot &&
+            (!relative ||
+                relative === ".." ||
+                relative.startsWith(`..${path.sep}`) ||
+                path.isAbsolute(relative))) {
+            throw new Error("Init Task staging path must stay inside .pactile/tasks");
+        }
+        const entry = fs.lstatSync(directory, { throwIfNoEntry: false });
+        if (!entry)
+            continue;
+        if (entry.isSymbolicLink() ||
+            !entry.isDirectory() ||
+            fs.realpathSync(directory) !== directory) {
+            throw new Error("Init Task paths must be real directories inside the project");
+        }
+    }
+    return tasksRoot;
+}
+function readInitTaskMarker(cwd, taskName) {
+    try {
+        const tasksRoot = assertSafeInitTaskPaths(cwd);
+        const marker = path.join(tasksRoot, `.pending-${taskName}`);
+        const entry = fs.lstatSync(marker);
+        if (!entry.isFile() ||
+            entry.isSymbolicLink() ||
+            entry.size > MAX_INIT_TASK_MARKER_BYTES) {
+            return null;
+        }
+        const contents = fs.readFileSync(marker, "utf8");
+        if (contents === INIT_TASK_MARKER_TEXT)
+            return { developerName: null };
+        if (!contents.startsWith(INIT_JOINER_MARKER_PREFIX) ||
+            !contents.endsWith("\n")) {
+            return null;
+        }
+        const encodedName = contents.slice(INIT_JOINER_MARKER_PREFIX.length, -1);
+        let parsedName;
+        try {
+            parsedName = JSON.parse(encodedName);
+        }
+        catch {
+            return null;
+        }
+        const developerName = normalizeInitJoinerDeveloperName(parsedName, taskName);
+        return developerName ? { developerName } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasInitTaskMarker(cwd, taskName) {
+    return readInitTaskMarker(cwd, taskName) !== null;
+}
+function readPendingJoinerMarkers(cwd) {
     try {
-        fs.mkdirSync(taskDir, { recursive: true });
-        const created = applyKernelCreate({
-            taskDir,
-            actor: "pactile init",
-            idempotencyKey: `init:${taskName}`,
-            record: { ...taskJson, status: "planning" },
-            evidence: "pactile init skeleton",
+        const tasksRoot = assertSafeInitTaskPaths(cwd);
+        if (!pathExists(tasksRoot))
+            return [];
+        const taskNames = fs
+            .readdirSync(tasksRoot)
+            .filter((entry) => entry.startsWith(".pending-00-join-"))
+            .map((entry) => entry.slice(".pending-".length));
+        return taskNames.map((taskName) => {
+            const marker = readInitTaskMarker(cwd, taskName);
+            return {
+                taskName,
+                developerName: marker?.developerName ?? null,
+                valid: marker !== null,
+            };
         });
-        if (taskJson.status === "in_progress") {
-            applyKernelStart({
-                taskDir,
-                expectedRevision: created.kernel.revision,
-                actor: "pactile init",
-                idempotencyKey: `init-start:${taskName}`,
-                record: { ...taskJson, status: "in_progress" },
-                evidence: "pactile init skeleton start",
+    }
+    catch {
+        return [];
+    }
+}
+function readPendingJoinerDeveloperName(cwd) {
+    const markers = readPendingJoinerMarkers(cwd);
+    if (markers.length !== 1)
+        return null;
+    return markers[0].developerName;
+}
+function clearInitTaskMarker(cwd, taskName) {
+    if (hasInitTaskMarker(cwd, taskName)) {
+        try {
+            const tasksRoot = assertSafeInitTaskPaths(cwd);
+            fs.unlinkSync(path.join(tasksRoot, `.pending-${taskName}`));
+        }
+        catch {
+            // A missing, unreadable, or user-owned marker is left untouched.
+        }
+    }
+}
+function ensureInitTaskMarker(cwd, taskName, developerName) {
+    try {
+        let tasksRoot = assertSafeInitTaskPaths(cwd);
+        fs.mkdirSync(tasksRoot, { recursive: true });
+        tasksRoot = assertSafeInitTaskPaths(cwd);
+        const marker = path.join(tasksRoot, `.pending-${taskName}`);
+        const markerContent = initTaskMarkerContent(taskName, developerName);
+        try {
+            fs.writeFileSync(marker, markerContent, {
+                encoding: "utf8",
+                flag: "wx",
             });
+            return true;
         }
-        fs.writeFileSync(path.join(taskDir, FILE_NAMES.PRD), prdContent, "utf-8");
-        return true;
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return false;
+            const existing = readInitTaskMarker(cwd, taskName);
+            if (!existing)
+                return false;
+            if (!developerName)
+                return true;
+            const normalizedName = normalizeInitJoinerDeveloperName(developerName.trim(), taskName);
+            if (!normalizedName)
+                return existing.developerName === null;
+            if (existing.developerName === normalizedName)
+                return true;
+            if (existing.developerName !== null)
+                return false;
+            // Upgrade only the exact legacy sentinel owned by init. A malformed or
+            // user-edited marker never reaches this branch because the reader rejects it.
+            fs.writeFileSync(marker, markerContent, {
+                encoding: "utf8",
+                flag: "w",
+            });
+            return readInitTaskMarker(cwd, taskName)?.developerName === normalizedName;
+        }
+    }
+    catch {
+        // A conflicting, unreadable, or unwritable marker path is never replaced.
+        return false;
+    }
+}
+function recordInitTaskFailure(cwd, taskName) {
+    ensureInitTaskMarker(cwd, taskName);
+}
+function isCompleteExistingInitTask(cwd, taskName, taskId) {
+    const taskDir = path.join(cwd, PATHS.TASKS, taskName);
+    try {
+        const entry = fs.lstatSync(taskDir);
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            return false;
+        const prd = fs.readFileSync(path.join(taskDir, FILE_NAMES.PRD), "utf8");
+        if (!prd.trim())
+            return false;
+        const read = readTaskKernel({ root: cwd, taskDir, cwd });
+        if (read.kind === "task-kernel-v2") {
+            return (read.kernel.identity.taskId === taskId &&
+                read.kernel.definition.taskId === taskId);
+        }
+        // Keep complete historical V1 tasks in place for the explicit migration
+        // flow. A task.json without a persisted, matching Kernel is not complete.
+        const taskJson = JSON.parse(fs.readFileSync(path.join(taskDir, FILE_NAMES.TASK_JSON), "utf8"));
+        const legacyKernel = read.kernel.kernel;
+        const projection = legacyKernel.projection;
+        return (read.kernel.persisted &&
+            legacyKernel.identity.taskId === taskName &&
+            projection !== null &&
+            taskJson.id === taskName &&
+            taskJson.status === projection.status &&
+            projection.record.id === taskName &&
+            projection.record.status === projection.status);
     }
     catch {
         return false;
     }
 }
+function removeInitTaskStaging(stagingRoot, stagingDir) {
+    const relative = path.relative(stagingRoot, path.resolve(stagingDir));
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative) ||
+        fs.lstatSync(stagingDir).isSymbolicLink()) {
+        throw new Error("Unsafe init Task staging cleanup target");
+    }
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+}
 /**
- * Compute the bootstrap checklist items (previously stored as structured
- * `subtasks: [{name, status}]` in task.json). Per task 04-21-task-schema-unify
- * (D1), these live as markdown `- [ ]` items in prd.md instead, so task.json
- * stays canonical with `subtasks: string[]` (child task dir names).
+ * Publish a complete V2 Define Task (kernel.json + prd.md).
+ *
+ * A complete existing task is kept. A partial one is reported for recovery,
+ * never silently treated as a successful init. Historical V1 records are
+ * preserved for the explicit migration flow and are never rewritten here.
  */
+function writeTaskSkeleton(cwd, taskName, definition, actor, prdContent) {
+    let tasksRoot = null;
+    let stagingRoot = null;
+    let stagingDir = null;
+    let createdStagingRoot = false;
+    let committed = false;
+    try {
+        tasksRoot = assertSafeInitTaskPaths(cwd);
+        stagingRoot = path.join(tasksRoot, ".creating");
+        if (pathExists(path.join(tasksRoot, taskName))) {
+            if (!isCompleteExistingInitTask(cwd, taskName, definition.taskId)) {
+                throw new Error(`Task already exists or needs recovery: ${taskName}`);
+            }
+            clearInitTaskMarker(cwd, taskName);
+            return true;
+        }
+        fs.mkdirSync(tasksRoot, { recursive: true });
+        assertSafeInitTaskPaths(cwd);
+        try {
+            fs.mkdirSync(stagingRoot);
+            createdStagingRoot = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existingStagingRoot = fs.lstatSync(stagingRoot);
+            if (!existingStagingRoot.isDirectory() ||
+                existingStagingRoot.isSymbolicLink()) {
+                throw new Error("Init Task staging path must be a directory");
+            }
+        }
+        assertSafeInitTaskPaths(cwd, [stagingRoot]);
+        stagingDir = fs.mkdtempSync(path.join(stagingRoot, `${taskName}-`));
+        assertSafeInitTaskPaths(cwd, [stagingRoot, stagingDir]);
+        fs.writeFileSync(path.join(stagingDir, FILE_NAMES.PRD), prdContent, {
+            encoding: "utf8",
+            flag: "wx",
+        });
+        const created = createTaskKernel({
+            root: cwd,
+            taskDir: stagingDir,
+            definition,
+            actor,
+            idempotencyKey: `init-v2:${definition.taskId}`,
+            cwd,
+        });
+        if (created.kernel.phase !== "define" ||
+            created.kernel.runs.length !== 0 ||
+            created.kernel.reviews.length !== 0 ||
+            created.kernel.closure !== null) {
+            throw new Error("Init Task did not produce the expected V2 Define state");
+        }
+        const verified = readTaskKernel({ root: cwd, taskDir: stagingDir, cwd });
+        if (verified.kind !== "task-kernel-v2" ||
+            verified.kernel.identity.taskId !== definition.taskId ||
+            verified.kernel.definition.deliveryLevel !== definition.deliveryLevel ||
+            verified.kernel.definition.dependencies.length !== 0 ||
+            verified.kernel.phase !== "define" ||
+            verified.kernel.runs.length !== 0 ||
+            verified.kernel.reviews.length !== 0 ||
+            verified.kernel.closure !== null) {
+            throw new Error("Init Task failed V2 Kernel read-back validation");
+        }
+        assertSafeInitTaskPaths(cwd, [stagingRoot, stagingDir]);
+        const taskDir = path.join(tasksRoot, taskName);
+        if (pathExists(taskDir))
+            throw new Error(`Task already exists: ${taskName}`);
+        fs.renameSync(stagingDir, taskDir);
+        stagingDir = null;
+        committed = true;
+        clearInitTaskMarker(cwd, taskName);
+        return true;
+    }
+    catch {
+        recordInitTaskFailure(cwd, taskName);
+        return false;
+    }
+    finally {
+        if (!committed &&
+            stagingRoot &&
+            stagingDir &&
+            pathExists(stagingDir)) {
+            try {
+                assertSafeInitTaskPaths(cwd, [stagingRoot, stagingDir]);
+                removeInitTaskStaging(stagingRoot, stagingDir);
+            }
+            catch {
+                // Leave unexpected staging state for inspection; the marker remains.
+            }
+        }
+        if (createdStagingRoot && stagingRoot && pathExists(stagingRoot)) {
+            try {
+                assertSafeInitTaskPaths(cwd, [stagingRoot]);
+                const currentStagingRoot = fs.lstatSync(stagingRoot);
+                if (currentStagingRoot.isDirectory() &&
+                    !currentStagingRoot.isSymbolicLink() &&
+                    fs.readdirSync(stagingRoot).length === 0) {
+                    fs.rmdirSync(stagingRoot);
+                }
+            }
+            catch {
+                // Preserve unexpected or user-modified paths during cleanup.
+            }
+        }
+    }
+}
+/** Build the human-readable checklist mirrored by the bootstrap Task's AC. */
 function getBootstrapChecklistItems(projectType, packages) {
     if (packages && packages.length > 0) {
         const items = packages.map((pkg) => `Fill guidelines for ${pkg.name}`);
@@ -117,7 +437,7 @@ function renderCapabilityReadinessSection(selectedCapabilities) {
     })
         .join("\n");
     return `
-## Capability readiness (required before archive)
+## Capability readiness (record before Review and Close)
 
 Init selected optional project capabilities for this repo. Treat them as
 \`pending\` until you verify they work in this checkout.
@@ -131,7 +451,7 @@ ${checklist}
   watcher auto-syncs later edits; you do not need to re-run full indexing for
   every code change.
 - If a capability cannot be made ready, record the failure and fallback path in
-  \`verify.md\` before archiving bootstrap.
+  this Task's evidence before independent Review and Close.
 - Validation entrypoint: \`pactile capability-smoke --write-status\`
 
 ---
@@ -154,23 +474,17 @@ function getBootstrapPrdContent(projectType, selectedCapabilities, packages) {
     const checklistMarkdown = checklistItems
         .map((item) => `- [ ] ${item}`)
         .join("\n");
+    const acceptanceMarkdown = getBootstrapTaskDefinition(projectType, selectedCapabilities, packages)
+        .acceptanceCriteria.map((criterion) => `- [ ] ${criterion.id}: ${criterion.description}`)
+        .join("\n");
     const header = `# Bootstrap Task: Fill Project Development Guidelines
 
-**You (the AI) are running this task. The developer does not read this file.**
+**Task state: V2 Define. No Run exists, and init does not authorize execution.**
 
-The developer just ran \`pactile init\` on this project for the first time.
-\`.pactile/\` now exists with empty spec scaffolding, and this bootstrap task
-exists under \`.pactile/tasks/\`. When they want to work on it, they should start
-this task from a session that provides Pactile session identity.
-
-**Your job**: help them populate \`.pactile/spec/\` with the team's real
-coding conventions. Every future AI session — this project's
-\`pactile-implement\` and \`pactile-check\` sub-agents — auto-loads spec files
-listed in per-task jsonl manifests. Empty spec = sub-agents write generic
-code. Real spec = sub-agents match the team's actual patterns.
+pactile init created this V2 Task as a proposal to document the project's actual conventions. Its kernel.json records Task state; this prd.md is the human-readable plan. Before starting any Run or making project changes, obtain the user's ordinary, explicit approval for that work.\n\n**Deliverable**: useful, evidence-based project guidance in .pactile/spec/. Read the current workflow and the project itself. Do not assume that a named sub-agent, host hook, or automatic prompt injection is installed or active; verify actual host behavior before making such a claim. Contributors can consult relevant spec files directly when working on this project.
 
 Don't dump instructions. Open with a short greeting, figure out if the repo
-has any existing convention docs (AGENTS.md, .cursorrules, CONTRIBUTING.md, etc.), and drive
+has any existing convention docs (AGENTS.md, CONTRIBUTING.md, etc.), and drive
 the rest conversationally.
 
 ---
@@ -179,6 +493,10 @@ the rest conversationally.
 
 ${checklistMarkdown}
 
+## Acceptance criteria
+
+${acceptanceMarkdown}
+
 ---
 
 ${renderCapabilityReadinessSection(selectedCapabilities)}
@@ -230,8 +548,6 @@ usually much faster than documenting from scratch.
 | File / Directory | Notes |
 |------|------|
 | \`AGENTS.md\` | Agent entry / managed instructions |
-| \`.cursorrules\` | Legacy Cursor rules file |
-| \`.cursor/rules/*.mdc\` | Cursor rules directory |
 | \`CONTRIBUTING.md\` | General project conventions |
 | \`.editorconfig\` | Editor formatting rules |
 
@@ -245,50 +561,22 @@ Scan real code to discover patterns. Before writing each spec file:
 ### Step 3: Document reality, not ideals
 
 **Critical**: write what the code *actually does*, not what it should do.
-Sub-agents match the spec, so aspirational patterns that don't exist in the
-codebase will cause sub-agents to write code that looks out of place.
+Separate verified patterns from open questions so the documentation does not
+present aspirational conventions as current behavior.
 
 If the team has known tech debt, document the current state — improvement
 is a separate conversation, not a bootstrap concern.
 
 ---
 
-## Quick explainer of the runtime (share when they ask "why do we need spec at all")
-
-- Every AI coding task spawns two sub-agents: \`pactile-implement\` (writes
-  code) and \`pactile-check\` (verifies quality).
-- Each task has \`implement.jsonl\` / \`check.jsonl\` manifests listing which
-  spec files to load.
-- The platform hook auto-injects those spec files + the task's \`prd.md\`
-  into every sub-agent prompt, so the sub-agent codes/reviews per team
-  conventions without anyone pasting them manually.
-- Source of truth: \`.pactile/spec/\`. That's why filling it well now pays
-  off forever.
-
----
-
-## Completion
-
-When the developer confirms the checklist items above are done with real
-examples (not placeholders), guide them to run:
-
-\`\`\`bash
-pactile task archive 00-bootstrap-guidelines --check
-pactile task archive 00-bootstrap-guidelines
-\`\`\`
-
-After archive, every new developer who joins this project will get a
-\`00-join-<slug>\` onboarding task instead of this bootstrap task.
+## How this fits the Task workflow\n\n- A V2 Task Kernel records the definition, hard dependencies, Runs, candidate snapshots, independent Reviews, and Close evidence. .pactile/workflow.md is a human overview; the Kernel is lifecycle authority.\n- This generated Task has no Run. A Run may begin only after the user approves the specific work through the ordinary approval flow.\n- A completed Run produces a candidate that must receive an independent Review bound to that exact candidate. Close uses the latest passing Review and evidence for every acceptance criterion, with documentation delivery evidence for this Task.\n- Scheduler suggestions do not grant approval or bypass Kernel gates. Use the current V2 Task commands and pactile task --help for their arguments.\n\n---\n
+## Completion\n\nWhen the checklist items are complete, record evidence for every acceptance criterion, including references to the documented files and real examples. Ask the user before creating a Run. Then follow the V2 lifecycle: approved Run, candidate-bound independent Review, and Close with matching documentation delivery evidence. Init, a scheduler plan, or this PRD is not execution approval.
 
 ---
 
 ## Suggested opening line
 
-"Welcome to Pactile! Your init just set me up to help you fill the project
-spec — a one-time setup so every future AI session follows the team's
-conventions instead of writing generic code. Before we start, do you have
-any existing convention docs (AGENTS.md, .cursorrules, CONTRIBUTING.md,
-etc.) I can pull from, or should I scan the codebase from scratch?"
+"Welcome to Pactile! Init created a proposal to document this project's conventions. Do you have existing convention docs (AGENTS.md, CONTRIBUTING.md, or similar) I should compare with the code, or should I begin by inspecting the repository?"
 `;
     let content = header;
     if (packages && packages.length > 0) {
@@ -319,184 +607,167 @@ etc.) I can pull from, or should I scan the codebase from scratch?"
     content += footer;
     return content;
 }
-function getBootstrapTaskJson(developer, projectType, packages) {
-    const today = new Date().toISOString().split("T")[0];
+function getBootstrapTaskDefinition(projectType, selectedCapabilities, packages) {
     const relatedFiles = getBootstrapRelatedFiles(projectType, packages);
-    // Canonical 24-field shape via emptyTaskJson factory.
-    // Checklist items (previously stored as structured `subtasks`) are now
-    // rendered as `- [ ]` items in prd.md; task.json.subtasks is always
-    // string[] (child task dir names) per the canonical schema.
-    return emptyTaskJson({
-        id: BOOTSTRAP_TASK_NAME,
-        name: BOOTSTRAP_TASK_NAME,
-        title: "Bootstrap Guidelines",
-        description: "Fill in project development guidelines for AI agents",
-        status: "in_progress",
-        dev_type: "docs",
-        priority: "P1",
-        creator: developer,
-        assignee: developer,
-        createdAt: today,
-        relatedFiles,
-        notes: `First-time setup task created by pactile init (${projectType} project)`,
-    });
+    const checklistItems = getBootstrapChecklistItems(projectType, packages);
+    const acceptanceCriteria = [
+        {
+            id: "AC-1",
+            description: "Complete the project-specific checklist (" +
+                checklistItems.join("; ") +
+                ") and update the relevant spec files: " +
+                relatedFiles.join(", ") +
+                ".",
+        },
+        {
+            id: "AC-2",
+            description: "For each documented convention, cite at least two real repository examples or source documents; mark unsupported claims as open questions instead of presenting them as facts.",
+        },
+    ];
+    if (selectedCapabilities.length > 0) {
+        acceptanceCriteria.push({
+            id: "AC-3",
+            description: "Record each selected capability as ready, pending, or failed using observable verification evidence; do not report a capability as ready without that evidence.",
+        });
+    }
+    return {
+        taskId: BOOTSTRAP_TASK_NAME,
+        title: "Populate project development guidelines",
+        description: "Document verified project conventions in the Pactile specification files.",
+        deliverable: "Evidence-based project guidance in " +
+            relatedFiles.join(", ") +
+            " with acceptance evidence recorded for this Task.",
+        deliveryLevel: "documentation",
+        acceptanceCriteria,
+        dependencies: [],
+    };
 }
 /**
  * Create bootstrap task for first-time setup
  */
 function createBootstrapTask(cwd, developer, projectType, selectedCapabilities, packages) {
-    const taskJson = getBootstrapTaskJson(developer, projectType, packages);
+    const definition = getBootstrapTaskDefinition(projectType, selectedCapabilities, packages);
     const prdContent = getBootstrapPrdContent(projectType, selectedCapabilities, packages);
-    return writeTaskSkeleton(cwd, BOOTSTRAP_TASK_NAME, taskJson, prdContent);
+    return writeTaskSkeleton(cwd, BOOTSTRAP_TASK_NAME, definition, "pactile init (" + developer + ")", prdContent);
 }
 // =============================================================================
 // Joiner Onboarding Task Creation
 // =============================================================================
-/**
- * task.json factory for joiner onboarding. Mirrors the bootstrap factory but
- * uses dev_type "docs", higher priority "P1", and the developer-specific task
- * name (so multiple joiners in the same checkout don't collide).
- */
-function getJoinerTaskJson(developer, taskName) {
-    const today = new Date().toISOString().split("T")[0];
-    return emptyTaskJson({
-        id: taskName,
-        name: taskName,
-        title: `Joining: Onboard to this Pactile project (${developer})`,
-        description: "Onboard a new developer to an existing Pactile project: learn the workflow, conventions, and find assigned work",
-        status: "in_progress",
-        dev_type: "docs",
-        priority: "P1",
-        creator: developer,
-        assignee: developer,
-        createdAt: today,
-        notes: "Generated by pactile init for a new developer joining an existing Pactile project",
-    });
+/** Create the V2 documentation Task used for a new project joiner. */
+function getJoinerTaskDefinition(developer, taskId, taskName, selectedCapabilities) {
+    const acceptanceCriteria = [
+        {
+            id: "AC-1",
+            description: "Create onboarding-notes.md in the Task directory with references to this project's actual workflow and specification files, and explain that the Kernel controls lifecycle state.",
+        },
+        {
+            id: "AC-2",
+            description: "Record the active V2 Task IDs found or explicitly state that none are listed; do not infer V2 assignment from legacy task fields.",
+        },
+    ];
+    if (selectedCapabilities.length > 0) {
+        acceptanceCriteria.push({
+            id: "AC-3",
+            description: "Record each selected capability as ready, pending, or failed with observable verification evidence, or state that verification was not performed.",
+        });
+    }
+    return {
+        taskId,
+        title: "Onboard developer to this Pactile project: " + developer,
+        description: "Prepare a concise onboarding note based on the actual project workflow, conventions, and visible V2 Tasks.",
+        deliverable: "A project-specific onboarding note at .pactile/tasks/" +
+            taskName +
+            "/onboarding-notes.md with evidence for each acceptance criterion.",
+        deliveryLevel: "documentation",
+        acceptanceCriteria,
+        dependencies: [],
+    };
 }
 /**
  * PRD content for joiner onboarding. Kept concise (~80 lines) — deeper
  * guidance lives in skills and docs.
  */
-function getJoinerPrdContent(developer, selectedCapabilities) {
-    const slug = slugifyDeveloperName(developer);
+function getJoinerPrdContent(developer, taskName, taskId, selectedCapabilities) {
     const selectedCapabilityChecklist = selectedCapabilities
         .map((id) => {
         const capability = getProjectCapability(id);
-        return `- \`${capability.id}\` — re-check readiness in this clone before claiming it is available.`;
+        return ("- " +
+            capability.id +
+            " — re-check readiness in this clone before claiming it is available.");
     })
         .join("\n");
-    let capabilitySection = "";
-    if (selectedCapabilities.length > 0) {
-        capabilitySection = `
-### 5. Re-verify selected project capabilities
-
-This repo has capability selections recorded in \`.pactile/capabilities.json\`.
-Before they rely on MCP-backed behavior, remind them to check the selected set:
-
-${selectedCapabilityChecklist}
-
-- If a capability is not \`ready\`, have them re-run the local verification path
-  instead of assuming the previous machine's setup carries over.
-
----
-`;
-    }
-    return `# Joiner Onboarding Task
-
-**You (the AI) are running this task. The developer does not read this file.**
-
-\`${developer}\` just ran \`pactile init\` on a fresh clone, saw "Developer
-initialized", and will now start asking you questions in chat. This joiner task
-exists under \`.pactile/tasks/\`; when they want to work on it, they should
-select it from a session that provides Pactile session identity.
-
-Your job is to orient them to Pactile. Don't dump all of this at them — open
-with a short greeting, ask where they want to start, and fill in the rest as
-they engage.
-
----
-
-## Topics to cover (adapt order to their questions)
-
-### 1. What Pactile is + the workflow
-
-Pactile is a governed capability workspace for Codex that keeps AI
-agents consistent with project-specific conventions instead of writing generic
-code every session.
-
-- **Human lifecycle**: Open → Define → Approve → Execute → Verify →
-  (Integrate? when parent-child) → Close. Kernel writes that state.
-  \`.pactile/workflow.md\` is a human overview, **not runtime SSOT**.
-- **Task files** live under \`.pactile/tasks/\`. \`status\` is a projection, not
-  the only truth.
-- **Codex session**: read the Task record, project instructions, and current
-  Evidence before resuming. The Task record remains durable authority.
-
-### 2. Runtime mechanics (explain when they ask "how does it know what to do")
-
-- **Context**: load Kernel / Dashboard and the selected Task's \`prd.md\`
-  plus recent activity. Do not treat a generated phase index as runtime
-  authority.
-- **Coordination**: \`pactile codex\` records native desktop task requests and
-  receipts; the App task invokes its native tools. \`pactile pi\` dispatches
-  approved Execute work through Pi RPC.
-
-File layout (mention when they ask "where does what live"):
-- \`.pactile/.runtime/sessions/<session>.json\` — live-session selected-task state, gitignored
-- \`.pactile/tasks/<task>/{implement,check}.jsonl\` — per-task context manifests
-- \`.pactile/spec/\` — project-wide conventions (source of truth)
-- \`.pactile/workspace/${developer}/journal-*.md\` — their session log,
-  rotated at ~2000 lines
-
-### 3. This project's actual conventions
-
-- Summarize \`.pactile/spec/\` for them — what coding conventions this
-  specific team enforces.
-- Point at the last 5 entries in \`.pactile/tasks/archive/\` as a rhythm
-  example of how people actually work here. **If archive is empty** (the
-  project just started), skip this — don't invent examples.
-- Not your job in this onboarding to teach them the business code itself —
-  the README and their teammates handle that.
-
-### 4. Their assigned work
-
-- Check if \`.pactile/workspace/${developer}/\` already exists — if yes, it's
-  their journal from another machine and worth mentioning.
-- Run \`pactile task list --assignee "${developer}"\` to
-  show tasks assigned to them. (Quote the name if it contains spaces.)
-- Remind them to inspect assigned Tasks at the start of each session.
-
----
-
-${capabilitySection}
-
-## Optional: walk through a small task end-to-end
-
-If they want to practice before touching real work, offer to pick a tiny
-P3 task or a typo fix and run the full cycle together: define → approve →
-execute → verify → close.
-
----
-
-## Completion
-
-When they feel oriented (or after you've covered the four topics with
-reasonable back-and-forth), guide them to run:
-
-\`\`\`bash
-pactile task archive 00-join-${slug} --check
-pactile task archive 00-join-${slug}
-\`\`\`
-
----
-
-## Suggested opening line
-
-"Welcome! Your \`pactile init\` set me up to onboard you to this project. I
-can walk you through the workflow, show you the runtime mechanics under the
-hood, summarize the team's spec, or jump to what you're already curious about
-— which would you prefer?"
-`;
+    const capabilitySection = selectedCapabilities.length > 0
+        ? [
+            "### Selected project capabilities",
+            "",
+            "Re-check each selected capability in this clone before relying on it:",
+            "",
+            selectedCapabilityChecklist,
+            "",
+            "If verification is incomplete, record it as pending or failed with the fallback path.",
+        ].join("\n")
+        : "";
+    const acceptanceCriteriaMarkdown = getJoinerTaskDefinition(developer, taskId, taskName, selectedCapabilities)
+        .acceptanceCriteria.map((criterion) => "- [ ] " + criterion.id + ": " + criterion.description)
+        .join("\n");
+    return [
+        "# Joiner Onboarding Task",
+        "",
+        "Task ID: " +
+            taskId +
+            ". State: V2 Define. No Run exists, and init does not authorize execution.",
+        "",
+        "pactile init created this V2 Task for " +
+            developer +
+            " as an onboarding proposal. The Kernel in .pactile/tasks/" +
+            taskName +
+            "/kernel.json records its definition and lifecycle. This PRD is the human-readable plan.",
+        "Before starting a Run or changing project files, obtain the user's ordinary, explicit approval for that work.",
+        "",
+        "Your deliverable is a concise onboarding note at .pactile/tasks/" +
+            taskName +
+            "/onboarding-notes.md. Use project evidence, and mark unavailable information as unknown rather than guessing.",
+        "",
+        "## Onboarding topics",
+        "",
+        "### 1. Current Task workflow",
+        "",
+        "- Read .pactile/workflow.md as a human overview. The V2 Task Kernel is lifecycle authority.",
+        "- Explain the Task definition, hard dependencies, and why a Run needs ordinary user approval.",
+        "- Explain that a Task can have multiple Runs and that an independent Review binds to the exact candidate from one Run.",
+        "- Explain that Close uses the latest passing Review, evidence for every acceptance criterion, and the delivery evidence level in the Task definition.",
+        "- Use pactile task --help for the current command arguments. Do not assume a host spawned a named agent or ran a hook without an observable receipt.",
+        "",
+        "### 2. This project's actual conventions",
+        "",
+        "- Read .pactile/spec/ and cite the relevant files in onboarding-notes.md.",
+        "- Compare the written guidance with real repository files; mark unresolved questions explicitly.",
+        "- Do not treat old archive directories or generated phase hints as V2 lifecycle authority.",
+        "",
+        "### 3. Visible V2 Tasks and next steps",
+        "",
+        "- Run pactile task schedule list to inspect visible V2 scheduling candidates. Record their Task IDs, or state that none were listed.",
+        "- Ask the user which approved work they want to pursue. The V2 Task definition has no assignee field, so do not infer assignment from legacy task.json data.",
+        "- If the user wants a practice task, agree on its definition and acceptance criteria first, then follow the ordinary approval, Run, independent Review, and Close gates.",
+        "",
+        capabilitySection,
+        "",
+        "## Acceptance criteria",
+        "",
+        acceptanceCriteriaMarkdown,
+        "",
+        "## Acceptance evidence",
+        "",
+        "In onboarding-notes.md include links or repository-relative paths to the workflow and spec files reviewed, the V2 Task IDs found (or none), and capability verification status when applicable.",
+        "",
+        "Before completion, check every acceptance criterion in the Task definition. Ask the user before any Run, record a candidate-bound independent Review, then Close with documentation delivery evidence that points to onboarding-notes.md. Do not move the task directory as a substitute for Close.",
+        "",
+        "## Suggested opening",
+        "",
+        "Welcome, " +
+            developer +
+            ". I can start by explaining the current Task workflow, reviewing the project conventions, or checking which V2 Tasks are visible. Which is most useful?",
+    ].join("\n");
 }
 /**
  * Create joiner onboarding task for a new developer on an existing Pactile
@@ -506,9 +777,11 @@ hood, summarize the team's spec, or jump to what you're already curious about
 function createJoinerOnboardingTask(cwd, developer) {
     const slug = slugifyDeveloperName(developer);
     const taskName = `00-join-${slug}`;
-    const taskJson = getJoinerTaskJson(developer, taskName);
-    const prdContent = getJoinerPrdContent(developer, loadProjectCapabilities(cwd));
-    return writeTaskSkeleton(cwd, taskName, taskJson, prdContent);
+    const taskId = taskKernelIdForDirectoryName(taskName);
+    const selectedCapabilities = loadProjectCapabilities(cwd);
+    const definition = getJoinerTaskDefinition(developer, taskId, taskName, selectedCapabilities);
+    const prdContent = getJoinerPrdContent(developer, taskName, taskId, selectedCapabilities);
+    return writeTaskSkeleton(cwd, taskName, definition, `pactile init (${developer})`, prdContent);
 }
 /**
  * Handle re-init when .pactile/ already exists.
@@ -622,16 +895,24 @@ async function handleReinit(cwd, options, developerName) {
         // the Node identity writer, this checkout had no identity → treat as a new
         // joiner onboarding onto an existing Pactile project.
         const hadDeveloperFileBefore = fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW, FILE_NAMES.DEVELOPER));
-        try {
-            initializeDeveloper(cwd, devName);
-            console.log(chalk.green(`✓ Developer "${devName}" initialized`));
+        const joinerTaskName = `00-join-${slugifyDeveloperName(devName)}`;
+        const joinerIntentReady = hadDeveloperFileBefore ||
+            ensureInitTaskMarker(cwd, joinerTaskName, devName);
+        if (!joinerIntentReady) {
+            console.warn(chalk.yellow("⚠ Could not record joiner recovery intent; developer identity was not initialized"));
         }
-        catch (err) {
-            console.log(chalk.yellow(`⚠ Could not initialize developer: ${err instanceof Error ? err.message : String(err)}`));
+        if (joinerIntentReady) {
+            try {
+                initializeDeveloper(cwd, devName);
+                console.log(chalk.green(`✓ Developer "${devName}" initialized`));
+            }
+            catch (err) {
+                console.log(chalk.yellow(`⚠ Could not initialize developer: ${err instanceof Error ? err.message : String(err)}`));
+            }
         }
         // Create joiner onboarding task for fresh checkouts (no prior .developer).
         // Runs outside the init_developer try/catch so failures surface as warnings.
-        if (!hadDeveloperFileBefore) {
+        if (!hadDeveloperFileBefore && joinerIntentReady) {
             try {
                 if (!createJoinerOnboardingTask(cwd, devName)) {
                     console.warn(chalk.yellow("⚠ Failed to create joiner onboarding task"));
@@ -731,11 +1012,6 @@ export async function init(options) {
     const banner = figlet.textSync("Pactile", { font: "Rebel" });
     console.log(chalk.cyan(`\n${banner.trimEnd()}`));
     console.log(chalk.gray("\n   Governed AI workflow for Codex\n"));
-    // Set up proxy before any network calls
-    const proxyUrl = setupProxy();
-    if (proxyUrl) {
-        console.log(chalk.gray(`   Using proxy: ${maskProxyUrl(proxyUrl)}\n`));
-    }
     // Set write mode based on options
     let writeMode = "ask";
     if (options.force) {
@@ -770,6 +1046,50 @@ export async function init(options) {
             }
         }
     }
+    // A joiner intent is durable before identity is written. Resolve any
+    // existing identity before dispatch so an unrelated request or marker cannot
+    // publish a Task under a second developer name.
+    let persistedDeveloper = null;
+    try {
+        persistedDeveloper = readDeveloper(cwd);
+    }
+    catch {
+        // Keep init best-effort when a user-owned identity file is unreadable.
+    }
+    const pendingJoinerMarkers = readPendingJoinerMarkers(cwd);
+    const validPendingJoinerMarkers = pendingJoinerMarkers.filter((marker) => marker.valid);
+    const hasPersistedDeveloperFile = pathExists(path.join(cwd, PATHS.DEVELOPER_FILE));
+    let requestedDeveloper = null;
+    const trimmedDeveloperName = developerName?.trim();
+    if (trimmedDeveloperName)
+        requestedDeveloper = trimmedDeveloperName;
+    const markerConflictsWithIdentity = (marker, identity) => marker.developerName !== null
+        ? marker.developerName !== identity
+        : marker.taskName !== `00-join-${slugifyDeveloperName(identity)}`;
+    const conflictsWithPersistedDeveloper = persistedDeveloper !== null &&
+        ((requestedDeveloper !== null &&
+            requestedDeveloper !== persistedDeveloper) ||
+            validPendingJoinerMarkers.some((marker) => markerConflictsWithIdentity(marker, persistedDeveloper)));
+    const conflictingRequestAndMarker = requestedDeveloper !== null &&
+        validPendingJoinerMarkers.some((marker) => markerConflictsWithIdentity(marker, requestedDeveloper));
+    const cannotValidatePersistedDeveloper = hasPersistedDeveloperFile &&
+        persistedDeveloper === null &&
+        (requestedDeveloper !== null || validPendingJoinerMarkers.length > 0);
+    if (conflictsWithPersistedDeveloper ||
+        conflictingRequestAndMarker ||
+        cannotValidatePersistedDeveloper) {
+        console.warn(chalk.yellow("⚠ Init stopped: the requested identity, pending joiner marker, and existing .developer identity cannot be reconciled. Preserve existing files and resolve the identity before retrying."));
+        return;
+    }
+    if (!options.user) {
+        if (persistedDeveloper &&
+            hasInitTaskMarker(cwd, `00-join-${slugifyDeveloperName(persistedDeveloper)}`)) {
+            developerName = persistedDeveloper;
+        }
+        else if (!persistedDeveloper) {
+            developerName = readPendingJoinerDeveloperName(cwd) ?? developerName;
+        }
+    }
     if (developerName) {
         console.log(chalk.blue("👤 Developer:"), chalk.gray(developerName));
     }
@@ -781,12 +1101,18 @@ export async function init(options) {
     // to the full flow so the main-dispatch tasksEmpty fallback fires —
     // handleReinit's joiner branch would otherwise mis-route the recovery.
     const tasksDirEarly = path.join(cwd, PATHS.TASKS);
-    const tasksEmptyEarly = !fs.existsSync(tasksDirEarly) || fs.readdirSync(tasksDirEarly).length === 0;
+    const pendingBootstrap = hasInitTaskMarker(cwd, BOOTSTRAP_TASK_NAME);
+    const pendingJoiner = developerName
+        ? hasInitTaskMarker(cwd, `00-join-${slugifyDeveloperName(developerName)}`)
+        : false;
+    const tasksEmptyEarly = !fs.existsSync(tasksDirEarly) || fs.readdirSync(tasksDirEarly).filter((entry) => entry !== ".creating" && !entry.startsWith(".pending-")).length === 0;
     if (!isFirstInit &&
         !importingCstl &&
         !options.force &&
         !options.skipExisting &&
-        !tasksEmptyEarly) {
+        !tasksEmptyEarly &&
+        !pendingBootstrap &&
+        !pendingJoiner) {
         const reinitDone = await handleReinit(cwd, options, developerName);
         if (reinitDone)
             return;
@@ -1427,8 +1753,37 @@ export async function init(options) {
         // migration backup or prompt for a legacy transition that never existed.
         writeWaveCConfirmed(cwd);
     }
-    // Initialize developer identity with Node (silent - no output).
+    let shouldCreateBootstrap = false;
+    let shouldCreateJoiner = false;
     if (developerName) {
+        const tasksDir = path.join(cwd, PATHS.TASKS);
+        const tasksEmpty = !fs.existsSync(tasksDir) ||
+            fs
+                .readdirSync(tasksDir)
+                .filter((entry) => entry !== ".creating" && !entry.startsWith(".pending-"))
+                .length === 0;
+        shouldCreateBootstrap =
+            (isFirstInit && !importingCstl) ||
+                pendingBootstrap ||
+                (tasksEmpty && !pendingJoiner);
+        shouldCreateJoiner =
+            !shouldCreateBootstrap &&
+                (!hadDeveloperFileAtStart || pendingJoiner);
+    }
+    const joinerTaskName = developerName
+        ? `00-join-${slugifyDeveloperName(developerName)}`
+        : null;
+    const joinerIntentReady = !developerName ||
+        !shouldCreateJoiner ||
+        (joinerTaskName !== null &&
+            ensureInitTaskMarker(cwd, joinerTaskName, developerName ?? undefined));
+    if (shouldCreateJoiner && !joinerIntentReady) {
+        console.warn(chalk.yellow("⚠ Could not record joiner recovery intent; developer identity was not initialized"));
+    }
+    // Initialize developer identity with Node (silent - no output). For a fresh
+    // joiner, the recovery intent must be durable before this write so a process
+    // interruption cannot leave identity without its onboarding Task.
+    if (developerName && joinerIntentReady) {
         try {
             if (!readDeveloper(cwd))
                 initializeDeveloper(cwd, developerName);
@@ -1451,15 +1806,16 @@ export async function init(options) {
         // Runs OUTSIDE the init_developer try/catch (which uses stdio: "pipe")
         // so joiner failures surface as warnings instead of being silently
         // swallowed.
-        const tasksDir = path.join(cwd, PATHS.TASKS);
-        const tasksEmpty = !fs.existsSync(tasksDir) || fs.readdirSync(tasksDir).length === 0;
-        if ((isFirstInit && !importingCstl) || tasksEmpty) {
+        if (shouldCreateBootstrap) {
             const bootstrapCreated = createBootstrapTask(cwd, developerName, projectType, selectedCapabilities, monorepoPackages);
             if (bootstrapCreated) {
                 console.log(chalk.gray(`Next: complete ${BOOTSTRAP_TASK_NAME} to verify selected capabilities and fill the project spec.`));
             }
+            else {
+                console.warn(chalk.yellow(`⚠ Failed to create ${BOOTSTRAP_TASK_NAME}; inspect .pactile/tasks/ and retry pactile init.`));
+            }
         }
-        else if (!hadDeveloperFileAtStart) {
+        else if (shouldCreateJoiner) {
             try {
                 if (!createJoinerOnboardingTask(cwd, developerName)) {
                     console.warn(chalk.yellow("⚠ Failed to create joiner onboarding task"));