alignfirst 0.4.0 → 0.6.0-preview.0

package/dist/project-layout.js

@@ -0,0 +1,174 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { type } from "arktype";
+import { CliError } from "./cli-error.js";
+import { errorMessage } from "./errors.js";
+import { gitOutputOrUndefined } from "./git.js";
+export const ITEM_NAMES = [
+    ".alignfirst.json",
+    ".alignfirst.md",
+    "DEVELOPERS.md",
+    "docs",
+    ".plans",
+    "_aligndev",
+];
+const FLAG = "boolean | 'auto'";
+const flagsSchema = type({
+    "+": "reject",
+    ".alignfirst.json?": FLAG,
+    ".alignfirst.md?": FLAG,
+    "DEVELOPERS.md?": FLAG,
+    "docs?": FLAG,
+    ".plans?": FLAG,
+    "_aligndev?": FLAG,
+});
+const companionsSchema = type({
+    "+": "reject",
+    root: "string > 0",
+    paths: type.Record("string", flagsSchema),
+});
+export function layoutOf(ctx) {
+    ctx.layout ??= resolveProjectLayout(ctx.cwd, ctx.home);
+    return ctx.layout;
+}
+export function resolveProjectLayout(cwd, home) {
+    const companion = resolveCompanion(cwd, home);
+    return { companion, locations: resolveLocations(cwd, companion) };
+}
+function resolveCompanion(cwd, home) {
+    const file = readCompanionsFile(home);
+    if (file === undefined)
+        return null;
+    const mainWorktree = findMainWorktree(cwd);
+    if (mainWorktree === undefined)
+        return null;
+    const realHome = realOrResolved(home);
+    const matches = matchingEntries(file, mainWorktree, realHome);
+    if (matches.length === 0)
+        return null;
+    const flags = mergeFlags(matches);
+    assertValidFlags(file, flags, matches);
+    const dir = join(normalizePath(file.root, realHome), companionName(mainWorktree, realHome));
+    return { dir, exists: pathExists(dir), entries: matches.map((match) => match.key), flags };
+}
+function readCompanionsFile(home) {
+    const path = companionsPath(home);
+    if (!pathExists(path))
+        return;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (error) {
+        throw invalidCompanions(path, errorMessage(error));
+    }
+    const file = companionsSchema(value);
+    if (file instanceof type.errors)
+        throw invalidCompanions(path, file.summary.split("\n", 1)[0]);
+    if (!isUserPath(file.root))
+        throw invalidCompanions(path, `root must be an absolute path or start with ~/: ${file.root}`);
+    const badKey = Object.keys(file.paths).find((key) => !isUserPath(key));
+    if (badKey !== undefined)
+        throw invalidCompanions(path, `paths key must be an absolute path or start with ~/: ${badKey}`);
+    return { path, root: file.root, paths: file.paths };
+}
+export function companionsPath(home) {
+    return join(home, ".config", "alignfirst", "companions.json");
+}
+function invalidCompanions(path, detail) {
+    return new CliError(`Invalid ${path}: ${detail}`);
+}
+function isUserPath(value) {
+    return value === "~" || value.startsWith("~/") || isAbsolute(value);
+}
+/** The main worktree is the parent of the common `.git` directory; a bare repository has none. */
+function findMainWorktree(cwd) {
+    const commonDir = gitOutputOrUndefined(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir");
+    if (commonDir === undefined || basename(commonDir) !== ".git")
+        return;
+    return realpathSync(dirname(commonDir));
+}
+function normalizePath(value, realHome) {
+    if (value === "~")
+        return realHome;
+    return realOrResolved(value.startsWith("~/") ? join(realHome, value.slice(2)) : value);
+}
+function realOrResolved(path) {
+    return existsSync(path) ? realpathSync(path) : resolve(path);
+}
+function matchingEntries(file, mainWorktree, realHome) {
+    return Object.entries(file.paths)
+        .map(([key, flags]) => ({ key, path: normalizePath(key, realHome), flags }))
+        .filter((entry) => isSameOrInside(mainWorktree, entry.path))
+        .toSorted((left, right) => right.path.length - left.path.length);
+}
+function isSameOrInside(path, ancestor) {
+    return path === ancestor || path.startsWith(ancestor.endsWith(sep) ? ancestor : ancestor + sep);
+}
+function mergeFlags(matches) {
+    const flagOf = (item) => matches.find((match) => match.flags[item] !== undefined)?.flags[item] ?? "auto";
+    return {
+        ".alignfirst.json": flagOf(".alignfirst.json"),
+        ".alignfirst.md": flagOf(".alignfirst.md"),
+        "DEVELOPERS.md": flagOf("DEVELOPERS.md"),
+        docs: flagOf("docs"),
+        ".plans": flagOf(".plans"),
+        _aligndev: flagOf("_aligndev"),
+    };
+}
+function assertValidFlags(file, flags, matches) {
+    if (flags._aligndev !== true || flags[".plans"] !== "auto")
+        return;
+    const keys = matches.map((match) => match.key).join(", ");
+    throw invalidCompanions(file.path, `"_aligndev": true requires ".plans" set to true or false (matching keys: ${keys})`);
+}
+function companionName(mainWorktree, realHome) {
+    const name = mainWorktree !== realHome && isSameOrInside(mainWorktree, realHome)
+        ? relative(realHome, mainWorktree)
+        : mainWorktree.slice(1);
+    return name.replaceAll("/", "_");
+}
+function resolveLocations(cwd, companion) {
+    const locate = (name) => locateItem(cwd, companion, name);
+    const plans = locate(".plans");
+    return {
+        ".alignfirst.json": locate(".alignfirst.json"),
+        ".alignfirst.md": locate(".alignfirst.md"),
+        "DEVELOPERS.md": locate("DEVELOPERS.md"),
+        docs: locate("docs"),
+        ".plans": plans,
+        _aligndev: companion?.flags._aligndev === true ? companionCopy(companion, ".plans") : plans,
+    };
+}
+function locateItem(cwd, companion, name) {
+    const project = projectCopy(cwd, name);
+    if (companion === null || companion.flags[name] === false)
+        return project;
+    const copy = companionCopy(companion, name);
+    if (companion.flags[name] === true || copy.exists || !project.exists)
+        return copy;
+    return project;
+}
+function projectCopy(cwd, name) {
+    const path = join(cwd, name);
+    return { path, in: "project", exists: pathExists(path) };
+}
+function companionCopy(companion, name) {
+    const path = join(companion.dir, name);
+    return { path, in: "companion", exists: pathExists(path) };
+}
+/** An lstat check, so a broken `.plans` symlink still resolves in place. */
+function pathExists(path) {
+    return lstatSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+/** One line: `<name>: <path> (<in>)`, with `, missing` when absent. */
+export function renderItemLocation(name, location) {
+    return `${name}: ${location.path} (${location.in}${location.exists ? "" : ", missing"})`;
+}
+/** The `_aligndev` tree when it is not the resolved `.plans` and exists. */
+export function separateSessionTree(layout) {
+    const sessions = layout.locations._aligndev;
+    if (!sessions.exists || sessions.path === layout.locations[".plans"].path)
+        return;
+    return sessions.path;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.4.0",
+  "version": "0.6.0-preview.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, work files and docs in one command.",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@alignfirst/docmap": "~0.11.0",
+    "@alignfirst/docmap": "~0.11.1",
     "arktype": "^2.2.3",
     "semver": "^7.8.5"
   },
@@ -44,6 +44,6 @@
     "@types/semver": "~7.8.0",
     "rimraf": "~6.1.3",
     "typescript": "~7.0.2",
-    "vitest": "~4.1.11"
+    "vitest": "~5.0.1"
   }
 }

package/templates/guide/code-review/correctness-reviewer.md

@@ -38,6 +38,7 @@ The most useful findings come from here, because nobody looks for them.
 | Signal | Question | Severity |
 | --- | --- | --- |
 | Function modified | Who calls it? Do callers outside the diff assume the old behavior? | 🔴 |
+| Code, branch or condition removed | What did it handle? Is that case now impossible, handled elsewhere, or silently dropped? | 🔴 |
 | One occurrence of a pattern fixed | Does the same pattern exist elsewhere, unfixed? Report once, with the count. | 🟡 |
 | Code the diff touches contains a bug unrelated to the diff | Report it as 🟣, without requiring a fix in this PR. | 🟣 |
 | Constant, enumeration, or type union extended | Was every place that exhausts it updated? | 🔴 |

package/templates/guide/code-review/quality-reviewer.md

@@ -52,3 +52,4 @@ Also check consistency by example: does the new code match its neighbors in stru
 | Mock added | Does it reproduce the real contract of the dependency, or an idealized version that can never fail? | 🟡 |
 | Test depending on the clock, network, execution order, or shared state | Source of flakiness. | 🟡 |
 | Assertion modified to make a test pass | Was the test fixed, or aligned with a bug? Strong signal: find out why it failed. | 🔴 |
+| Test deleted or skipped | Which behavior stops being verified? Was it fixed, or made to stop failing? | 🔴 |

package/templates/guide/code-review/reviewer-common.md

@@ -10,6 +10,8 @@ You are one of several reviewers examining the same branch, each from a differen
 
 ## Method
 
+Assume nothing works until the code shows it does: your job is to find how this change goes wrong. The bar below decides what you report, not what you look for.
+
 Work signal by signal: each checklist item is a signal/question pair, and applies only when its signal is visible in the diff. This keeps the review on the change, away from a general audit of the repository. A defect in the changed code is a finding even without a matching checklist item.
 
 To answer a checklist question, read the code — including files outside the diff (callers, configuration, the installed version of a dependency). Never guess.

package/templates/guide/core.md

@@ -16,7 +16,7 @@ When the user says there is no ticket or asks for a side ticket, run `{{CMD}} ti
 
 Files use `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`. FILE_PREFIX combines the cycle letter and the file number within that cycle. FILE_NAME includes the prefix and extension.
 
-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.
+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 exactly as printed to get the file path.
 
 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.
 

package/templates/guide/protocols/aad.md

@@ -10,30 +10,37 @@ This is a 4-step protocol. Follow each step in order.
 
 ## 1. Investigate
 
-Check your context for available **documentation** and **skills**. Read every document and skill relevant to any aspect of the task — this is not optional. For each skill, also **read its relevant references**.
+Your context lists the available **documentation** and **skills**. Read every document and skill that applies to any aspect of the task, and the relevant references of each skill. A familiar-looking task tempts you to skip this reading; the project conventions live in these files.
 
-Explore the codebase. Take the time to understand how it currently works and what needs to change.
+Explore the codebase. Take the time to understand how it works today and what needs to change.
 
-Always seek a clean break solution by default. Never consider backward compatibility unless explicitly requested.
+Seek a clean break solution by default. Consider backward compatibility only when the user asks for it.
 
 ## 2. Discuss
 
-Present your findings and proposed approach. Ask clarifying questions. Explore trade-offs and edge cases.
+Nothing is implemented, and nothing is written in TICKET_DIR, before the user agrees. This step is where a small task reveals itself as a large one. It is never skipped.
 
-**Remember**: This discussion happens BEFORE any implementation or formal specification writing.
+The user is a developer who carries the global vision of the project and decides the choices that matter. You carry the details of the code you just read. The discussion keeps the user aware of what you found and hands them every decision worth taking.
 
-Engage in a thorough collaborative discussion covering:
+Manage the reader's attention. Open with the task as you understand it and the approach you propose, in two or three sentences. Then write one block per point that deserves a decision. Write for a reader who has not opened the code today: a function, module or mechanism gets a few words of definition the first time you name it.
 
-- **Problem/Goal exploration**: Present your understanding and ask clarifying questions
-- **Current implementation analysis**: Share what you discovered and ask for confirmation or corrections
-- **Approach evaluation**: Discuss potential solutions and their trade-offs
-- **Edge cases and implications**: Explore potential issues and broader system impacts
+A block is a question and a recommendation:
 
-You're new to this project, the user can guide you.
+```
+❓ **Q1 - <title>**: <the problem in plain words, what the code does today in the words needed to decide, the options with their consequence>
+
+➡️ <your recommendation>
+```
+
+Look for edge cases and impacts on the rest of the system; each one that needs a decision gets its block.
+
+A ❓ is open: the user's answer shapes what you build. When the only answers are go or veto, the block shrinks to a single ➡️ line stating your choice. The more obvious the choice, the shorter the line. Leave out the investigation narrative and the list of files you read.
+
+Settle on your own what the code can answer. Ask the user what needs their judgement: product behavior, scope, priorities, constraints the code does not show. Every ❓ carries a ➡️, so that "fine with all recommendations" is a valid answer. Ask in rounds: a question whose answer depends on another question still open waits for the next round.
 
-Do not use your question tool. Always ask in plain text. Your questions will be the opportunity for a real discussion.
+When there is nothing to decide, say so in a few lines and ask for an explicit go.
 
-**This phase is mandatory.** If there is nothing to discuss, ask the user for an explicit validation.
+Do not use your question tool. Ask in plain text: your questions open a real discussion, a multiple-choice widget closes it.
 
 ## 3. Act
 
@@ -47,7 +54,7 @@ Use subagents (your subagent tool) for distinct, isolated units of work when ben
 
 Finalize the summary file: replace the working notes with the final content described below.
 
-Start the summary with a header, then a suggested commit message {{COMMIT_RULE}}. The shorter the better. Omit any field with nothing to list. Always exclude `alignfirst` from skills.
+Start the summary with a header, then a suggested commit message {{COMMIT_RULE}}. The shorter the better. Omit any field with nothing to list. Exclude `alignfirst` from the skills.
 
 Example:
 
@@ -64,15 +71,15 @@ Used documentation:
 Used skills: `skill-a`, `skill-b`
 ```
 
-The finalized summary is a **very concise handover document** that should capture:
+The finalized summary is a **very concise handover document**. It captures:
 
 - What was the topic or problem
 - What was decided or discovered
-- What action was taken (if any)
+- What action was taken, if any
 - Key outcomes or next steps
 
 The shorter the better.
 
-_Ignore markdown lint errors in the summary file._
+Ignore Markdown lint errors in the summary file.
 
 At the end, give the path of the summary file to the user.

package/templates/guide/protocols/description.md

@@ -24,23 +24,23 @@ Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory c
 [description body]
 ```
 
-Start with a suggested commit message {{COMMIT_RULE}}. Refine it from the suggested commit messages found in the specs and summaries you read. Keep it brief—usually 3-5 words for the description part. Shorter is better when it's clear.
+Start with a suggested commit message {{COMMIT_RULE}}. Refine it from the suggested commit messages found in the specs and summaries you read. Keep it brief, usually 3 to 5 words for the description part. Shorter is better when it stays clear.
 
 ## Guidelines for the Description Body
 
 - Write in markdown:
   - If there is one subject, write a single paragraph.
   - Otherwise, write a bulleted list with one subject per item.
-- **Describe only WHAT was done, never WHY.** Never include explanations, justifications, or reasoning for the changes. Only state what was implemented or modified.
-- **Keep it minimal and functional.** Mention each subject very concisely—just the essentials. Most subjects can be summarized in one sentence of about 5 to 15 words.
-- **Always prefer functional/business descriptions.** Avoid technical implementation details unless absolutely necessary.
-- **CRITICAL: Merge related subjects whenever possible.** Look for opportunities to combine similar changes into a single, cohesive subject. This keeps the description focused and readable.
+- **Describe what was done, never why.** Explanations, justifications and reasoning stay out; the reader gets the result.
+- **Keep it minimal and functional.** Mention each subject very concisely, the essentials only. Most subjects fit in one sentence of about 5 to 15 words.
+- **Prefer functional descriptions.** Technical implementation details appear only when the reader needs them.
+- **Merge related subjects.** A long list of small items is the usual failure of a description; combine similar changes into one cohesive subject.
 - Include technical details only for major structural changes (e.g., renaming a database table, significant linter config changes, major codebase refactors).
-- Do not mention specs that were not implemented. If in doubt, explore the codebase to confirm what was actually done.
-- **Absorb fix-only summaries**: If a summary is about fixing issues introduced by previous summaries in the same ticket (e.g., bug fixes, corrections, adjustments to earlier work), do not mention it as a separate subject. An external reader only cares about the end state.
+- Leave out specs that were not implemented. In doubt, explore the codebase to confirm what was done.
+- **Absorb fix-only summaries.** A summary that fixes issues introduced by earlier work in the same ticket is not a subject of its own. An external reader only cares about the end state.
 
 ---
 
-_Ignore lint errors (formatting issues) in the description file._
+Ignore Markdown lint errors in the description file.
 
 At the end, give the path of the description file to the user.

package/templates/guide/protocols/merge.md

@@ -12,7 +12,7 @@ This protocol applies when a merge or rebase has produced conflicts, or when the
 
 Run `git status` to check for conflicts.
 
-**If there are no conflicts:** start the merge — use the incoming branch if the user provided one, {{BASE_BRANCH_RULE}} If the merge completes cleanly, you are done — no summary file needed. Otherwise, continue with the steps below.
+**If there are no conflicts:** start the merge — use the incoming branch if the user provided one, {{BASE_BRANCH_RULE}} A merge that completes cleanly ends the protocol, with no summary file. Otherwise, continue with the steps below.
 
 ## 2. Investigate
 
@@ -22,9 +22,9 @@ Take the time to understand how things work in the incoming branch and in the cu
 
 Run `{{TICKET_CMD}} --next merge.summary.md` to continue the current cycle. Append FILE_NAME to TICKET_DIR, then immediately create the summary at that path. Log each notable resolution in it as you resolve (see step 5 for the expected content).
 
-Resolve the conflicts properly — preserve both intents whenever possible. Do not blindly accept one side.
+Preserve both intents whenever possible. Accepting one side wholesale is the usual failure of a merge; it silently drops the other branch's work.
 
-Resolve conflicts one at a time. Avoid batch processing, broad search-and-replace operations, and other brute-force edits.
+Resolve conflicts one at a time. Batch processing, broad search-and-replace and other brute-force edits are out.
 
 **Special case for lock files:** If a lock file has conflicts:
 
@@ -41,7 +41,7 @@ If you need to execute the project, whether through E2E tests or manual checks,
 
 Finalize the summary file.
 
-**Keep it lean.** Only document challenging conflicts and the choices made to resolve them. Do not list straightforward resolutions — if everything was trivial, the summary should be almost empty (just a header and a one-line note that there was nothing tricky). Do not include a commit message — git already provides one for merges.
+**Keep it lean.** Document only the challenging conflicts and the choices made to resolve them. Straightforward resolutions stay out: when everything was trivial, the summary is a header and a one-line note that nothing was tricky. No commit message either; Git provides one for merges.
 
 Example:
 
@@ -59,6 +59,6 @@ Example:
 
 Omit any section with nothing to report.
 
-_Ignore markdown lint errors in the summary file._
+Ignore Markdown lint errors in the summary file.
 
 At the end, give the path of the summary file to the user.