alignfirst 0.1.0-beta.6 → 0.1.0

package/README.md

@@ -89,12 +89,12 @@ AlignFirst stores specifications, plans, and summaries in `.plans/<ticket-id>/`.
 
 ## Catchup output
 
-`alignfirst ticket [<id>] --catchup` prints the ticket's Markdown files, plans excluded, each in a `<file>` block carrying its path and modification time. When the history exceeds the output budget, only the entry list is printed so the agent can read the relevant files.
+`alignfirst ticket [<id>] --catchup` prints the ticket's Markdown files, plans excluded, each in a `<file>` block carrying its path and modification time. When the history exceeds the output budget, only the entry list is printed, with a notice telling the agent to read the relevant files and skip the plans.
 
 ## Updates
 
 ```sh
-npm update -g alignfirst
+npm install -g alignfirst@latest
 npx skills update --global --yes
 ```
 

package/dist/commands/plans.js

@@ -5,6 +5,7 @@ import { CliError } from "../cli-error.js";
 import { assertMainWorktreeRoot } from "../git.js";
 import { parseBareCommandArgs, parseCommandArgs } from "../parse-args.js";
 import { archiveEntry, archiveThresholdDays, 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";
@@ -156,9 +157,10 @@ function resolveArchiveTarget(ctx, args, usage) {
     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.`);
-    if (basename(target).startsWith("_"))
+    const name = basename(target);
+    if (!isTicketName(name))
         throw new CliError(`${argument}: names starting with _ are not tickets.`);
-    return target;
+    return join(plansDir, name);
 }
 function isPathArgument(argument) {
     return argument.includes("/") || argument.includes("\\");

package/dist/commands/ticket.js

@@ -11,16 +11,18 @@ const USAGE = `Usage:
   {{FORM}} ticket --side [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
   {{FORM}} ticket [<id>] --catchup
 
+--next may repeat, each occurrence with a filename: the names are numbered in order.
+
 --catchup prints the ticket's Markdown files, plans excluded, summaries included.
 Files over 64 KiB are listed without content. Above 30 KiB of output, only the entry
 list is printed.
 `;
 export function runTicket(ctx, args) {
-    assertPlansGate(ctx.cwd, ctx.form);
     const usage = renderUsage(ctx);
     const parsed = parseTicketArgs(ctx, args, usage);
     if (parsed === undefined)
         return 0;
+    assertPlansGate(ctx.cwd, ctx.form);
     const result = resolveTicket(ctx, parsed);
     if (parsed.catchup) {
         ctx.stdout.write(renderCatchup(ctx.cwd, result, renderReport(ctx, parsed, result)));
@@ -68,12 +70,10 @@ function parseTicketArgs(ctx, args, usage) {
     if (values.catchup &&
         (values.side || values.next !== undefined || values.json || values["dry-run"]))
         throw new CliError(`--catchup cannot be combined with --side, --next, --json, or --dry-run.\n\n${usage}`);
-    if (normalized.filename !== undefined)
-        validateNextFilename(normalized.filename);
     const resolution = resolveTicketId(ctx, positionals[0], values);
     return {
         ...resolution,
-        next: values.next === undefined ? undefined : (normalized.filename ?? true),
+        next: values.next === undefined ? undefined : resolveNextRequest(normalized.requests, usage),
         newCycle: values["new-cycle"],
         json: values.json,
         dryRun: values["dry-run"],
@@ -82,7 +82,7 @@ function parseTicketArgs(ctx, args, usage) {
     };
 }
 function normalizeNextArgs(args) {
-    const normalized = { args: [] };
+    const normalized = { args: [], requests: [] };
     for (let index = 0; index < args.length; ++index) {
         const arg = args[index];
         if (arg === "--") {
@@ -90,7 +90,7 @@ function normalizeNextArgs(args) {
             break;
         }
         if (arg.startsWith("--next=")) {
-            normalized.filename = arg.slice("--next=".length);
+            normalized.requests.push(arg.slice("--next=".length));
             normalized.args.push("--next");
             continue;
         }
@@ -98,14 +98,25 @@ function normalizeNextArgs(args) {
         if (arg !== "--next")
             continue;
         const following = args[index + 1];
-        delete normalized.filename;
         if (following !== undefined && !following.startsWith("-")) {
-            normalized.filename = following;
+            normalized.requests.push(following);
             ++index;
         }
+        else
+            normalized.requests.push(undefined);
     }
     return normalized;
 }
+function resolveNextRequest(requests, usage) {
+    if (requests.length === 1 && requests[0] === undefined)
+        return true;
+    const filenames = requests.filter((request) => request !== undefined);
+    if (filenames.length < requests.length)
+        throw new CliError(`A repeated --next requires a filename on each occurrence.\n\n${usage}`);
+    for (const filename of filenames)
+        validateNextFilename(filename);
+    return filenames;
+}
 function validateNextFilename(filename) {
     if (filename.length === 0 || filename === "." || filename === ".." || /[\\/]/u.test(filename)) {
         throw new CliError("--next must be a non-empty single path segment.");
@@ -135,21 +146,26 @@ function resolveTicket(ctx, options) {
         };
     return resolveTicketDir(ctx.cwd, options.id, { dryRun: options.dryRun });
 }
-function writeNextReport(ctx, options, result, filename) {
+function writeNextReport(ctx, options, result, request) {
     const names = result.entries.map((entry) => entry.name);
     const { cycleLetter, fileNumber } = nextFilePosition(names, options.newCycle);
-    const prefix = `${cycleLetter}${fileNumber}`;
+    const fileName = (filename, offset) => `${cycleLetter}${fileNumber + offset}-${filename}`;
     const report = {
         TICKET_DIR: `${relative(ctx.cwd, result.dir)}/`,
         CYCLE_LETTER: cycleLetter,
-        FILE_NUMBER: fileNumber,
-        ...(filename === true ? { FILE_PREFIX: prefix } : { FILE_NAME: `${prefix}-${filename}` }),
+        ...(request === true
+            ? { FILE_NUMBER: fileNumber, FILE_PREFIX: `${cycleLetter}${fileNumber}` }
+            : request.length === 1
+                ? { FILE_NUMBER: fileNumber, FILE_NAME: fileName(request[0], 0) }
+                : { FILE_NAMES: request.map(fileName) }),
     };
     if (options.json) {
         ctx.stdout.write(`${JSON.stringify(report, undefined, 2)}\n`);
         return;
     }
-    const lines = Object.entries(report).map(([name, value]) => `- ${name}: \`${value}\``);
+    const lines = Object.entries(report).map(([name, value]) => Array.isArray(value)
+        ? [`- ${name}:`, ...value.map((item) => `  - \`${item}\``)].join("\n")
+        : `- ${name}: \`${value}\``);
     ctx.stdout.write(`${lines.join("\n")}\n`);
 }
 function jsonReport(ctx, options, result) {

package/dist/conventions.js

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync } from "node:fs";
 import { join } from "node:path";
 import { renderDefaultBranchLine, resolveDefaultBranch } from "./default-branch.js";
+import { errorMessage } from "./errors.js";
 import { gitOutputOrUndefined, gitSucceeds } from "./git.js";
 import { resolvePlansMode } from "./plans/mode.js";
 export function renderConventions(ctx) {
@@ -59,8 +60,7 @@ function renderPlans(ctx) {
         return `${base}${archival}`;
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return `Plans: ${message.split("\n", 1)[0]}`;
+        return `Plans: ${errorMessage(error).split("\n", 1)[0]}`;
     }
 }
 function plansEntryExists(cwd) {

package/dist/plans/catchup.js

@@ -1,12 +1,13 @@
 import { readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { CliError } from "../cli-error.js";
+import { errorMessage } from "../errors.js";
 import { formatLocalTimestamp, formatSize } from "../format.js";
 const MAX_FILE_BYTES = 64 * 1024;
 const MAX_OUTPUT_BYTES = 30 * 1024;
 const PLAN_FILE = /^[A-Z]\d+-(?:main-plan|plan-.*)\.md$/;
 const OMISSION_NOTICE = `Content omitted: over the ${formatSize(MAX_FILE_BYTES)} limit.`;
-const TOO_LARGE_NOTICE = `History too large to print (over the ${formatSize(MAX_OUTPUT_BYTES)} budget). Read the relevant files among the entries above rather than all of them.`;
+const TOO_LARGE_NOTICE = `History too large to print (over the ${formatSize(MAX_OUTPUT_BYTES)} budget). Read the relevant files among the entries above, skipping the plans (\`*-plan.md\`, \`*-main-plan.md\`, \`*-plan-*.md\`): their \`.summary.md\` files cover them.`;
 export function renderCatchup(cwd, ticket, report) {
     const files = ticket.entries.flatMap((entry) => catchupFile(cwd, ticket.dir, entry));
     if (files.length === 0)
@@ -49,7 +50,6 @@ function readBody(cwd, file) {
         return readFileSync(join(cwd, file.path), "utf-8");
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new CliError(`Cannot load catchup file ${file.path}: ${detail}`);
+        throw new CliError(`Cannot load catchup file ${file.path}: ${errorMessage(error)}`);
     }
 }

package/dist/plans/layout.d.ts

@@ -1,9 +1,11 @@
+import { type Stats } from "node:fs";
 import { CliError } from "../cli-error.js";
 export declare const PLANS_DIR = ".plans";
 export declare const ARCHIVES_DIR = "_archives";
 export declare function isTicketName(name: string): boolean;
 export declare function plansDir(cwd: string): string;
 export declare function archivesDir(cwd: string): string;
-export declare function assertPlansGate(cwd: string, form: string): void;
+/** Returns the lstat of `.plans`, so callers can tell a symlink from a directory. */
+export declare function assertPlansGate(cwd: string, form: string): Stats;
 export declare function missingPlansMessage(form: string): string;
 export declare function missingPlansError(form: string): CliError;

package/dist/plans/layout.js

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, lstatSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { CliError } from "../cli-error.js";
 export const PLANS_DIR = ".plans";
@@ -12,10 +12,17 @@ export function plansDir(cwd) {
 export function archivesDir(cwd) {
     return join(plansDir(cwd), ARCHIVES_DIR);
 }
+/** Returns the lstat of `.plans`, so callers can tell a symlink from a directory. */
 export function assertPlansGate(cwd, form) {
-    if (existsSync(plansDir(cwd)))
-        return;
-    throw missingPlansError(form);
+    const path = plansDir(cwd);
+    const stats = lstatSync(path, { throwIfNoEntry: false });
+    if (!stats)
+        throw missingPlansError(form);
+    if (stats.isSymbolicLink() && !existsSync(path))
+        throw new CliError(`The .plans symlink is broken. Re-run ${form} plans setup with the clone location.`);
+    if (!statSync(path).isDirectory())
+        throw new CliError(`.plans is not a directory. Remove it, then run ${form} plans setup (see the project documentation).`);
+    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>`;

package/dist/plans/mode.js

@@ -1,17 +1,11 @@
-import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { realpathSync } from "node:fs";
 import { join } from "node:path";
 import { CliError } from "../cli-error.js";
 import { gitOutput } from "../git.js";
-import { missingPlansError } from "./layout.js";
+import { assertPlansGate } from "./layout.js";
 export function resolvePlansMode(cwd, form) {
     const plansPath = join(cwd, ".plans");
-    const stats = lstatSync(plansPath, { throwIfNoEntry: false });
-    if (!stats)
-        throw missingPlansError(form);
-    if (stats.isSymbolicLink() && !existsSync(plansPath))
-        throw new CliError(`The .plans symlink is broken. Re-run ${form} plans setup with the clone location.`);
-    if (!statSync(plansPath).isDirectory())
-        throw new CliError(`.plans is not a directory. Remove it, then run ${form} plans setup (see the project documentation).`);
+    const stats = assertPlansGate(cwd, form);
     if (plansRepositoryId(plansPath, stats.isSymbolicLink(), form) === repositoryId(cwd))
         return { kind: "local" };
     return { kind: "shared", repoToplevel: gitOutput(plansPath, "rev-parse", "--show-toplevel") };

package/dist/plans/ticket.js

@@ -105,7 +105,7 @@ export function isPathSafeTicketId(id) {
     return id !== "." && !id.includes("..") && PATH_SAFE_TICKET.test(id);
 }
 export function validateTicketId(id, pattern) {
-    if (!isPathSafeTicketId(id))
+    if (!isPathSafeTicketId(id) || !isTicketName(id))
         throw new CliError(`Invalid ticket id: ${id}`);
     if (pattern !== undefined && !new RegExp(pattern).test(id) && !SIDE_TICKET.test(id))
         throw new CliError(`Ticket id "${id}" does not match ticketIdPattern "${pattern}".`);

package/dist/project-config.js

@@ -75,6 +75,26 @@ function assertValidPattern(pattern, label) {
     catch (error) {
         throw invalidConfig(label, `ticketIdPattern is not a valid regular expression: ${errorMessage(error)}`);
     }
+    if (hasInnerAnchor(pattern))
+        throw invalidConfig(label, "ticketIdPattern must be one anchored expression; group alternatives: ^(ABC|XYZ)-\\d+$");
+}
+/** Branch detection unanchors the pattern by trimming its ends, so inner anchors never match. */
+function hasInnerAnchor(pattern) {
+    let inClass = false;
+    for (let i = 0; i < pattern.length; ++i) {
+        const char = pattern[i];
+        if (char === "\\")
+            ++i;
+        else if (inClass)
+            inClass = char !== "]";
+        else if (char === "[")
+            inClass = true;
+        else if (char === "^" && i !== 0)
+            return true;
+        else if (char === "$" && i !== pattern.length - 1)
+            return true;
+    }
+    return false;
 }
 function assertValidPortRange(range, label) {
     if (range.first > range.last)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, plans and docs in one command.",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@paleo/docmap": "~0.10.0-beta.1",
+    "@paleo/docmap": "~0.10.0",
     "arktype": "^2.2.3",
     "semver": "^7.8.5"
   },

package/templates/guide/core.md

@@ -18,9 +18,9 @@ Files use `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`. FILE_PREFIX combines the
 
 Immediately before creating each file, run `{{TICKET_CMD}} --next <filename>` with the extension included. It returns TICKET_DIR, CYCLE_LETTER, FILE_NUMBER, and FILE_NAME. Append FILE_NAME to TICKET_DIR to get the file path, preserving the leading dot and existing slash.
 
-With no filename, `{{TICKET_CMD}} --next` returns FILE_PREFIX instead of FILE_NAME. Add `--new-cycle` to either form when the protocol or user calls for a new cycle.
+With no filename, `{{TICKET_CMD}} --next` returns FILE_PREFIX instead of FILE_NAME. To name several files at once, repeat `--next <filename>` once per file: the command returns FILE_NAMES, numbered in that order. Add `--new-cycle` to any form when the protocol or user calls for a new cycle.
 
-Neither form reserves a number. Write the file before requesting another filename. With `--json`, the same information uses the same field names.
+No form reserves a number. Write the named file or files before requesting another filename. With `--json`, the same information uses the same field names.
 
 Common file types are `spec`, `plan`, `AAD.summary`, `description`, `review`, and `merge.summary`. Use another type when needed.
 

package/templates/guide/protocols/plan.md

@@ -207,32 +207,22 @@ Note:
 
 ## Phase 5. Writing
 
-Write the plan file(s) according to the determined structure:
+Continue the current cycle. Request the file names with `{{TICKET_CMD}} --next`, then write every file it named before requesting anything else. Append each name to TICKET_DIR to get its path. Never overwrite an existing file.
 
-Continue the current cycle. Immediately before writing each file, run `{{TICKET_CMD}} --next plan.md`, `{{TICKET_CMD}} --next main-plan.md`, or `{{TICKET_CMD}} --next plan-<descriptor>.md`. Append FILE_NAME to TICKET_DIR to get its path. Write that file before requesting the next one.
+**Single plan**: run `{{TICKET_CMD}} --next plan.md`.
 
-**Single Plan**:
+- Plan: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-plan.md`, e.g. `.plans/123/A2-plan.md`
+- Handover: `.plans/123/A2-plan.summary.md`
 
-- **Single plan**: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-plan.md`
-  - Example: `.plans/123/A2-plan.md`
-  - Handover: `.plans/123/A2-plan.summary.md`
-  - No main plan needed
+**Multiple plans**: run one command with a `--next` per file, the main plan first, then the specialized plans in the order the main plan lists them. The command returns all the names, numbered in that order, so the main plan can reference the specialized plans exactly. Example:
 
-**Multiple Plans**:
-
-- **Main plan**: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-main-plan.md`
-  - Example: `.plans/123/A2-main-plan.md`
-  - Handover: `.plans/123/A2-main-plan.summary.md` (written after all specialized plans complete)
-- **Specialized plans**: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-plan-{DESCRIPTOR}.md`
-  - Use a descriptive name as `{DESCRIPTOR}` (e.g., work scope, stack area)
-  - Example: `.plans/123/A3-plan-api.md`, `.plans/123/A4-plan-ui.md`
-  - Handovers: `.plans/123/A3-plan-api.summary.md`, etc.
-
-**Important**:
+```
+{{TICKET_CMD}} --next main-plan.md --next plan-api.md --next plan-ui.md
+```
 
-- Use lowercase, hyphenated descriptors for plan names (work scope descriptor)
-- When multiple plans are created, the main plan should be written first and have the lowest FILE_NUMBER
-- Be careful never to overwrite an existing file
+- Main plan: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-main-plan.md`, e.g. `.plans/123/A2-main-plan.md`
+- Specialized plans: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-plan-{DESCRIPTOR}.md`, e.g. `.plans/123/A3-plan-api.md`, `.plans/123/A4-plan-ui.md`. The descriptor is lowercase and hyphenated and names the work scope or stack area.
+- Handovers: replace the final `.md` with `.summary.md`, e.g. `.plans/123/A3-plan-api.summary.md`. The main plan handover is written after all specialized plans complete.
 
 _Important Note: There will be lint errors in the markdown files you write. Ignore them. NEVER FIX LINT ERRORS (FORMATTING ISSUES) IN THE PLANS._