alignfirst 0.2.1 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # alignfirst
 
-The AlignFirst CLI provides collaborative software-development workflows, work files, and documentation discovery. Work files are organized by ticket and kept either git-ignored in the project or synchronized through a team plans repository.
+The AlignFirst CLI provides collaborative software-development workflows, work files, and documentation discovery. Work files are organized by ticket and kept either git-ignored in the project or synchronized through a work-files repository.
 
 ## Agent skills
 
@@ -45,7 +45,7 @@ These examples use the `/` form. Replace it with `$` in Codex.
 
 To implement a plan, start a fresh agent context and ask it to execute the plan file.
 
-AlignFirst stores specifications, plans, and summaries in `.plans/<ticket-id>/`. It normally derives the ticket ID from the request or branch and asks when none is available. Files use a cycle letter and sequence number, such as `A1-spec.md` and `A2-plan.md`.
+AlignFirst stores the work files of a ticket, such as specifications, plans and summaries, in `.plans/<ticket-id>/`. It normally derives the ticket ID from the request or branch and asks when none is available. Files use a cycle letter and sequence number, such as `A1-spec.md` and `A2-plan.md`.
 
 ## Global CLI
 
@@ -81,8 +81,8 @@ The guide installs the selected components and configures the repository. You ca
 
 - `guide` — Print an AlignFirst protocol.
 - `ticket` — Resolve a ticket directory, load its history, or get its next file.
-- `sync` — Synchronize shared plans.
-- `plans` — Set up, check and archive plans.
+- `sync` — Synchronize the work files with the work-files repository.
+- `plans` — Link `.plans` to the work-files repository, check the link, archive tickets.
 - `docmap` — Browse project documentation.
 - `conventions` — Print the effective project conventions.
 - `context` — Print the conventions, the documentation map when `docs/` exists, and the protocol aliases.

package/dist/cli.js

@@ -39,7 +39,8 @@ export async function main(options) {
             ctx.projectConfig = resolveProjectConfig(ctx.cwd);
             checkCliRange(ctx.projectConfig?.config, ctx.version, [command, ...args]);
         }
-        return dispatch(ctx, command, args);
+        const code = await dispatch(ctx, command, args);
+        return code;
     }
     catch (error) {
         if (!(error instanceof CliError))
@@ -55,7 +56,7 @@ function readPackageVersion() {
     return pkg.version;
 }
 function renderHelp(ctx) {
-    return `alignfirst — protocols, plans and docs in one command.
+    return `alignfirst — protocols, work files and docs in one command.
 
 Usage:
   ${ctx.form} guide [<protocol>]

package/dist/commands/doctor.js

@@ -22,7 +22,7 @@ export function runDoctor(ctx, args) {
         return inspectConfig(ctx, resolved);
     });
     writeSection(ctx, "Git", () => inspectGit(ctx, resolved));
-    writeSection(ctx, "Plans", () => inspectPlans(ctx));
+    writeSection(ctx, "Work files", () => inspectPlans(ctx));
     writeSection(ctx, "Docmap", () => inspectDocmap(ctx));
     writeSection(ctx, "Skills", () => inspectSkills(ctx));
     return 0;

package/dist/commands/plans.js

@@ -51,10 +51,10 @@ function runSetup(ctx, args) {
 }
 function createPlansDirectory(cloneDir, folder) {
     if (folder.length === 0 || folder === "." || folder === ".." || /[\\/]/u.test(folder)) {
-        throw new CliError(`Plans folder "${folder}" must be a single path segment.`);
+        throw new CliError(`Project folder "${folder}" must be a single path segment.`);
     }
     if (RESERVED_PLANS_FOLDERS.has(folder.toLowerCase())) {
-        throw new CliError(`Plans folder "${folder}" is reserved.`);
+        throw new CliError(`Project folder "${folder}" is reserved.`);
     }
     const cloneRoot = realpathSync(cloneDir);
     const projectDir = join(cloneRoot, folder);
@@ -64,7 +64,7 @@ function createPlansDirectory(cloneDir, folder) {
         relativeTarget === ".." ||
         relativeTarget.startsWith(`..${sep}`) ||
         isAbsolute(relativeTarget)) {
-        throw new CliError(`Plans folder "${folder}" must resolve inside ${cloneRoot}.`);
+        throw new CliError(`Project folder "${folder}" must resolve inside ${cloneRoot}.`);
     }
     return projectDir;
 }
@@ -94,11 +94,11 @@ function parseSetupArgs(ctx, args, usage) {
 }
 function checkClone(ctx, cloneDir) {
     if (!existsSync(cloneDir))
-        throw new CliError(`${cloneDir} does not exist. Clone the team plans repository there first (see the instruction file).`);
+        throw new CliError(`${cloneDir} does not exist. Clone the work-files repository there first (see the instruction file).`);
     if (!existsSync(join(cloneDir, ".git")))
-        throw new CliError(`${cloneDir} is not a git repository. Point ${ctx.form} plans setup at a clone of the team plans repository.`);
+        throw new CliError(`${cloneDir} is not a git repository. Point ${ctx.form} plans setup at a clone of the work-files repository.`);
     if (realpathSync(cloneDir) === realpathSync(ctx.cwd))
-        throw new CliError(`${cloneDir} is the product repository itself. Point ${ctx.form} plans setup at a clone of the team plans repository.`);
+        throw new CliError(`${cloneDir} is the product repository itself. Point ${ctx.form} plans setup at a clone of the work-files repository.`);
 }
 function runCheck(ctx, args) {
     const usage = `Usage: ${ctx.form} plans check\n`;
@@ -111,9 +111,9 @@ function runCheck(ctx, args) {
             throw new CliError(renderStoppedRebase(stopped, ctx.form));
     }
     if (mode.kind === "shared")
-        ctx.stdout.write(".plans is linked to the team plans repository.\n");
+        ctx.stdout.write(".plans is linked to the work-files repository.\n");
     else
-        ctx.stdout.write(".plans is a local directory (local plans mode): synchronization is disabled.\n");
+        ctx.stdout.write(".plans is a local directory (local mode): synchronization is disabled.\n");
     return 0;
 }
 function runAutoArchive(ctx, args) {

package/dist/commands/sync.d.ts

@@ -1,2 +1,2 @@
 import type { CommandContext } from "../context.js";
-export declare function runSync(ctx: CommandContext, args: string[]): number;
+export declare function runSync(ctx: CommandContext, args: string[]): Promise<number>;

package/dist/commands/sync.js

@@ -5,8 +5,8 @@ import { git, gitOutput, gitSucceeds } from "../git.js";
 import { parseCommandArgs } from "../parse-args.js";
 import { archiveThresholdDays, autoArchive } from "../plans/archive.js";
 import { resolvePlansMode } from "../plans/mode.js";
-import { findStoppedRebase, renderStoppedRebase } from "../plans/rebase.js";
-export function runSync(ctx, args) {
+import { findStoppedRebase, renderStoppedRebase, resolveStoppedRebase } from "../plans/rebase.js";
+export async function runSync(ctx, args) {
     const usage = `Usage: ${ctx.form} sync [--auto-archive | --no-auto-archive]\n`;
     const options = parseSyncArgs(ctx, args, usage);
     if (options === undefined)
@@ -22,39 +22,40 @@ export function runSync(ctx, args) {
     if (mode.kind === "local") {
         if (thresholdDays !== undefined)
             autoArchive(plansDir, thresholdDays, ctx.stdout);
-        ctx.stdout.write("(local plans mode, nothing to sync)\n");
+        ctx.stdout.write("(local mode, nothing to sync)\n");
         return 0;
     }
     const repoDir = mode.repoToplevel;
     assertNoStoppedRebase(repoDir, ctx.form);
-    git(repoDir, "add", "-A");
+    await git(ctx, repoDir, "add", "-A");
     if (hasStagedChanges(repoDir))
-        git(repoDir, "commit", "--quiet", "-m", "sync");
+        await git(ctx, repoDir, "commit", "--quiet", "-m", "sync");
     if (hasUpstream(repoDir)) {
         try {
-            git(repoDir, "pull", "--rebase");
+            await git(ctx, repoDir, "pull", "--rebase");
         }
         catch {
-            assertNoStoppedRebase(repoDir, ctx.form);
-            throw new CliError("git pull failed. See the git output above.");
+            if (findStoppedRebase(repoDir) === undefined)
+                throw new CliError("git pull failed. See the git output above.");
+            await resolveStoppedRebase(ctx, repoDir);
         }
     }
     if (thresholdDays !== undefined && autoArchive(plansDir, thresholdDays, ctx.stdout)) {
-        git(repoDir, "add", "-A");
+        await git(ctx, repoDir, "add", "-A");
         if (hasStagedChanges(repoDir))
-            git(repoDir, "commit", "--quiet", "-m", "sync");
+            await git(ctx, repoDir, "commit", "--quiet", "-m", "sync");
     }
     if (hasCommitsToSend(repoDir)) {
         try {
-            git(repoDir, "push", "--quiet", "-u", "origin", "HEAD");
+            await git(ctx, repoDir, "push", "--quiet", "-u", "origin", "HEAD");
         }
         catch {
             throw new CliError(`git push failed. See the git output above. Another synchronization may have landed first: run ${ctx.form} sync again.`);
         }
-        ctx.stdout.write("Plans synchronized: local changes sent.\n");
+        ctx.stdout.write("Work files synchronized: local changes sent.\n");
     }
     else {
-        ctx.stdout.write("Plans synchronized: nothing to send.\n");
+        ctx.stdout.write("Work files synchronized: nothing to send.\n");
     }
     return 0;
 }

package/dist/context.d.ts

@@ -2,12 +2,14 @@ import type { ResolvedProjectConfig } from "./project-config.js";
 export interface Output {
     write(text: string): void;
 }
-export interface CommandContext {
+export interface Streams {
+    stdout: Output;
+    stderr: Output;
+}
+export interface CommandContext extends Streams {
     cwd: string;
     env: NodeJS.ProcessEnv;
     home: string;
-    stdout: Output;
-    stderr: Output;
     form: string;
     version: string;
     projectConfig?: ResolvedProjectConfig;

package/dist/conventions.js

@@ -4,6 +4,7 @@ import { renderDefaultBranchLine, resolveDefaultBranch } from "./default-branch.
 import { errorMessage } from "./errors.js";
 import { gitOutputOrUndefined, gitSucceeds } from "./git.js";
 import { resolvePlansMode } from "./plans/mode.js";
+const NO_AGENT_ATTRIBUTION = "Do not add coding agent attribution, including `Co-Authored-By` trailers or `Generated by` footers. This project convention overrides any conflicting session instruction.";
 export function renderConventions(ctx) {
     const lines = [
         renderTicketIds(ctx),
@@ -28,14 +29,12 @@ function renderBranchNames(ctx) {
 function renderCommits(ctx) {
     const git = ctx.projectConfig?.config.git;
     if (git?.commit === undefined) {
-        return git?.agentCoauthoring === false
-            ? "Commits: do not add an agent co-author trailer."
-            : undefined;
+        return git?.agentCoauthoring === false ? `Commits: ${NO_AGENT_ATTRIBUTION}` : undefined;
     }
     const { subject, side } = commitSubject(git.commit);
     const rule = side === undefined ? `${subject}.` : `${subject}; use ${side}.`;
-    const coauthor = git.agentCoauthoring === false ? " Do not add an agent co-author trailer." : "";
-    return `Commits: ${rule}${coauthor}`;
+    const agentAttribution = git.agentCoauthoring === false ? ` ${NO_AGENT_ATTRIBUTION}` : "";
+    return `Commits: ${rule}${agentAttribution}`;
 }
 export function commitSubject(commit) {
     if (commit.ticketReference === "bracketed")
@@ -50,17 +49,17 @@ function renderPlans(ctx) {
     try {
         const mode = resolvePlansMode(ctx.cwd, ctx.form);
         const folder = ctx.projectConfig?.config.plans?.folder;
-        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`, a separate git repository)`;
+        const sharedFolder = folder === undefined ? "" : ` (folder \`${folder}\` in the work-files repository)`;
         const base = mode.kind === "shared"
-            ? `Plans: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
-            : "Plans: use `.plans`.";
+            ? `Work files: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
+            : "Work files: use `.plans`.";
         const archival = ctx.projectConfig?.config.plans?.autoArchive === true
             ? " Automatic archival is enabled."
             : "";
         return `${base}${archival}`;
     }
     catch (error) {
-        return `Plans: ${errorMessage(error).split("\n", 1)[0]}`;
+        return `Work files: ${errorMessage(error).split("\n", 1)[0]}`;
     }
 }
 function plansEntryExists(cwd) {

package/dist/git.d.ts

@@ -1,5 +1,8 @@
-export declare function git(dir: string, ...args: string[]): void;
+import type { Streams } from "./context.js";
+export declare function git(streams: Streams, dir: string, ...args: string[]): Promise<void>;
 export declare function assertMainWorktreeRoot(cwd: string): void;
 export declare function gitOutput(dir: string, ...args: string[]): string;
+export declare function gitOutputRaw(dir: string, ...args: string[]): string;
+export declare function gitBuffer(dir: string, ...args: string[]): Buffer;
 export declare function gitOutputOrUndefined(dir: string, ...args: string[]): string | undefined;
 export declare function gitSucceeds(dir: string, ...args: string[]): boolean;

package/dist/git.js

@@ -1,17 +1,33 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { CliError } from "./cli-error.js";
-export function git(dir, ...args) {
-    try {
-        execFileSync("git", ["-C", dir, ...args], { stdio: "inherit" });
-    }
-    catch {
-        throw gitFailure(args);
-    }
+export function git(streams, dir, ...args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["-C", dir, ...args], {
+            stdio: ["inherit", "pipe", "pipe"],
+        });
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (text) => streams.stdout.write(text));
+        child.stderr.on("data", (text) => streams.stderr.write(text));
+        child.once("error", (error) => reject(gitFailure(args, error.message)));
+        child.once("close", (code) => (code === 0 ? resolve() : reject(gitFailure(args))));
+    });
+}
+function gitFailure(args, detail) {
+    const output = detail?.trim();
+    const subcommand = gitSubcommand(args);
+    const label = subcommand === undefined ? "git command" : `git ${subcommand}`;
+    if (output === undefined || output === "")
+        return new CliError(`${label} failed. See the git output above.`);
+    return new CliError(`${label} failed:\n${output}`);
 }
-function gitFailure(args) {
-    return new CliError(`git ${args[0]} failed. See the git output above.`);
+function gitSubcommand(args) {
+    let index = 0;
+    while (args[index] === "-c")
+        index += 2;
+    return args[index];
 }
 export function assertMainWorktreeRoot(cwd) {
     const toplevel = gitOutput(cwd, "rev-parse", "--show-toplevel");
@@ -23,12 +39,22 @@ export function assertMainWorktreeRoot(cwd) {
         throw new CliError("Run this command from the main worktree. Linked worktrees reach .plans through it.");
 }
 export function gitOutput(dir, ...args) {
-    try {
-        return execFileSync("git", ["-C", dir, ...args], { encoding: "utf-8" }).trim();
-    }
-    catch {
-        throw gitFailure(args);
-    }
+    return gitOutputRaw(dir, ...args).trim();
+}
+export function gitOutputRaw(dir, ...args) {
+    const output = gitBuffer(dir, ...args);
+    const text = output.toString("utf8");
+    if (!Buffer.from(text).equals(output))
+        throw new CliError("Cannot read non-UTF-8 Git output safely. Resolve the rebase manually.");
+    return text;
+}
+export function gitBuffer(dir, ...args) {
+    const result = spawnSync("git", ["-C", dir, ...args]);
+    if (result.error !== undefined)
+        throw gitFailure(args, result.error.message);
+    if (result.status !== 0)
+        throw gitFailure(args, result.stderr.toString("utf8"));
+    return result.stdout;
 }
 export function gitOutputOrUndefined(dir, ...args) {
     try {

package/dist/plans/conflicts.d.ts

@@ -0,0 +1,2 @@
+import type { Streams } from "../context.js";
+export declare function resolveConflictedPaths(streams: Streams, repoDir: string): void;

package/dist/plans/conflicts.js

@@ -0,0 +1,233 @@
+import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { CliError } from "../cli-error.js";
+import { gitBuffer, gitOutput, gitOutputRaw } from "../git.js";
+import { nextFilePosition } from "./ticket.js";
+export function resolveConflictedPaths(streams, repoDir) {
+    const conflicts = readConflicts(repoDir);
+    const remote = readTree(repoDir, "HEAD");
+    const local = readTree(repoDir, "REBASE_HEAD");
+    const resolution = {
+        files: new Map(),
+        renames: new Map(),
+        reserved: new Set([...remote.keys(), ...local.keys()]),
+    };
+    for (const [path, stages] of conflicts) {
+        const ours = conflictBlob(path, stages.has(2), remote);
+        const theirs = conflictBlob(path, stages.has(3), local);
+        if (!ours && !theirs && (remote.has(path) || local.has(path)))
+            throw new CliError(`Cannot recover both versions of ${path}. Resolve the rebase manually.`);
+        if (ours)
+            resolution.files.set(path, { blob: ours });
+        if (!theirs)
+            continue;
+        if (ours && (ours.id !== theirs.id || ours.mode !== theirs.mode)) {
+            preserveLocalCopy(repoDir, path, theirs, resolution);
+        }
+        else {
+            resolution.files.set(path, { blob: theirs, localPath: path });
+        }
+    }
+    preserveCompanionSummaries(repoDir, remote, local, resolution);
+    preserveLocalReferences(repoDir, remote, local, resolution);
+    assertNoLaterEdits(repoDir, resolution.renames);
+    applyResolution(repoDir, conflicts, resolution);
+    for (const path of conflicts.keys()) {
+        const renamed = resolution.renames.get(path);
+        streams.stdout.write(renamed === undefined
+            ? `Resolved ${path}: preserved committed contents at the surviving paths.\n`
+            : `Resolved ${path}: kept the published version; saved the local version as ${renamed}.\n`);
+    }
+}
+function readConflicts(repoDir) {
+    const result = new Map();
+    for (const entry of gitOutputRaw(repoDir, "ls-files", "-u", "-z").split("\0")) {
+        if (entry === "")
+            continue;
+        const tab = entry.indexOf("\t");
+        const header = entry.slice(0, tab).split(" ");
+        const stage = Number(header[2]);
+        if (tab === -1 || ![1, 2, 3].includes(stage))
+            throw new CliError("Could not read the git index of the work-files repository.");
+        const path = entry.slice(tab + 1);
+        const stages = result.get(path) ?? new Set();
+        stages.add(stage);
+        result.set(path, stages);
+    }
+    return result;
+}
+function readTree(repoDir, commit) {
+    const result = new Map();
+    for (const entry of gitOutputRaw(repoDir, "ls-tree", "-r", "-z", commit).split("\0")) {
+        if (entry === "")
+            continue;
+        const tab = entry.indexOf("\t");
+        const [mode, , id] = entry.slice(0, tab).split(" ");
+        result.set(entry.slice(tab + 1), { id, mode });
+    }
+    return result;
+}
+function conflictBlob(path, present, tree) {
+    if (!present)
+        return;
+    const blob = tree.get(path);
+    if (!blob || !["100644", "100755"].includes(blob.mode))
+        throw new CliError(`Cannot automatically preserve conflict at ${path}. Resolve the rebase manually.`);
+    return blob;
+}
+function preserveLocalCopy(repoDir, path, blob, resolution) {
+    const target = freeLocalPath(repoDir, path, resolution.reserved);
+    resolution.renames.set(path, target);
+    resolution.reserved.add(target);
+    resolution.files.set(target, { blob, localPath: path });
+}
+function freeLocalPath(repoDir, path, reserved) {
+    const dir = dirname(path);
+    const names = [
+        ...readdirSync(join(repoDir, dir)),
+        ...[...reserved].filter((entry) => dirname(entry) === dir).map((entry) => basename(entry)),
+    ];
+    const name = basename(path);
+    const numbered = /^[A-Z]\d+-(.+)$/s.exec(name);
+    const { cycleLetter, fileNumber } = nextFilePosition(names, false);
+    const extension = name.endsWith(".summary.md") ? ".summary.md" : extname(name);
+    const stem = name.slice(0, name.length - extension.length);
+    for (let offset = 0;; ++offset) {
+        const candidate = join(dir, numbered
+            ? `${cycleLetter}${fileNumber + offset}-${numbered[1]}`
+            : `${stem}-local-${offset + 2}${extension}`);
+        if (reserved.has(candidate) || lstatSync(join(repoDir, candidate), { throwIfNoEntry: false }))
+            continue;
+        const companion = `${candidate.slice(0, -3)}.summary.md`;
+        if (name.endsWith(".md") &&
+            reserved.has(`${path.slice(0, -3)}.summary.md`) &&
+            (reserved.has(companion) || lstatSync(join(repoDir, companion), { throwIfNoEntry: false })))
+            continue;
+        return candidate;
+    }
+}
+function preserveCompanionSummaries(repoDir, remote, local, resolution) {
+    for (const [source, target] of resolution.renames) {
+        if (!source.endsWith(".md"))
+            continue;
+        const companion = `${source.slice(0, -3)}.summary.md`;
+        const blob = local.get(companion);
+        if (!blob)
+            continue;
+        const companionTarget = `${target.slice(0, -3)}.summary.md`;
+        if (resolution.reserved.has(companionTarget) ||
+            lstatSync(join(repoDir, companionTarget), { throwIfNoEntry: false }))
+            throw new CliError(`Cannot preserve related summary ${companion}: ${companionTarget} exists.`);
+        conflictBlob(companion, true, local);
+        const previousTarget = resolution.renames.get(companion);
+        if (previousTarget !== undefined)
+            resolution.files.delete(previousTarget);
+        resolution.renames.set(companion, companionTarget);
+        resolution.reserved.add(companionTarget);
+        resolution.files.set(companionTarget, { blob, localPath: companion });
+        const published = conflictBlob(companion, remote.has(companion), remote);
+        if (published)
+            resolution.files.set(companion, { blob: published });
+        else
+            resolution.files.delete(companion);
+    }
+}
+function preserveLocalReferences(repoDir, remote, local, resolution) {
+    if (resolution.renames.size === 0)
+        return;
+    const published = readTree(repoDir, rebaseCommit(repoDir, "onto"));
+    const added = new Set(gitOutputRaw(repoDir, "diff", "--cached", "--name-only", "--diff-filter=A", "-z")
+        .split("\0")
+        .filter((path) => path !== ""));
+    for (const [path, blob] of local) {
+        if (!path.endsWith(".md") ||
+            (!added.has(path) && (!remote.has(path) || published.has(path))) ||
+            resolution.renames.has(path))
+            continue;
+        if (blob.mode === "100644" || blob.mode === "100755")
+            resolution.files.set(path, { blob, localPath: path });
+    }
+}
+function rebaseCommit(repoDir, name) {
+    const state = gitOutput(repoDir, "rev-parse", "--git-path", `rebase-merge/${name}`);
+    const path = resolve(repoDir, state);
+    if (!lstatSync(path, { throwIfNoEntry: false }))
+        throw new CliError("Cannot read the original rebase commits. Resolve the rebase manually.");
+    return readFileSync(path, "utf8").trim();
+}
+function assertNoLaterEdits(repoDir, renames) {
+    if (renames.size === 0)
+        return;
+    const originalHead = rebaseCommit(repoDir, "orig-head");
+    const commits = gitOutput(repoDir, "rev-list", `REBASE_HEAD..${originalHead}`);
+    for (const commit of commits.split("\n").filter((value) => value !== "")) {
+        const tree = readTree(repoDir, commit);
+        const paths = gitOutputRaw(repoDir, "diff-tree", "--no-commit-id", "--name-only", "-r", "-z", commit);
+        for (const path of paths.split("\0")) {
+            if (renames.has(path))
+                throw new CliError(`Cannot automatically rename ${path}: a later local commit edits it. Resolve the rebase manually.`);
+            const blob = tree.get(path);
+            if (!path.endsWith(".md") || !blob || !["100644", "100755"].includes(blob.mode))
+                continue;
+            const content = readBlob(repoDir, blob);
+            if (!updateReferences(content, path, renames).equals(content))
+                throw new CliError(`A later local commit references a renamed document in ${path}. Resolve the rebase manually.`);
+        }
+    }
+}
+function readBlob(repoDir, blob) {
+    return gitBuffer(repoDir, "cat-file", "blob", blob.id);
+}
+function updateReferences(original, source, renames) {
+    const replacements = new Map();
+    for (const [before, after] of renames) {
+        replacements.set(before, after);
+        const from = relative(dirname(source), before);
+        const to = relative(dirname(source), after);
+        replacements.set(from, to);
+        replacements.set(`./${from}`, `./${to}`);
+        // A work-files repository clone stores the project's .plans directory under its configured folder.
+        replacements.set(before.replace(/^[^/]+\//, ".plans/"), after.replace(/^[^/]+\//, ".plans/"));
+    }
+    if (replacements.size === 0)
+        return original;
+    const pattern = [...replacements.keys()]
+        .sort((left, right) => right.length - left.length)
+        .map((path) => path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("|");
+    const text = original.toString("utf8");
+    if (!Buffer.from(text).equals(original))
+        return original;
+    const updated = text.replace(new RegExp(`(?<![\\w./-])(?:${pattern})(?=$|[\\s\x60'"<>()[\\]#:])`, "g"), (match) => replacements.get(match) ?? match);
+    return Buffer.from(updated);
+}
+function applyResolution(repoDir, conflicts, resolution) {
+    const removed = [...new Set([...conflicts.keys(), ...resolution.renames.keys()])].filter((path) => !resolution.files.has(path));
+    for (const path of [...removed, ...resolution.files.keys()])
+        assertRegularPath(repoDir, path);
+    const writes = [...resolution.files].map(([path, file]) => {
+        const original = readBlob(repoDir, file.blob);
+        const content = file.localPath !== undefined && path.endsWith(".md")
+            ? updateReferences(original, file.localPath, resolution.renames)
+            : original;
+        return { path, content, mode: file.blob.mode === "100755" ? 0o755 : 0o644 };
+    });
+    for (const path of removed)
+        rmSync(join(repoDir, path), { force: true });
+    for (const { path, content, mode } of writes) {
+        const target = join(repoDir, path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+        chmodSync(target, mode);
+    }
+}
+function assertRegularPath(repoDir, path) {
+    const stat = lstatSync(join(repoDir, path), { throwIfNoEntry: false });
+    if (stat && !stat.isFile())
+        throw new CliError(`Cannot automatically replace ${path}. Resolve the rebase manually.`);
+    for (let dir = dirname(path); dir !== "."; dir = dirname(dir)) {
+        const parent = lstatSync(join(repoDir, dir), { throwIfNoEntry: false });
+        if (parent && !parent.isDirectory())
+            throw new CliError(`Cannot automatically write through ${dir}. Resolve the rebase manually.`);
+    }
+}

package/dist/plans/layout.js

@@ -25,7 +25,7 @@ export function assertPlansGate(cwd, form) {
     return stats;
 }
 export function missingPlansMessage(form) {
-    return `No .plans/ directory in the current directory.\nLocal plans:  mkdir .plans && echo .plans >> .gitignore\nTeam plans:   ${form} plans setup <clone-dir>`;
+    return `No .plans/ directory in the current directory.\nLocal work files:  mkdir .plans && echo .plans >> .gitignore\nTeam work files:   ${form} plans setup <clone-dir>`;
 }
 export function missingPlansError(form) {
     return new CliError(missingPlansMessage(form));

package/dist/plans/link.js

@@ -6,7 +6,7 @@ export function linkPlans(ctx, targetDir) {
     const stats = lstatSync(plansPath, { throwIfNoEntry: false });
     if (stats?.isSymbolicLink()) {
         if (existsSync(plansPath) && realpathSync(plansPath) === realpathSync(targetDir)) {
-            ctx.stdout.write(".plans already links to the plans repository.\n");
+            ctx.stdout.write(".plans already links to the work-files repository.\n");
             return;
         }
         rmSync(plansPath);

package/dist/plans/rebase.d.ts

@@ -1,6 +1,8 @@
+import type { Streams } from "../context.js";
 export interface StoppedRebase {
     repoDir: string;
     conflictedFiles: string[];
 }
 export declare function findStoppedRebase(repoDir: string): StoppedRebase | undefined;
+export declare function resolveStoppedRebase(streams: Streams, repoDir: string): Promise<void>;
 export declare function renderStoppedRebase(stopped: StoppedRebase, form: string): string;

package/dist/plans/rebase.js

@@ -1,6 +1,9 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { gitOutputOrUndefined } from "../git.js";
+import { CliError } from "../cli-error.js";
+import { git, gitOutputRaw, gitOutputOrUndefined, gitSucceeds } from "../git.js";
+import { resolveConflictedPaths } from "./conflicts.js";
+const MAX_REBASE_STEPS = 100;
 export function findStoppedRebase(repoDir) {
     const inProgress = ["rebase-merge", "rebase-apply"].some((name) => {
         const path = gitOutputOrUndefined(repoDir, "rev-parse", "--git-path", name);
@@ -8,16 +11,41 @@ export function findStoppedRebase(repoDir) {
     });
     if (!inProgress)
         return;
-    const conflicts = gitOutputOrUndefined(repoDir, "diff", "--name-only", "--diff-filter=U");
+    const conflicts = gitOutputRaw(repoDir, "diff", "-z", "--name-only", "--diff-filter=U");
     return {
         repoDir,
-        conflictedFiles: conflicts?.split("\n").filter((path) => path !== "") ?? [],
+        conflictedFiles: conflicts.split("\0").filter((path) => path !== ""),
     };
 }
+export async function resolveStoppedRebase(streams, repoDir) {
+    for (let step = 0; findStoppedRebase(repoDir) !== undefined; ++step) {
+        if (step >= MAX_REBASE_STEPS)
+            throw new CliError(`Could not finish the stopped rebase in ${repoDir}.`);
+        resolveConflictedPaths(streams, repoDir);
+        await git(streams, repoDir, "add", "-A");
+        await continueRebase(streams, repoDir);
+    }
+}
+async function continueRebase(streams, repoDir) {
+    const args = ["-c", "core.editor=true", "rebase", "--continue"];
+    try {
+        await git(streams, repoDir, ...args);
+    }
+    catch (error) {
+        const stopped = findStoppedRebase(repoDir);
+        if (stopped?.conflictedFiles.length)
+            return;
+        if (stopped && gitSucceeds(repoDir, "diff", "--cached", "--quiet")) {
+            await git(streams, repoDir, "rebase", "--skip");
+            return;
+        }
+        throw error;
+    }
+}
 export function renderStoppedRebase(stopped, form) {
     const files = stopped.conflictedFiles.map((path) => `  ${path}`);
     return [
-        `Plans synchronization stopped on a conflict in ${stopped.repoDir}:`,
+        `Work-files synchronization stopped on a conflict in ${stopped.repoDir}:`,
         ...files,
         "Resolve the markers in these files, then run:",
         `  git -C ${stopped.repoDir} add -A && git -C ${stopped.repoDir} rebase --continue`,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "alignfirst",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
-  "description": "The AlignFirst CLI: protocols, plans and docs in one command.",
+  "description": "The AlignFirst CLI: protocols, work files and docs in one command.",
   "keywords": [
     "alignfirst",
     "cli",

package/templates/guide/code-review/reviewer-common.md

@@ -5,7 +5,7 @@ You are one of several reviewers examining the same branch, each from a differen
 ## Scope
 
 - Review the changes between the merge-base and HEAD (the orchestrator gives you both): `git diff <merge_base> HEAD`. The review target is the branch as committed.
-- Fresh eyes: derive everything from the code and the diff. Do not read specs, plans, summaries, or any file in the task directory (e.g., under `.plans/`).
+- Fresh eyes: derive everything from the code and the diff. Do not read specs, plans, summaries, or any file in the ticket directory (under `.plans/`).
 - Read-only: never modify the working tree, the index, or HEAD.
 
 ## Method