alignfirst 0.4.0 → 0.6.0-preview.0

package/README.md

@@ -4,6 +4,8 @@ The AlignFirst CLI provides collaborative software-development workflows, work f
 
 See the [product page](https://alignfirst.paroi.tech/skills) for a demonstration.
 
+Supported systems: Linux and macOS, and Windows through WSL.
+
 ## Agent skills
 
 Nine Agent Skill stubs expose the CLI as commands in Claude Code, Codex, GitHub Copilot, and Cursor. Install them globally:
@@ -87,8 +89,8 @@ The guide installs the selected components and configures the repository. You ca
 - `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.
-- `config` — Report the effective project configuration.
+- `context` — Print the conventions, the project instructions from `.alignfirst.md`, the documentation map when `docs/` exists, and the protocol aliases.
+- `config` — Report the effective project configuration, the companion directory and the location of each AlignFirst file.
 - `doctor` — Diagnose an AlignFirst setup.
 
 Run `alignfirst --help` for command usage or `alignfirst guide` to choose a protocol. `alignfirst guide <protocol>` prints the selected protocol followed by the ticket directory and work file rules. Add `--protocol-only` when those rules are already in context.
@@ -97,6 +99,56 @@ Run `alignfirst --help` for command usage or `alignfirst guide` to choose a prot
 
 `alignfirst ticket [<id>] --catchup` prints the ticket's Markdown files, plans excluded.
 
+## Companion directories
+
+A companion directory holds a project's AlignFirst files outside its repository, so the repository stays untouched. `~/.config/alignfirst/companions.json` declares which projects have one:
+
+```json
+{
+  "root": "~/alignfirst-companions",
+  "paths": {
+    "~/projects/team-app": { ".plans": false, "_aligndev": true },
+    "~/projects/client-api": {},
+    "~/projects": {}
+  }
+}
+```
+
+- `root` — the directory that holds the companion directories: an absolute path or a `~/` path.
+- `paths` — the projects, by absolute or `~/` path. Each value sets flags for the items a companion can hold: `.alignfirst.json`, `.alignfirst.md`, `DEVELOPERS.md`, `docs`, `.plans` and `_aligndev`. A flag is `true`, `false` or `"auto"`.
+
+An absent file means no project has a companion. An invalid file makes every command fail; `doctor` reports it and continues.
+
+### Matching
+
+A key matches a project when it names the project's main worktree or one of its ancestors, so every worktree of a project shares one companion. `"~": {}` matches every project under the home directory. For each item, the longest matching key that sets the flag wins, and an unset flag is `"auto"`. A bare repository or a directory outside git has no companion.
+
+The companion directory is `<root>/<name>`. The name is the main worktree path relative to the home directory, or the absolute path without its leading `/` outside it, with every `/` replaced by `_`. For example, `~/projects/client-api` gets `<root>/projects_client-api/`.
+
+### Resolution
+
+| Flag | Location |
+| --- | --- |
+| `true` | The companion copy, present or not. |
+| `false` | The project copy, present or not. |
+| `"auto"` | The companion copy when it exists, otherwise the project copy when it exists, otherwise the companion copy, where the item gets created. |
+
+`_aligndev` is the directory under which `aligndev` writes its session files: `<companion>/.plans` when `true`, the resolved `.plans` otherwise. `"_aligndev": true` requires `.plans` set to `true` or `false`. When the two differ, archiving and `ticket <id>` apply to both trees, each with its own `_archives/`.
+
+`alignfirst config` reports the companion and the location of every item. `alignfirst doctor` checks them.
+
+### Project instructions
+
+`.alignfirst.md` holds free prose for the coding agent: the project instructions a prepared project keeps in its `AGENTS.md`. `alignfirst context` prints it under `# Project Instructions`. It resolves like the other items, so a project copy works too.
+
+### Agent bootstrap
+
+An agent reads a repository's `AGENTS.md` on its own, but never a companion. When your repositories carry no AlignFirst instructions, add this line to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
+
+```text
+In a git repository, run `alignfirst context` once before investigating, unless the project's instructions already say so.
+```
+
 ## Upgrade from v1, v2, or v3
 
 Install the setup-guide skill and ask your agent to run its upgrade route:

package/dist/cli.js

@@ -12,6 +12,7 @@ import { runPlans } from "./commands/plans.js";
 import { runSync } from "./commands/sync.js";
 import { runTicket } from "./commands/ticket.js";
 import { resolveProjectConfig } from "./project-config.js";
+import { layoutOf } from "./project-layout.js";
 import { checkCliRange } from "./version-guard.js";
 export async function main(options) {
     const argv = options?.argv ?? process.argv;
@@ -36,7 +37,7 @@ export async function main(options) {
             return 0;
         }
         if (command !== "config" && command !== "doctor") {
-            ctx.projectConfig = resolveProjectConfig(ctx.cwd);
+            ctx.projectConfig = resolveProjectConfig(layoutOf(ctx));
             checkCliRange(ctx.projectConfig?.config, ctx.version, [command, ...args]);
         }
         const code = await dispatch(ctx, command, args);

package/dist/commands/config.js

@@ -1,15 +1,16 @@
 import { CliError } from "../cli-error.js";
 import { parseArgs } from "node:util";
 import { parseCommandArgs } from "../parse-args.js";
-import { resolveProjectConfig } from "../project-config.js";
+import { resolveProjectConfig, } from "../project-config.js";
+import { ITEM_NAMES, layoutOf, renderItemLocation, } from "../project-layout.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);
-    const report = buildConfigReport(ctx, resolved);
+    const layout = layoutOf(ctx);
+    const report = buildConfigReport(ctx, layout, resolveProjectConfig(layout));
     ctx.stdout.write(json ? `${JSON.stringify(report, undefined, 2)}\n` : renderConfigReport(report));
     return 0;
 }
@@ -31,12 +32,14 @@ function parseConfigArgs(ctx, args, usage) {
         throw new CliError(`Unexpected argument: ${positionals[0]}\n\n${usage}`);
     return values.json;
 }
-function buildConfigReport(ctx, resolved) {
+function buildConfigReport(ctx, layout, resolved) {
     const cli = cliRangeResult(resolved?.config, ctx.version);
     return {
         source: resolved?.source ?? null,
         cli: cli ? { installed: ctx.version, range: cli.range, satisfied: cli.satisfied } : null,
         config: resolved?.config ?? null,
+        companion: layout.companion,
+        locations: layout.locations,
     };
 }
 function renderConfigReport(report) {
@@ -45,7 +48,15 @@ function renderConfigReport(report) {
         lines.push(`CLI range: ${report.cli.range}, ${report.cli.satisfied ? "satisfied" : "not satisfied"} by ${report.cli.installed}`);
     else
         lines.push("CLI range: none");
+    lines.push(renderCompanionLine(report.companion));
+    for (const name of ITEM_NAMES)
+        lines.push(renderItemLocation(name, report.locations[name]));
     if (report.config)
         lines.push("Config:", JSON.stringify(report.config, undefined, 2));
     return `${lines.join("\n")}\n`;
 }
+function renderCompanionLine(companion) {
+    if (companion === null)
+        return "Companion: none";
+    return `Companion: ${companion.dir}${companion.exists ? "" : " (missing)"}`;
+}

package/dist/commands/context.js

@@ -1,18 +1,38 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { CliError } from "../cli-error.js";
 import { renderCommandForm } from "../command-form.js";
 import { renderConventions } from "../conventions.js";
+import { errorMessage } from "../errors.js";
 import { parseBareCommandArgs } from "../parse-args.js";
+import { layoutOf } from "../project-layout.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(`# Project Conventions\n\n${renderConventions(ctx)}`);
-    const code = existsSync(join(ctx.cwd, "docs")) ? writeDocmapSection(ctx) : 0;
+    writeProjectInstructions(ctx);
+    const code = layoutOf(ctx).locations.docs.exists ? writeDocmapSection(ctx) : 0;
     ctx.stdout.write(`\n${renderProtocolsSection(ctx)}`);
     return code;
 }
+function writeProjectInstructions(ctx) {
+    const location = layoutOf(ctx).locations[".alignfirst.md"];
+    if (!location.exists)
+        return;
+    const content = readInstructions(location.path).trim();
+    if (content === "")
+        return;
+    ctx.stdout.write(`\n# Project Instructions\n\n${content}\n`);
+}
+function readInstructions(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch (error) {
+        throw new CliError(`Cannot read ${path}: ${errorMessage(error)}`);
+    }
+}
 function writeDocmapSection(ctx) {
     ctx.stdout.write("\n# Docmap Usage\n\n");
     return runDocmap(ctx, []);

package/dist/commands/docmap.js

@@ -1,7 +1,10 @@
 import { main as docmapMain } from "@alignfirst/docmap";
+import { layoutOf } from "../project-layout.js";
 export function runDocmap(ctx, args) {
+    const docs = layoutOf(ctx).locations.docs;
+    const rootArgs = docs.in === "companion" && !args.includes("--root") ? ["--root", docs.path] : [];
     return docmapMain({
-        argv: ["node", "docmap", ...args],
+        argv: ["node", "docmap", ...rootArgs, ...args],
         cwd: ctx.cwd,
         stdout: ctx.stdout,
         stderr: ctx.stderr,

package/dist/commands/doctor.js

@@ -1,6 +1,5 @@
 import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import semver from "semver";
 import { resolveDefaultBranch } from "../default-branch.js";
@@ -9,6 +8,7 @@ import { parseBareCommandArgs } from "../parse-args.js";
 import { resolvePlansMode } from "../plans/mode.js";
 import { findStoppedRebase } from "../plans/rebase.js";
 import { PROJECT_CONFIG_FILENAME, resolveProjectConfig, } from "../project-config.js";
+import { companionsPath, ITEM_NAMES, layoutOf, renderItemLocation, } from "../project-layout.js";
 import { COMMAND_SKILLS, findInstalledSkill } from "../skills.js";
 import { cliRangeResult } from "../version-guard.js";
 export function runDoctor(ctx, args) {
@@ -18,9 +18,10 @@ export function runDoctor(ctx, args) {
     writeSection(ctx, "CLI", () => inspectCli(ctx));
     let resolved;
     writeSection(ctx, PROJECT_CONFIG_FILENAME, () => {
-        resolved = resolveProjectConfig(ctx.cwd);
+        resolved = resolveProjectConfig(layoutOf(ctx));
         return inspectConfig(ctx, resolved);
     });
+    writeSection(ctx, "Companion", () => inspectCompanion(ctx));
     writeSection(ctx, "Git", () => inspectGit(ctx, resolved));
     writeSection(ctx, "Work files", () => inspectPlans(ctx));
     writeSection(ctx, "Docmap", () => inspectDocmap(ctx));
@@ -65,6 +66,28 @@ function inspectConfig(ctx, resolved) {
         lines.push({ level: "warn", text: `${ctx.version} is ahead of ${result.range}` });
     return lines;
 }
+function inspectCompanion(ctx) {
+    const path = companionsPath(ctx.home);
+    const layout = layoutOf(ctx);
+    const file = {
+        level: "ok",
+        text: `companions.json ${existsSync(path) ? "valid" : "absent"} (${path})`,
+    };
+    if (layout.companion === null)
+        return [file, { level: "ok", text: "none" }];
+    const { companion } = layout;
+    return [
+        file,
+        { level: "ok", text: `matched by ${companion.entries.join(", ")}` },
+        { level: "ok", text: `directory ${companion.dir}${companion.exists ? "" : " (missing)"}` },
+        ...ITEM_NAMES.map((name) => describeItem(name, layout, companion)),
+    ];
+}
+function describeItem(name, layout, companion) {
+    const location = layout.locations[name];
+    const missingCopy = companion.flags[name] === true && !location.exists;
+    return { level: missingCopy ? "warn" : "ok", text: renderItemLocation(name, location) };
+}
 function inspectGit(ctx, resolved) {
     const branch = resolveDefaultBranch(ctx.cwd, resolved?.config);
     if (branch === undefined)
@@ -73,7 +96,7 @@ function inspectGit(ctx, resolved) {
     return [{ level: "ok", text: `default branch ${branch.name} (${source})` }];
 }
 function inspectPlans(ctx) {
-    const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    const mode = resolvePlansMode(ctx.cwd, layoutOf(ctx).locations[".plans"], ctx.form);
     if (mode.kind === "shared" && findStoppedRebase(mode.repoToplevel) !== undefined)
         return [{ level: "error", text: `rebase stopped on a conflict in ${mode.repoToplevel}` }];
     return [
@@ -84,7 +107,7 @@ function inspectPlans(ctx) {
     ];
 }
 function inspectDocmap(ctx) {
-    const present = existsSync(join(ctx.cwd, "docs"));
+    const present = layoutOf(ctx).locations.docs.exists;
     return [
         { level: "ok", text: `docs/ ${present ? "present" : "none"}` },
         { level: "ok", text: `embedded docmap ${readDocmapVersion()}` },

package/dist/commands/guide.js

@@ -1,5 +1,4 @@
-import { lstatSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
 import { renderCommandForm } from "../command-form.js";
@@ -9,6 +8,7 @@ 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 { layoutOf } from "../project-layout.js";
 import { PROTOCOLS } from "../protocols.js";
 const TICKET_CMD_PLACEHOLDER = "{{TICKET_CMD}}";
 const TICKET_DETECTION_PLACEHOLDER = "{{TICKET_DETECTION}}";
@@ -148,11 +148,11 @@ function renderTicketDetection(pattern, detection) {
     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\`\`\``;
+    const plans = layoutOf(ctx).locations[".plans"];
+    if (!plans.exists)
+        return `\`\`\`text\n${missingPlansMessage(plans, ctx.form)}\n\`\`\``;
     try {
-        return resolvePlansMode(ctx.cwd, ctx.form).kind === "shared"
+        return resolvePlansMode(ctx.cwd, plans, ctx.form).kind === "shared"
             ? "After every change in TICKET_DIR, run `{{CMD}} sync`."
             : "";
     }

package/dist/commands/plans.js

@@ -2,14 +2,16 @@ import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
+import { displayPath } from "../format.js";
 import { assertMainWorktreeRoot } from "../git.js";
 import { parseBareCommandArgs, parseCommandArgs } from "../parse-args.js";
-import { archiveEntry, archiveThresholdDays, autoArchive } from "../plans/archive.js";
+import { archiveThresholdDays, archiveTicket, autoArchive } from "../plans/archive.js";
 import { isTicketName } from "../plans/layout.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"]);
+import { layoutOf } from "../project-layout.js";
+const RESERVED_PLANS_FOLDERS = new Set([".git", ".plans", "_archives"]);
 export function runPlans(ctx, args) {
     const [command, ...rest] = args;
     switch (command) {
@@ -46,7 +48,7 @@ function runSetup(ctx, args) {
     const cloneDir = resolve(ctx.cwd, parsed.dir);
     checkClone(ctx, cloneDir);
     const projectDir = createPlansDirectory(cloneDir, parsed.folder);
-    linkPlans(ctx, projectDir);
+    linkPlans(ctx, layoutOf(ctx).locations[".plans"].path, projectDir);
     return 0;
 }
 function createPlansDirectory(cloneDir, folder) {
@@ -104,7 +106,7 @@ function runCheck(ctx, args) {
     const usage = `Usage: ${ctx.form} plans check\n`;
     if (parseBareCommandArgs(ctx, args, usage))
         return 0;
-    const mode = resolvePlansMode(ctx.cwd, ctx.form);
+    const mode = resolvePlansMode(ctx.cwd, layoutOf(ctx).locations[".plans"], ctx.form);
     if (mode.kind === "shared") {
         const stopped = findStoppedRebase(mode.repoToplevel);
         if (stopped !== undefined)
@@ -120,25 +122,26 @@ function runAutoArchive(ctx, args) {
     const usage = `Usage: ${ctx.form} plans auto-archive\n`;
     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);
+    const layout = layoutOf(ctx);
+    const mode = resolvePlansMode(ctx.cwd, layout.locations[".plans"], ctx.form);
+    const archived = autoArchive(layout, archiveThresholdDays(ctx.env), ctx.stdout);
     if (mode.kind === "shared" && archived)
         ctx.stdout.write(`Publish with: ${ctx.form} sync\n`);
     return 0;
 }
 function runArchive(ctx, args) {
     const usage = `Usage: ${ctx.form} plans archive <ticket-id | path>\n`;
-    const target = resolveArchiveTarget(ctx, args, usage);
-    if (target === undefined)
+    const ticket = resolveArchiveTicket(ctx, args, usage);
+    if (ticket === undefined)
         return 0;
-    const mode = resolvePlansMode(ctx.cwd, ctx.form);
-    const root = join(ctx.cwd, ".plans");
-    archiveEntry(root, target, ctx.stdout);
+    const layout = layoutOf(ctx);
+    const mode = resolvePlansMode(ctx.cwd, layout.locations[".plans"], ctx.form);
+    archiveTicket(layout, ticket, ctx.stdout);
     if (mode.kind === "shared")
         ctx.stdout.write(`Publish with: ${ctx.form} sync\n`);
     return 0;
 }
-function resolveArchiveTarget(ctx, args, usage) {
+function resolveArchiveTicket(ctx, args, usage) {
     const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
         args,
         options: { help: { type: "boolean", short: "h", default: false } },
@@ -152,15 +155,15 @@ function resolveArchiveTarget(ctx, args, usage) {
     if (positionals.length !== 1)
         throw new CliError(usage.trimEnd());
     const argument = positionals[0];
-    const plansDir = join(ctx.cwd, ".plans");
+    const plansDir = layoutOf(ctx).locations[".plans"].path;
     const target = isPathArgument(argument) ? resolve(ctx.cwd, argument) : join(plansDir, argument);
     const stats = statSync(target, { throwIfNoEntry: false });
     if (!stats?.isDirectory() || realpathSync(dirname(target)) !== realpathSync(plansDir))
-        throw new CliError(`${argument} must be an existing directory directly under .plans.`);
+        throw new CliError(`${argument} must be an existing directory directly under ${displayPath(ctx.cwd, plansDir)}.`);
     const name = basename(target);
     if (!isTicketName(name))
         throw new CliError(`${argument}: names starting with _ are not tickets.`);
-    return join(plansDir, name);
+    return name;
 }
 function isPathArgument(argument) {
     return argument.includes("/") || argument.includes("\\");

package/dist/commands/sync.js

@@ -1,4 +1,3 @@
-import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
 import { git, gitOutput, gitSucceeds } from "../git.js";
@@ -6,6 +5,7 @@ import { parseCommandArgs } from "../parse-args.js";
 import { archiveThresholdDays, autoArchive } from "../plans/archive.js";
 import { resolvePlansMode } from "../plans/mode.js";
 import { findStoppedRebase, renderStoppedRebase, resolveStoppedRebase } from "../plans/rebase.js";
+import { layoutOf } from "../project-layout.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);
@@ -17,11 +17,11 @@ export async function runSync(ctx, args) {
             ? false
             : (ctx.projectConfig?.config.plans?.autoArchive ?? false);
     const thresholdDays = enabled ? archiveThresholdDays(ctx.env) : undefined;
-    const mode = resolvePlansMode(ctx.cwd, ctx.form);
-    const plansDir = join(ctx.cwd, ".plans");
+    const layout = layoutOf(ctx);
+    const mode = resolvePlansMode(ctx.cwd, layout.locations[".plans"], ctx.form);
     if (mode.kind === "local") {
         if (thresholdDays !== undefined)
-            autoArchive(plansDir, thresholdDays, ctx.stdout);
+            autoArchive(layout, thresholdDays, ctx.stdout);
         ctx.stdout.write("(local mode, nothing to sync)\n");
         return 0;
     }
@@ -40,7 +40,7 @@ export async function runSync(ctx, args) {
             await resolveStoppedRebase(ctx, repoDir);
         }
     }
-    if (thresholdDays !== undefined && autoArchive(plansDir, thresholdDays, ctx.stdout)) {
+    if (thresholdDays !== undefined && autoArchive(layout, thresholdDays, ctx.stdout)) {
         await git(ctx, repoDir, "add", "-A");
         if (hasStagedChanges(repoDir))
             await git(ctx, repoDir, "commit", "--quiet", "-m", "sync");

package/dist/commands/ticket.js

@@ -1,11 +1,12 @@
-import { join, relative } from "node:path";
+import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
-import { formatLocalTimestamp, formatSize } from "../format.js";
+import { displayPath, formatLocalTimestamp, formatSize } from "../format.js";
 import { parseCommandArgs } from "../parse-args.js";
 import { renderCatchup } from "../plans/catchup.js";
 import { assertPlansGate } from "../plans/layout.js";
-import { detectTicketFromBranch, deduceTicketFromExisting, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
+import { detectTicketFromBranch, deduceTicketFromExisting, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, restoreSessionTreeTicket, validateTicketId, } from "../plans/ticket.js";
+import { layoutOf } from "../project-layout.js";
 const USAGE = `Usage:
   {{FORM}} ticket [<id>] [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
   {{FORM}} ticket --side [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
@@ -22,8 +23,12 @@ export function runTicket(ctx, args) {
     const parsed = parseTicketArgs(ctx, args, usage);
     if (parsed === undefined)
         return 0;
-    assertPlansGate(ctx.cwd, ctx.form);
-    const result = resolveTicket(ctx, parsed);
+    const layout = layoutOf(ctx);
+    const plans = layout.locations[".plans"];
+    assertPlansGate(plans, ctx.form);
+    const result = resolveTicket(plans.path, parsed);
+    if (!parsed.side && !parsed.dryRun)
+        restoreSessionTreeTicket(layout, result.id);
     if (parsed.catchup) {
         ctx.stdout.write(renderCatchup(ctx.cwd, result, renderReport(ctx, parsed, result)));
         return 0;
@@ -129,8 +134,11 @@ function resolveTicketId(ctx, positional, flags) {
         validateTicketId(positional);
         return { id: positional };
     }
-    if (flags.side)
-        return { id: flags["dry-run"] ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
+    const plans = layoutOf(ctx).locations[".plans"];
+    if (flags.side) {
+        assertPlansGate(plans, ctx.form);
+        return { id: flags["dry-run"] ? peekSideTicket(plans.path) : reserveSideTicket(plans.path) };
+    }
     const template = ctx.projectConfig?.config.git?.branchNameTemplate;
     const detection = detectTicketFromBranch(ctx.cwd, pattern, template);
     if (detection.kind === "detected") {
@@ -138,28 +146,23 @@ function resolveTicketId(ctx, positional, flags) {
         return detection;
     }
     if (pattern === undefined)
-        return deduceTicketFromExisting(ctx.cwd, { sideAllowed: !flags.catchup });
+        return deduceTicketFromExisting(ctx.cwd, plans.path, { sideAllowed: !flags.catchup });
     if (detection.kind === "noBranch")
         throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
     const templateDetail = template?.includes("{TICKET_ID}") ? ` and template "${template}"` : "";
     throw new CliError(`Cannot deduce a ticket id from branch "${detection.branch}" with pattern "${pattern}"${templateDetail}.`);
 }
-function resolveTicket(ctx, options) {
+function resolveTicket(plansPath, options) {
     if (options.side && !options.dryRun)
-        return {
-            id: options.id,
-            dir: join(ctx.cwd, ".plans", options.id),
-            state: "created",
-            entries: [],
-        };
-    return resolveTicketDir(ctx.cwd, options.id, { dryRun: options.dryRun });
+        return { id: options.id, dir: join(plansPath, options.id), state: "created", entries: [] };
+    return resolveTicketDir(plansPath, options.id, { dryRun: options.dryRun });
 }
 function writeNextReport(ctx, options, result, request) {
     const names = result.entries.map((entry) => entry.name);
     const { cycleLetter, fileNumber } = nextFilePosition(names, options.newCycle);
     const fileName = (filename, offset) => `${cycleLetter}${fileNumber + offset}-${filename}`;
     const report = {
-        TICKET_DIR: `${relative(ctx.cwd, result.dir)}/`,
+        TICKET_DIR: `${displayPath(ctx.cwd, result.dir)}/`,
         CYCLE_LETTER: cycleLetter,
         ...(request === true
             ? { FILE_NUMBER: fileNumber, FILE_PREFIX: `${cycleLetter}${fileNumber}` }
@@ -179,7 +182,7 @@ function writeNextReport(ctx, options, result, request) {
 function jsonReport(ctx, options, result) {
     return {
         TICKET_ID: result.id,
-        TICKET_DIR: `${relative(ctx.cwd, result.dir)}/`,
+        TICKET_DIR: `${displayPath(ctx.cwd, result.dir)}/`,
         state: result.state,
         ...(options.branch === undefined ? {} : { branch: options.branch }),
         entries: result.entries.map((entry) => ({
@@ -192,7 +195,7 @@ function renderReport(ctx, options, result) {
     const reservation = options.side && options.dryRun ? " (would be reserved)" : "";
     const deduction = options.branch === undefined ? "" : ` (deduced from branch \`${options.branch}\`)`;
     const directoryState = renderDirectoryState(result.state, options.dryRun);
-    const directory = `${relative(ctx.cwd, result.dir)}/`;
+    const directory = `${displayPath(ctx.cwd, result.dir)}/`;
     const lines = [
         `- TICKET_ID: \`${result.id}\`${reservation}${deduction}`,
         `- TICKET_DIR: \`${directory}\`${directoryState}`,

package/dist/context.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedProjectConfig } from "./project-config.js";
+import type { ProjectLayout } from "./project-layout.js";
 export interface Output {
     write(text: string): void;
 }
@@ -13,4 +14,5 @@ export interface CommandContext extends Streams {
     form: string;
     version: string;
     projectConfig?: ResolvedProjectConfig;
+    layout?: ProjectLayout;
 }

package/dist/conventions.js

@@ -1,9 +1,11 @@
-import { existsSync, lstatSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { renderDefaultBranchLine, resolveDefaultBranch } from "./default-branch.js";
 import { errorMessage } from "./errors.js";
+import { displayPath } from "./format.js";
 import { gitOutputOrUndefined, gitSucceeds } from "./git.js";
 import { resolvePlansMode } from "./plans/mode.js";
+import { layoutOf } from "./project-layout.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 = [
@@ -44,15 +46,17 @@ export function commitSubject(commit) {
     return { subject: "`type: summary`" };
 }
 function renderPlans(ctx) {
-    if (!plansEntryExists(ctx.cwd))
+    const plans = layoutOf(ctx).locations[".plans"];
+    if (!plans.exists)
         return;
     try {
-        const mode = resolvePlansMode(ctx.cwd, ctx.form);
+        const mode = resolvePlansMode(ctx.cwd, plans, ctx.form);
         const folder = ctx.projectConfig?.config.plans?.folder;
         const sharedFolder = folder === undefined ? "" : ` (folder \`${folder}\` in the work-files repository)`;
+        const path = displayPath(ctx.cwd, plans.path);
         const base = mode.kind === "shared"
-            ? `Work files: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
-            : "Work files: use `.plans`.";
+            ? `Work files: use \`${path}\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
+            : `Work files: use \`${path}\`.`;
         const archival = ctx.projectConfig?.config.plans?.autoArchive === true
             ? " Automatic archival is enabled."
             : "";
@@ -62,12 +66,10 @@ function renderPlans(ctx) {
         return `Work files: ${errorMessage(error).split("\n", 1)[0]}`;
     }
 }
-function plansEntryExists(cwd) {
-    return lstatSync(join(cwd, ".plans"), { throwIfNoEntry: false }) !== undefined;
-}
 function renderSearches(ctx) {
+    const plans = layoutOf(ctx).locations[".plans"];
     const directories = [
-        ...(plansEntryExists(ctx.cwd) ? [".plans"] : []),
+        ...(plans.exists && plans.in === "project" ? [".plans"] : []),
         ...[".local", ".local-wt"].filter((name) => qualifiesIgnoredDirectory(ctx.cwd, name)),
     ];
     if (directories.length === 0)

package/dist/format.d.ts

@@ -1,2 +1,4 @@
 export declare function formatSize(bytes: number): string;
 export declare function formatLocalTimestamp(date: Date): string;
+/** Relative to `cwd` when inside it, absolute otherwise. */
+export declare function displayPath(cwd: string, path: string): string;

package/dist/format.js

@@ -1,3 +1,4 @@
+import { isAbsolute, relative, sep } from "node:path";
 const KIB = 1024;
 const MIB = KIB * KIB;
 export function formatSize(bytes) {
@@ -21,3 +22,10 @@ export function formatLocalTimestamp(date) {
 function pad(value) {
     return String(value).padStart(2, "0");
 }
+/** Relative to `cwd` when inside it, absolute otherwise. */
+export function displayPath(cwd, path) {
+    const rel = relative(cwd, path);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return path;
+    return rel;
+}

package/dist/plans/archive.d.ts

@@ -1,4 +1,10 @@
 import type { Output } from "../context.js";
+import { type ProjectLayout } from "../project-layout.js";
 export declare function archiveThresholdDays(env: NodeJS.ProcessEnv): number;
-export declare function autoArchive(plansDir: string, thresholdDays: number, stdout: Output): boolean;
-export declare function archiveEntry(plansDir: string, sourcePath: string, stdout: Output): void;
+/**
+ * Archives the stale entries of `.plans`, and of a separate session tree into its own `_archives`.
+ * Returns whether `.plans` changed.
+ */
+export declare function autoArchive(layout: ProjectLayout, thresholdDays: number, stdout: Output): boolean;
+/** Archiving ticket `name` also archives its directory in a separate session tree. */
+export declare function archiveTicket(layout: ProjectLayout, name: string, stdout: Output): void;