alignfirst 0.1.0-beta.7 → 0.1.1

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.1",
   "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/merge.md

@@ -24,14 +24,18 @@ Run `{{TICKET_CMD}} --next merge.summary.md` to continue the current cycle. Appe
 
 Resolve the conflicts properly — preserve both intents whenever possible. Do not blindly accept one side.
 
+Resolve conflicts one at a time. Avoid batch processing, broad search-and-replace operations, and other brute-force edits.
+
 **Special case for lock files:** If a lock file has conflicts:
 
 1. Accept all the changes from the incoming branch.
 2. After all other conflicts are resolved, run the proper install command so the package manager re-applies the current branch's dependency changes.
 
-## 4. Finalize the Merge
+## 4. Validate and Commit
+
+After resolving all conflicts, run the codebase's usual checks, such as compilation, linting, and unit tests. Commit the merge as soon as the available checks pass, using Git's default message (for example, `git commit --no-edit`).
 
-Finalize the merge using git's default commit message (e.g. `git commit --no-edit`). Do not write your own commit message — git has already prepared the proper merge message.
+If you need to execute the project, whether through E2E tests or manual checks, do so after the merge commit. Commit any resulting fixes separately.
 
 ## 5. Summarize
 

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._