alignfirst 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -1,6 +1,8 @@
 # alignfirst
 
-The AlignFirst CLI provides protocols, shared plans and project documentation in one command.
+The AlignFirst CLI provides collaborative software-development workflows, task files, shared plans, project conventions, documentation discovery, and setup diagnostics.
+
+## Installation
 
 Install it globally:
 
@@ -11,21 +13,92 @@ npm install -g alignfirst
 Or run the current version without installing it:
 
 ```sh
-npx -y alignfirst
+npx alignfirst
+```
+
+## Setup with your agent
+
+Temporarily install the setup-guide skill:
+
+```sh
+npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guide
+```
+
+Then ask your agent:
+
+```text
+Use your alignfirst-setup-guide skill. Set up AlignFirst in this project. Ask before installing anything globally.
 ```
 
-Commands:
+The guide installs the selected components and configures the repository. Remove the setup-guide skill when setup is complete.
+
+## Commands
 
 - `guide` — Print an AlignFirst protocol.
 - `ticket` — Resolve a ticket directory and its next file.
 - `sync` — Synchronize shared plans.
 - `plans` — Set up, check and archive plans.
 - `docmap` — Browse project documentation.
+- `conventions` — Print the effective project conventions.
+- `context` — Print the conventions and the documentation map.
 - `config` — Report the effective project configuration.
-- `DEVELOPERS.md` — Print the project developer guide.
-- `setup` — Prepare an AlignFirst project.
 - `doctor` — Diagnose an AlignFirst setup.
 
 Run `alignfirst --help` for command usage or `alignfirst guide` for the collaboration guide.
 
-`@paleo/alcode` is the companion CLI for the AlignFirst Developer.
+## Agent skills
+
+Eight optional Agent Skill stubs expose the CLI to GitHub Copilot, Cursor, Claude Code, and Codex. The skills contain no protocols; they invoke `npx alignfirst guide`.
+
+Install them globally:
+
+```sh
+npx skills add https://github.com/paleo/alignfirst --global \
+  --skill alignfirst --skill al --skill alplan --skill alspec \
+  --skill aldescription --skill alreview --skill alcatchup --skill almerge
+```
+
+Restart the agent after installation. Claude Code, GitHub Copilot, and Cursor expose skills with `/`; Codex uses `$`.
+
+## Workflows
+
+These examples use the `/` form. Replace it with `$` in Codex.
+
+| Workflow | Command | Result |
+| --- | --- | --- |
+| Specification | `/alspec <request>` | Discuss and write a technical specification. |
+| Planning | `/alplan` | Turn a specification into one or more implementation plans. |
+| Align and do | `/al <request>` | Discuss and implement a small change, then write a summary. |
+| Description | `/aldescription` | Summarize the work and propose a commit message. |
+| Review | `/alreview` | Review the current branch against its base. |
+| Merge | `/almerge` | Resolve merge or rebase conflicts. |
+| Catch up | `/alcatchup` | Load the current task history and continue. |
+
+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`.
+
+## Updates
+
+```sh
+npm update -g alignfirst
+npx skills update --global --yes
+```
+
+## Upgrade from v1, v2, or v3
+
+Install the setup-guide skill and ask your agent to run its upgrade route:
+
+```sh
+npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guide
+```
+
+```text
+Use your alignfirst-setup-guide skill. Upgrade AlignFirst in this project.
+```
+
+_Note: the setup-guide skill can be removed safely after it's done._
+
+## License
+
+CC0 1.0 Universal.

package/dist/cli.js

@@ -3,15 +3,15 @@ import { homedir } from "node:os";
 import { CliError } from "./cli-error.js";
 import { resolveCommandForm } from "./command-form.js";
 import { runConfig } from "./commands/config.js";
-import { runDevelopers } from "./commands/developers.js";
+import { runContext } from "./commands/context.js";
+import { runConventions } from "./commands/conventions.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runDocmap } from "./commands/docmap.js";
 import { runGuide } from "./commands/guide.js";
 import { runPlans } from "./commands/plans.js";
-import { runSetup } from "./commands/setup.js";
 import { runSync } from "./commands/sync.js";
 import { runTicket } from "./commands/ticket.js";
-import { resolveProjectConfig } from "./overlay.js";
+import { resolveProjectConfig } from "./project-config.js";
 import { checkCliRange } from "./version-guard.js";
 export async function main(options) {
     const argv = options?.argv ?? process.argv;
@@ -36,8 +36,7 @@ export async function main(options) {
             return 0;
         }
         if (command !== "config" && command !== "doctor") {
-            ctx.projectConfig = resolveProjectConfig(ctx.cwd, ctx.env, ctx.home);
-            ctx.overlay = ctx.projectConfig?.overlay;
+            ctx.projectConfig = resolveProjectConfig(ctx.cwd);
             checkCliRange(ctx.projectConfig?.config, ctx.version, [command, ...args]);
         }
         return dispatch(ctx, command, args);
@@ -61,12 +60,12 @@ function renderHelp(ctx) {
 Usage:
   ${ctx.form} guide [<protocol>]
   ${ctx.form} ticket [<id>]
-  ${ctx.form} sync [--auto-archive]
+  ${ctx.form} sync [--auto-archive | --no-auto-archive]
   ${ctx.form} plans <command>
   ${ctx.form} docmap [<arguments>]
+  ${ctx.form} conventions
+  ${ctx.form} context
   ${ctx.form} config [--json]
-  ${ctx.form} DEVELOPERS.md
-  ${ctx.form} setup [<options>]
   ${ctx.form} doctor
   ${ctx.form} --help
   ${ctx.form} --version
@@ -84,12 +83,12 @@ function dispatch(ctx, command, args) {
             return runPlans(ctx, args);
         case "docmap":
             return runDocmap(ctx, args);
+        case "conventions":
+            return runConventions(ctx, args);
+        case "context":
+            return runContext(ctx, args);
         case "config":
             return runConfig(ctx, args);
-        case "DEVELOPERS.md":
-            return runDevelopers(ctx, args);
-        case "setup":
-            return runSetup(ctx, args);
         case "doctor":
             return runDoctor(ctx, args);
         default:

package/dist/commands/config.js

@@ -1,14 +1,14 @@
 import { CliError } from "../cli-error.js";
 import { parseArgs } from "node:util";
-import { resolveProjectConfig } from "../overlay.js";
 import { parseCommandArgs } from "../parse-args.js";
+import { resolveProjectConfig } from "../project-config.js";
 import { cliRangeResult } from "../version-guard.js";
 export function runConfig(ctx, args) {
     const usage = `Usage: ${ctx.form} config [--json]\n`;
     const json = parseConfigArgs(ctx, args, usage);
     if (json === undefined)
         return 0;
-    const resolved = resolveProjectConfig(ctx.cwd, ctx.env, ctx.home);
+    const resolved = resolveProjectConfig(ctx.cwd);
     const report = buildConfigReport(ctx, resolved);
     ctx.stdout.write(json ? `${JSON.stringify(report, undefined, 2)}\n` : renderConfigReport(report));
     return 0;
@@ -32,19 +32,15 @@ function parseConfigArgs(ctx, args, usage) {
     return values.json;
 }
 function buildConfigReport(ctx, resolved) {
-    const overlay = resolved?.overlay;
     const cli = cliRangeResult(resolved?.config, ctx.version);
     return {
         source: resolved?.source ?? null,
-        overlay: overlay ? { dir: overlay.dir, matchedBy: overlay.matchedBy } : null,
         cli: cli ? { installed: ctx.version, range: cli.range, satisfied: cli.satisfied } : null,
         config: resolved?.config ?? null,
     };
 }
 function renderConfigReport(report) {
     const lines = [`Source: ${report.source ?? "none"}`];
-    if (report.overlay)
-        lines.push(`Overlay: ${report.overlay.dir} (matched by ${report.overlay.matchedBy})`);
     if (report.cli)
         lines.push(`CLI range: ${report.cli.range}, ${report.cli.satisfied ? "satisfied" : "not satisfied"} by ${report.cli.installed}`);
     else

package/dist/commands/context.d.ts

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

package/dist/commands/context.js

@@ -0,0 +1,11 @@
+import { renderConventions } from "../conventions.js";
+import { parseBareCommandArgs } from "../parse-args.js";
+import { runDocmap } from "./docmap.js";
+export function runContext(ctx, args) {
+    const usage = `Usage: ${ctx.form} context\n`;
+    if (parseBareCommandArgs(ctx, args, usage))
+        return 0;
+    ctx.stdout.write(renderConventions(ctx));
+    ctx.stdout.write("\n");
+    return runDocmap(ctx, []);
+}

package/dist/commands/conventions.d.ts

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

package/dist/commands/conventions.js

@@ -0,0 +1,9 @@
+import { renderConventions } from "../conventions.js";
+import { parseBareCommandArgs } from "../parse-args.js";
+export function runConventions(ctx, args) {
+    const usage = `Usage: ${ctx.form} conventions\n`;
+    if (parseBareCommandArgs(ctx, args, usage))
+        return 0;
+    ctx.stdout.write(renderConventions(ctx));
+    return 0;
+}

package/dist/commands/docmap.js

@@ -1,22 +1,10 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { main as docmapMain } from "@paleo/docmap";
-import { resolveProjectFile } from "../overlay.js";
 export function runDocmap(ctx, args) {
-    const docmapArgs = withOverlayRoot(ctx, args);
     return docmapMain({
-        argv: ["node", "docmap", ...docmapArgs],
+        argv: ["node", "docmap", ...args],
         cwd: ctx.cwd,
         stdout: ctx.stdout,
         stderr: ctx.stderr,
         commands: { base: `${ctx.form} docmap`, withArgs: `${ctx.form} docmap` },
     });
 }
-function withOverlayRoot(ctx, args) {
-    if (args.includes("--root") || existsSync(join(ctx.cwd, "docs")))
-        return args;
-    const docs = resolveProjectFile(ctx.cwd, ctx.overlay, "docs");
-    if (docs?.source !== "overlay")
-        return args;
-    return [...args, "--root", docs.path];
-}

package/dist/commands/doctor.js

@@ -1,45 +1,35 @@
 import { execFileSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseArgs } from "node:util";
 import semver from "semver";
-import { CliError } from "../cli-error.js";
+import { resolveDefaultBranch } from "../default-branch.js";
 import { errorMessage } from "../errors.js";
 import { findExecutable } from "../executables.js";
-import { findOverlay, resolveProjectConfig, resolveProjectFile, } from "../overlay.js";
-import { parseCommandArgs } from "../parse-args.js";
+import { parseBareCommandArgs } from "../parse-args.js";
 import { resolvePlansMode } from "../plans/mode.js";
+import { findStoppedRebase } from "../plans/rebase.js";
+import { resolveProjectConfig } from "../project-config.js";
 import { findInstalledSkill, STUB_SKILLS } from "../skills.js";
 import { cliRangeResult } from "../version-guard.js";
-const PROJECT_CONFIG_NAME = ".alignfirst.json";
 export function runDoctor(ctx, args) {
     const usage = `Usage: ${ctx.form} doctor\n`;
-    if (parseDoctorArgs(ctx, args, usage))
+    if (parseBareCommandArgs(ctx, args, usage))
         return 0;
     writeSection(ctx, "CLI", () => inspectCli(ctx));
-    writeSection(ctx, "Config", () => inspectConfig(ctx));
+    let resolved;
+    writeSection(ctx, "Config", () => {
+        resolved = resolveProjectConfig(ctx.cwd);
+        return inspectConfig(ctx, resolved);
+    });
+    writeSection(ctx, "Git", () => inspectGit(ctx, resolved));
     writeSection(ctx, "Plans", () => inspectPlans(ctx));
     writeSection(ctx, "Docmap", () => inspectDocmap(ctx));
     writeSection(ctx, "Skills", () => inspectSkills(ctx));
-    writeSection(ctx, "Overlay", () => inspectOverlay(ctx));
     writeSection(ctx, "Companion", () => inspectCompanion(ctx));
     return 0;
 }
-function parseDoctorArgs(ctx, args, usage) {
-    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
-        args,
-        options: { help: { type: "boolean", short: "h", default: false } },
-        strict: true,
-        allowPositionals: true,
-    }));
-    if (positionals.length > 0)
-        throw new CliError(`Unexpected argument: ${positionals[0]}\n\n${usage}`);
-    if (!values.help)
-        return false;
-    ctx.stdout.write(usage);
-    return true;
-}
 function writeSection(ctx, section, inspect) {
     let lines;
     try {
@@ -63,9 +53,8 @@ function inspectCli(ctx) {
         },
     ];
 }
-function inspectConfig(ctx) {
-    const resolved = resolveProjectConfig(ctx.cwd, ctx.env, ctx.home);
-    const lines = [{ level: "ok", text: `source ${configSource(resolved)}` }];
+function inspectConfig(ctx, resolved) {
+    const lines = [{ level: "ok", text: resolved?.source ?? "none" }];
     const result = cliRangeResult(resolved?.config, ctx.version);
     if (result === undefined) {
         lines.push({ level: "ok", text: "no cli range" });
@@ -79,13 +68,17 @@ function inspectConfig(ctx) {
         lines.push({ level: "warn", text: `${ctx.version} is ahead of ${result.range}` });
     return lines;
 }
-function configSource(resolved) {
-    if (resolved === undefined)
-        return "none";
-    return resolved.source === "root" ? "root" : (resolved.overlay?.dir ?? "overlay");
+function inspectGit(ctx, resolved) {
+    const branch = resolveDefaultBranch(ctx.cwd, resolved?.config);
+    if (branch === undefined)
+        return [{ level: "warn", text: "default branch unresolved" }];
+    const source = branch.source === "config" ? "git.defaultBranch" : `cached ${branch.remote}/HEAD`;
+    return [{ level: "ok", text: `default branch ${branch.name} (${source})` }];
 }
 function inspectPlans(ctx) {
     const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    if (mode.kind === "shared" && findStoppedRebase(mode.repoToplevel) !== undefined)
+        return [{ level: "error", text: `rebase stopped on a conflict in ${mode.repoToplevel}` }];
     return [
         {
             level: "ok",
@@ -94,11 +87,9 @@ function inspectPlans(ctx) {
     ];
 }
 function inspectDocmap(ctx) {
-    const overlay = findOverlay(ctx.cwd, ctx.env, ctx.home);
-    const docs = resolveProjectFile(ctx.cwd, overlay, "docs");
-    const source = docs?.source ?? "none";
+    const present = existsSync(join(ctx.cwd, "docs"));
     return [
-        { level: docs === undefined ? "warn" : "ok", text: `docs/ source ${source}` },
+        { level: "ok", text: `docs/ ${present ? "present" : "none"}` },
         { level: "ok", text: `embedded docmap ${readDocmapVersion()}` },
     ];
 }
@@ -117,29 +108,16 @@ function inspectSkills(ctx) {
         const installed = findInstalledSkill(ctx.home, name);
         if (installed === undefined)
             return { level: "warn", text: `${name} missing` };
-        return {
-            level: "ok",
-            text: `${name} ${installed.version ?? "unknown"} (${installed.root})`,
-        };
+        const version = installed.version ?? "unknown";
+        const parsed = semver.parse(installed.version);
+        if (parsed === null || parsed.major < 4)
+            return {
+                level: "warn",
+                text: `${name} ${version} predates v4; update: npx -y skills update --global --yes`,
+            };
+        return { level: "ok", text: `${name} ${version} (${installed.root})` };
     });
 }
-function inspectOverlay(ctx) {
-    const configured = ctx.env.ALIGNFIRST_OVERLAYS;
-    if (configured === undefined || configured === "")
-        return [{ level: "ok", text: "no overlays directory" }];
-    const overlay = findOverlay(ctx.cwd, ctx.env, ctx.home);
-    if (overlay === undefined)
-        return [{ level: "ok", text: "no overlay matches" }];
-    const lines = [
-        { level: "ok", text: `${overlay.dir} (matched by ${overlay.matchedBy})` },
-    ];
-    for (const name of [PROJECT_CONFIG_NAME, "AGENTS.md", "DEVELOPERS.md", "docs"])
-        lines.push({
-            level: "ok",
-            text: `${name} ${resolveProjectFile(ctx.cwd, overlay, name)?.source ?? "none"}`,
-        });
-    return lines;
-}
 function inspectCompanion(ctx) {
     const executable = findExecutable(ctx.env, "alcode");
     if (executable === undefined)

package/dist/commands/guide.js

@@ -1,11 +1,20 @@
-import { readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
 import { renderCommandForm } from "../command-form.js";
-import { resolveProjectFile } from "../overlay.js";
+import { commitSubject, renderConventions } from "../conventions.js";
+import { resolveDefaultBranch } from "../default-branch.js";
 import { parseCommandArgs } from "../parse-args.js";
+import { missingPlansMessage } from "../plans/layout.js";
+import { resolvePlansMode } from "../plans/mode.js";
+import { detectTicketFromBranch } from "../plans/ticket.js";
 import { PROTOCOLS } from "../protocols.js";
-const TICKET_ID_RULE_PLACEHOLDER = "{{TICKET_ID_RULE}}";
+const TICKET_CMD_PLACEHOLDER = "{{TICKET_CMD}}";
+const TICKET_CONTEXT_PLACEHOLDER = "{{TICKET_CONTEXT}}";
+const PLANS_STATE_PLACEHOLDER = "{{PLANS_STATE}}";
+const COMMIT_RULE_PLACEHOLDER = "{{COMMIT_RULE}}";
+const BASE_BRANCH_RULE_PLACEHOLDER = "{{BASE_BRANCH_RULE}}";
 const PERSPECTIVES = ["intent", "correctness", "safety", "quality"];
 const MODULES = ["typescript-strict", "javascript", "python"];
 const PROTOCOL_LIST = `${PROTOCOLS.join(", ")}, or overview`;
@@ -88,12 +97,14 @@ function renderGuide(ctx, options) {
         return renderReviewerGuide(options.reviewer, options.modules);
     if (options.protocol === "overview")
         return readGuideTemplate("overview.md");
+    const placeholders = buildGuidePlaceholders(ctx, options.protocol);
     if (options.protocolOnly && options.protocol !== undefined)
-        return readProtocolTemplate(options.protocol);
-    const core = renderCoreGuide(ctx);
+        return applyPlaceholders(readProtocolTemplate(options.protocol), placeholders);
+    const core = renderCoreGuide(ctx, placeholders);
     if (options.protocol === undefined)
         return core;
-    return `${core.trimEnd()}\n\n${readProtocolTemplate(options.protocol).trimEnd()}`;
+    const protocol = applyPlaceholders(readProtocolTemplate(options.protocol), placeholders);
+    return `${core.trimEnd()}\n\n${protocol.trimEnd()}`;
 }
 function renderReviewerGuide(perspective, modules) {
     const templates = [
@@ -103,20 +114,73 @@ function renderReviewerGuide(perspective, modules) {
     ];
     return templates.map((template) => template.trimEnd()).join("\n\n");
 }
-function renderCoreGuide(ctx) {
-    const ticketRule = renderTicketIdRule(ctx);
-    const core = readGuideTemplate("core.md").replaceAll(TICKET_ID_RULE_PLACEHOLDER, () => ticketRule);
-    const projectConventions = resolveProjectFile(ctx.cwd, ctx.overlay, "AGENTS.md");
-    if (projectConventions?.source !== "overlay")
+function renderCoreGuide(ctx, placeholders) {
+    const core = applyPlaceholders(readGuideTemplate("core.md"), placeholders);
+    if (ctx.projectConfig !== undefined)
         return core;
-    const content = readFileSync(projectConventions.path, "utf-8").trimEnd();
-    return `${core.trimEnd()}\n\n## Project conventions\n\n${content}`;
+    return `${core.trimEnd()}\n\n## Project conventions\n\n${renderConventions(ctx).trimEnd()}`;
 }
-function renderTicketIdRule(ctx) {
-    const pattern = ctx.projectConfig?.config.ticketPattern;
+function buildGuidePlaceholders(ctx, protocol) {
+    const pattern = ctx.projectConfig?.config.ticketIdPattern;
+    const detection = pattern === undefined ? undefined : detectTicketFromBranch(ctx.cwd, pattern);
+    return {
+        ticketCommand: detection?.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
+        ticketContext: renderTicketContext(pattern, detection),
+        plansState: renderPlansState(ctx),
+        commitRule: renderCommitRule(ctx),
+        baseBranchRule: renderBaseBranchRule(ctx, protocol),
+    };
+}
+function renderTicketContext(pattern, detection) {
     if (pattern === undefined)
         return "Ask the user for the ticket ID when it is not given.";
-    return `Ticket IDs match \`${pattern}\`. When the user gives no id, run \`{{CMD}} ticket\` without an id: it deduces the id from the current branch.`;
+    if (detection?.kind === "detected")
+        return `Current ticket: \`${detection.id}\` (from branch \`${detection.branch}\`). The id argument of \`{{CMD}} ticket\` is optional and defaults to it; pass an id only when the user names another ticket.`;
+    if (detection?.kind === "noMatch")
+        return `No ticket id on branch \`${detection.branch}\`. Ask the user for the id.`;
+    return "No ticket id: detached HEAD. Ask the user for the id.";
+}
+function renderPlansState(ctx) {
+    const entry = lstatSync(join(ctx.cwd, ".plans"), { throwIfNoEntry: false });
+    if (entry === undefined)
+        return `\`\`\`text\n${missingPlansMessage(ctx.form)}\n\`\`\``;
+    try {
+        return resolvePlansMode(ctx.cwd, ctx.form).kind === "shared"
+            ? "After every change in TASK_DIR, run `{{CMD}} sync`."
+            : "";
+    }
+    catch {
+        return "";
+    }
+}
+function renderCommitRule(ctx) {
+    const commit = ctx.projectConfig?.config.git?.commit;
+    if (commit === undefined)
+        return "(follow the convention you are aware of, or default to `<type>: [<ticket_id>] very short description`)";
+    const { subject, side } = commitSubject(commit);
+    const rule = side === undefined ? subject : `${subject}; ${side}`;
+    return `(project convention: ${rule})`;
+}
+function renderBaseBranchRule(ctx, protocol) {
+    const branch = resolveDefaultBranch(ctx.cwd, ctx.projectConfig?.config);
+    if (protocol === "review")
+        return branch === undefined
+            ? "the **base branch** to compare against - use the branch provided by the user, or fall back to the default branch."
+            : `the **base branch** to compare against - use the branch provided by the user, or fall back to \`${branch.name}\`, the default branch.`;
+    if (protocol === "merge")
+        return branch === undefined
+            ? "otherwise ask which branch to merge."
+            : `otherwise merge \`${branch.name}\`, the default branch.`;
+    return "";
+}
+function applyPlaceholders(template, values) {
+    return template
+        .replaceAll(`${PLANS_STATE_PLACEHOLDER}\n\n`, () => values.plansState === "" ? "" : `${values.plansState}\n\n`)
+        .replaceAll(TICKET_CMD_PLACEHOLDER, () => values.ticketCommand)
+        .replaceAll(TICKET_CONTEXT_PLACEHOLDER, () => values.ticketContext)
+        .replaceAll(PLANS_STATE_PLACEHOLDER, () => values.plansState)
+        .replaceAll(COMMIT_RULE_PLACEHOLDER, () => values.commitRule)
+        .replaceAll(BASE_BRANCH_RULE_PLACEHOLDER, () => values.baseBranchRule);
 }
 function readProtocolTemplate(protocol) {
     return readGuideTemplate(`protocols/${protocol}.md`);

package/dist/commands/plans.js

@@ -1,12 +1,14 @@
 import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
 import { assertMainWorktreeRoot } from "../git.js";
-import { parseCommandArgs } from "../parse-args.js";
+import { parseBareCommandArgs, parseCommandArgs } from "../parse-args.js";
 import { archiveEntry, archiveThresholdDays, autoArchive } from "../plans/archive.js";
 import { linkPlans } from "../plans/link.js";
 import { resolvePlansMode } from "../plans/mode.js";
+import { findStoppedRebase, renderStoppedRebase } from "../plans/rebase.js";
+const RESERVED_PLANS_FOLDERS = new Set([".git", ".plans", "_archives", "_project"]);
 export function runPlans(ctx, args) {
     const [command, ...rest] = args;
     switch (command) {
@@ -42,11 +44,29 @@ function runSetup(ctx, args) {
     assertMainWorktreeRoot(ctx.cwd);
     const cloneDir = resolve(ctx.cwd, parsed.dir);
     checkClone(ctx, cloneDir);
-    const projectDir = join(cloneDir, parsed.folder);
-    mkdirSync(projectDir, { recursive: true });
+    const projectDir = createPlansDirectory(cloneDir, parsed.folder);
     linkPlans(ctx, projectDir);
     return 0;
 }
+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.`);
+    }
+    if (RESERVED_PLANS_FOLDERS.has(folder.toLowerCase())) {
+        throw new CliError(`Plans folder "${folder}" is reserved.`);
+    }
+    const cloneRoot = realpathSync(cloneDir);
+    const projectDir = join(cloneRoot, folder);
+    mkdirSync(projectDir, { recursive: true });
+    const relativeTarget = relative(cloneRoot, realpathSync(projectDir));
+    if (relativeTarget === "" ||
+        relativeTarget === ".." ||
+        relativeTarget.startsWith(`..${sep}`) ||
+        isAbsolute(relativeTarget)) {
+        throw new CliError(`Plans folder "${folder}" must resolve inside ${cloneRoot}.`);
+    }
+    return projectDir;
+}
 function parseSetupArgs(ctx, args, usage) {
     const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
         args,
@@ -64,8 +84,8 @@ function parseSetupArgs(ctx, args, usage) {
     if (positionals.length !== 1)
         throw new CliError(usage.trimEnd());
     const configFolder = ctx.projectConfig?.config.plans?.folder;
-    if (values.folder !== undefined && configFolder !== undefined)
-        throw new CliError(".alignfirst.json already sets plans.folder; drop --folder.");
+    if (values.folder !== undefined && configFolder !== undefined && values.folder !== configFolder)
+        throw new CliError(`--folder "${values.folder}" differs from plans.folder "${configFolder}" in .alignfirst.json.`);
     const folder = values.folder ?? configFolder;
     if (folder === undefined)
         throw new CliError("Pass --folder <name> or set plans.folder in .alignfirst.json.");
@@ -81,32 +101,23 @@ function checkClone(ctx, cloneDir) {
 }
 function runCheck(ctx, args) {
     const usage = `Usage: ${ctx.form} plans check\n`;
-    if (handleBareHelp(ctx, args, usage))
+    if (parseBareCommandArgs(ctx, args, usage))
         return 0;
     const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    if (mode.kind === "shared") {
+        const stopped = findStoppedRebase(mode.repoToplevel);
+        if (stopped !== undefined)
+            throw new CliError(renderStoppedRebase(stopped, ctx.form));
+    }
     if (mode.kind === "shared")
         ctx.stdout.write(".plans is linked to the team plans repository.\n");
     else
         ctx.stdout.write(".plans is a local directory (local plans mode): synchronization is disabled.\n");
     return 0;
 }
-function handleBareHelp(ctx, args, usage) {
-    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
-        args,
-        options: { help: { type: "boolean", short: "h", default: false } },
-        strict: true,
-        allowPositionals: true,
-    }));
-    if (positionals.length > 0)
-        throw new CliError(`Unexpected argument: ${positionals[0]}\n\n${usage}`);
-    if (!values.help)
-        return false;
-    ctx.stdout.write(usage);
-    return true;
-}
 function runAutoArchive(ctx, args) {
     const usage = `Usage: ${ctx.form} plans auto-archive\n`;
-    if (handleBareHelp(ctx, args, usage))
+    if (parseBareCommandArgs(ctx, args, usage))
         return 0;
     const mode = resolvePlansMode(ctx.cwd, ctx.form);
     const archived = autoArchive(join(ctx.cwd, ".plans"), archiveThresholdDays(ctx.env), ctx.stdout);