alignfirst 0.1.0-beta.7 → 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/ticket.js

@@ -11,6 +11,8 @@ 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.
@@ -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/plans/catchup.js

@@ -7,7 +7,7 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.1.0-beta.7",
+  "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._