alignfirst 0.1.0-beta.0

package/dist/skills.js

@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CliError } from "./cli-error.js";
+export const STUB_SKILLS = [
+    "alignfirst",
+    "alspec",
+    "alplan",
+    "al",
+    "alcatchup",
+    "almerge",
+    "alreview",
+    "aldescription",
+];
+export const SKILL_ROOTS = [".agents/skills", ".claude/skills", ".codex/skills"];
+export function findInstalledSkill(home, name) {
+    for (const relativeRoot of SKILL_ROOTS) {
+        const root = join(home, relativeRoot);
+        const skillFile = join(root, name, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        return { root, version: readSkillVersion(skillFile) };
+    }
+    return;
+}
+function readSkillVersion(path) {
+    const content = readFileSync(path, "utf-8");
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)?.[1];
+    if (frontmatter === undefined)
+        return;
+    const metadata = /^metadata:\s*\r?\n((?:^[ \t]+.*(?:\r?\n|$))*)/m.exec(frontmatter)?.[1];
+    if (metadata === undefined)
+        return;
+    return /^\s+version:\s*"?([^"\r\n]+)"?\s*$/m.exec(metadata)?.[1]?.trim();
+}
+export function installStubSkills(ctx, agents) {
+    const skillArgs = STUB_SKILLS.flatMap((skill) => ["--skill", skill]);
+    const agentArgs = agents.flatMap((agent) => ["--agent", agent]);
+    try {
+        execFileSync("npx", [
+            "-y",
+            "skills",
+            "add",
+            "https://github.com/paleo/alignfirst",
+            "--global",
+            "--yes",
+            ...skillArgs,
+            ...agentArgs,
+        ], { cwd: ctx.cwd, env: ctx.env, stdio: "inherit" });
+    }
+    catch {
+        throw new CliError("Failed to install the AlignFirst skills globally.");
+    }
+}

package/dist/version-guard.d.ts

@@ -0,0 +1,8 @@
+import type { ProjectConfig } from "./project-config.js";
+export interface CliRangeResult {
+    range: string;
+    satisfied: boolean;
+}
+export declare function defaultCliRange(version: string): string;
+export declare function checkCliRange(config: ProjectConfig | undefined, installedVersion: string, commandArgs: string[]): void;
+export declare function cliRangeResult(config: ProjectConfig | undefined, installedVersion: string): CliRangeResult | undefined;

package/dist/version-guard.js

@@ -0,0 +1,24 @@
+import semver from "semver";
+import { CliError } from "./cli-error.js";
+export function defaultCliRange(version) {
+    const parsed = semver.parse(version);
+    if (parsed === null)
+        throw new Error(`Invalid installed version: ${version}`);
+    const upper = parsed.major === 0 ? `0.${parsed.minor + 1}.0` : `${parsed.major + 1}.0.0`;
+    return `>=${version} <${upper}`;
+}
+export function checkCliRange(config, installedVersion, commandArgs) {
+    const result = cliRangeResult(config, installedVersion);
+    if (result === undefined || result.satisfied)
+        return;
+    const command = commandArgs.join(" ");
+    throw new CliError(`alignfirst ${installedVersion} is installed; this project requires ${result.range}.\n` +
+        `Run a matching version:  npx -y alignfirst@"${result.range}" ${command}\n` +
+        `Or install it globally:  npm install -g alignfirst@"${result.range}"`);
+}
+export function cliRangeResult(config, installedVersion) {
+    const range = config?.cli;
+    if (range === undefined)
+        return;
+    return { range, satisfied: semver.satisfies(installedVersion, range) };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "alignfirst",
+  "version": "0.1.0-beta.0",
+  "license": "CC0-1.0",
+  "author": "Thomas MUR",
+  "description": "The AlignFirst CLI: protocols, plans and docs in one command.",
+  "keywords": [
+    "alignfirst",
+    "cli",
+    "ai",
+    "agent",
+    "plans",
+    "docmap"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paleo/alignfirst.git",
+    "directory": "packages/alignfirst"
+  },
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "packageManager": "npm@11.19.0",
+  "type": "module",
+  "bin": {
+    "alignfirst": "bin/alignfirst.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@paleo/docmap": "~0.9.1",
+    "arktype": "^2.2.3",
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "@types/node": "~24.13.3",
+    "@types/semver": "~7.8.0",
+    "rimraf": "~6.1.3",
+    "typescript": "~7.0.2",
+    "vitest": "~4.1.11"
+  }
+}

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

@@ -0,0 +1,53 @@
+# Perspective — Correctness
+
+Logic bugs pass linters and compilation; this perspective covers exactly what the tooling cannot.
+
+## Logic and Edge Cases
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| New or modified condition | Are the bounds right? `<` vs `<=`, first and last element, equality case. | 🔴 |
+| Loop over a collection | What happens when it is empty? Does the code after the loop assume it ran at least once? | 🔴 |
+| Access to a field of a possibly absent object | Is the absent case handled, or merely tolerated by the typing? | 🔴 |
+| Missing `else` or `default` branch | Is the uncovered case impossible, or just not considered? If impossible, is it proven (exhaustive type, invariant) or assumed? | 🔴 |
+| Early return added | Does it skip code that had to run — cleanup, logging, release? | 🔴 |
+| Comparison of values that can be zero, empty string, or false | Does the test distinguish "absent" from "present but falsy"? | 🔴 |
+| Money or quantity computation | Floating point where exact decimals are required? Rounding applied once, at the right place? | 🔴 |
+| Date, time, duration | Explicit or implicit timezone? Does the code assume UTC, server time, or user time — and is it the right one? Daylight-saving transitions handled? | 🔴 |
+| Sort, deduplication, object comparison | Is the criterion total and stable? Are two "equal" elements equal in the sense the domain expects? | 🟡 |
+| Collection modified while being iterated | Intentional, and defined behavior for this collection type? | 🔴 |
+| Possible concurrent writes (handler, job, worker) | Can two simultaneous executions interfere? A non-atomic read-then-write is a race condition. | 🔴 |
+| Non-idempotent operation on a retryable path | Does a replay produce a duplicate — double charge, double send? | 🔴 |
+
+## Resilience
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| New network call | Timeout defined? Without an explicit one, the default is often infinite. | 🔴 |
+| Retry policy added | Bounded, with backoff? Is the retried operation idempotent? | 🔴 |
+| Error-catching block added | Is the error handled, or swallowed? A swallowed error turns a loud failure into silent corruption. | 🔴 |
+| Error caught and re-thrown | Is the original cause preserved? | 🟡 |
+| Multi-step operation without a transaction | What remains if step 3 of 5 fails? Is an inconsistent intermediate state visible to another reader? | 🔴 |
+| Batch processing | Does one failing item stop the whole batch? Is that the intended behavior? | 🟡 |
+| Feature flag added | Is the default the old behavior? Is the disabled path tested? | 🟡 |
+
+## Around the Diff
+
+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? | 🔴 |
+| 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? | 🔴 |
+| Documented behavior modified | Do the documentation, comments, or repo instruction files now state something false? | 🟡 |
+
+## Agent-Written Code
+
+Plausible, well-formed code that is wrong about its assumptions. These checks add to the above.
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Call to a library method or option | Does it exist in the **installed version**? Check the manifest, not memory. APIs removed between major versions are the most frequent case. | 🔴 |
+| Clean, complete implementation of the nominal case | Are the failure paths handled? This is the systematic deficit of generated code. | 🔴 |

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

@@ -0,0 +1,22 @@
+# Perspective — Intent
+
+Evaluate the change as a whole: what it tries to accomplish, and whether the implementation is a proper way to accomplish it.
+
+1. Derive the **intent** from the diff: what is this branch trying to accomplish? If the intent cannot be stated in one or two sentences, that is itself a finding.
+2. Describe **how it is done**: the approach taken to implement the intent.
+3. **Assess** the approach:
+   - Is there a simpler design that achieves the same intent?
+   - Does the change fit the architecture and conventions of the codebase, or work against them?
+   - Does it leave the codebase healthier than before?
+   - Is the size proportionate to the intent? Layers, options, and generality nobody asked for cost as much as missing pieces.
+   - Does the diff mix a refactor with a behavior change? If they cannot be told apart, say so — it is what makes a review reliable or not.
+4. Report portions of code that deserve a **rewrite** as findings: 🟡, or 🔴 when the flaw defeats the intent. Observations about the change as a whole belong in the assessment, not in the findings list.
+
+## Report
+
+In addition to the findings, your report must contain:
+
+- **Intent** — one or two sentences.
+- **How it's done** — a short description.
+- **Assessment** — is this the optimal way to implement this intent? Be direct. If yes, say so briefly. If not, explain the better approach.
+- **Verdict** — one of: mergeable as is, mergeable after fixes, needs rework. The verdict replaces the perspective summary.

package/templates/guide/code-review/module-javascript.md

@@ -0,0 +1,80 @@
+# Ecosystem Module — JavaScript and Non-Strict TypeScript
+
+For diffs in JavaScript, or in TypeScript without `strict`. Apply the section matching your perspective, on top of your perspective file.
+
+Without `strict`, the type system verifies little: nullability passes, `any` spreads implicitly. The checks a strict compiler would do become review work — which makes this module larger than the strict one.
+
+<!-- Maintainers: the JavaScript-runtime rows also live in module-typescript-strict.md; keep them in sync. -->
+
+## What the Tooling Covers (all perspectives)
+
+Check what runs in the repo before starting, and skip what is covered: ESLint rules (`eqeqeq`, `no-floating-promises`, …), `checkJs` with JSDoc, the formatter. If a tool is absent, its items belong to the review.
+
+## Correctness
+
+Nullability first — nothing checks it here:
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Property access on a value that can be `null` or `undefined` | Is the absent case handled on every path that reaches this access? | 🔴 |
+| Function parameter assumed present | What happens when a caller omits it? | 🔴 |
+| Index access on an array or record | The element can be `undefined`: is that handled? | 🔴 |
+| Truthiness test on a value that can be `0`, `""`, or `false` | `if (x)` is false for these. Was `if (x != null)` intended? | 🔴 |
+| `??` replaced by `\|\|` or the reverse | `\|\|` triggers on every falsy value, `??` only on `null` and `undefined`. On a number or boolean, the difference is a bug. | 🔴 |
+| `find`, `pop`, `shift`, `at`, `match` | They return `undefined` or `null`. Is that case handled? | 🔴 |
+| `==` used where types can differ | Coercion: `"" == 0` is true. Is `===` intended? Unless ESLint `eqeqeq` covers it. | 🔴 |
+| Arithmetic or concatenation mixing strings and numbers | `"1" + 1` is `"11"`, `"2" * 1` is `2`. Is the conversion explicit? | 🔴 |
+| `typeof x === "object"` | True for `null` too. | 🟡 |
+| `NaN` possible (failed `parseInt`/`Number`, missing field) | `NaN` propagates silently and every comparison with it is false. Checked with `Number.isNaN`? | 🔴 |
+
+Then the runtime pitfalls, shared with strict TypeScript:
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Async function called without `await` or `.catch` | Floating promise: the result is ignored and a rejection surfaces far from its origin. | 🔴 |
+| `await` missing where the result is read | The code manipulates the promise instead of the value. Frequent symptom: an always-true condition. | 🔴 |
+| `async` callback passed to a sync-expecting API (`forEach`, `filter`, `sort`, event handler) | The return is ignored, errors are lost, order is not guaranteed. | 🔴 |
+| `try`/`catch` around an async call | Is the `await` **inside** the `try`? Outside it, the `catch` misses the rejection — unless the rejection is deliberately handled elsewhere. | 🔴 |
+| `await` in a loop | Sequential on purpose, or parallelizable? | 🟡 |
+| `Promise.all` on a collection of unbounded size | Unbounded parallelism: connection exhaustion, rate limiting downstream. | 🔴 |
+| `Promise.all` where partial failure is acceptable — or `allSettled` whose statuses are not inspected | Is the failure mode chosen on purpose? `allSettled` keeps the successes; uninspected, it swallows the failures. | 🔴 |
+| State updated after an async operation (frontend) | The component may be unmounted, or an older response may arrive after a newer one. Cancellation or guard? | 🔴 |
+| `sort()` on numbers without a comparator | Lexicographic: `[10, 9, 1]` becomes `[1, 10, 9]`. | 🔴 |
+| Arithmetic on money | Binary floats have no decimal exactness. Integers in the smallest unit, or a decimal library. | 🔴 |
+| Integer from an external system | JSON deserialization silently loses precision beyond the safe range. | 🔴 |
+| `Date` built from a string | Non-ISO parsing is implementation-dependent. Implicit timezone: client or server? | 🔴 |
+| Copy via `{...x}` or `Object.assign` | Shallow: nested structures stay shared. Is sharing intended, or are they mutated downstream? | 🔴 |
+| Mutation of a received parameter, array, or object | Does the caller expect its value to change? | 🔴 |
+| `JSON.stringify` on an object holding `undefined`, `Map`, `Set`, `BigInt`, or a date | Silent loss, or exception. Can such values actually reach this payload? | 🟡 |
+| Regex with the `g` flag reused | `lastIndex` persists between calls: alternating results. | 🔴 |
+| Regex built from user input | Escaping, and catastrophic backtracking. | 🔴 |
+| `this` in a function extracted or passed by reference | Context lost. | 🟡 |
+| Comparison of objects or arrays | Reference comparison. | 🟡 |
+| Error wrapped in a new one | Is `cause` used to keep the origin? | 🟡 |
+| New import | Is the package in the manifest? Does the imported method exist in the **installed version**? | 🔴 |
+| Import cycle introduced | Depending on evaluation order, a value can be `undefined` at load time. | 🔴 |
+
+## Change Safety
+
+Every boundary is unchecked: no compiler backs the annotations.
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| HTTP response, queue message, file content, `localStorage` consumed directly | Is there runtime validation — schema, predicate, parser — before the fields are used? | 🔴 |
+| Environment variable read | It is `string \| undefined`. Validated at startup, or read ad hoc? | 🔴 |
+| URL, route, or form parameter | Always a string. Is the conversion checked? `Number("abc")` yields `NaN` without an error. | 🔴 |
+| JSDoc types or non-strict TS annotations on external data | They are documentation, not verification. Where is the runtime check? | 🔴 |
+| Import from a deep path of a package | Public API, or implementation detail? | 🟡 |
+
+## Quality
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| In non-strict TS: `as X` or `!` on a value of external origin | The assertion is a promise by the developer, not a verification — and here nothing limits its blast radius. What does it rest on? | 🔴 |
+| In non-strict TS: `any` added | Real dynamic boundary, or surrender? | 🟡 |
+| In non-strict TS: code added that would fail under `strict` | Does it push the repo further away from ever enabling it? | 🟡 |
+| `var` introduced | Function-scoped, hoisted. `let`/`const` unless there is a reason. | 🟡 |
+| Side effect at module load (I/O, global mutation) | Import order becomes behavior. Intended? | 🟡 |
+| Built-in prototype extended or mutated | — | 🟡 |
+| Assertion on a promise without `await` in a test | The test passes no matter what. | 🔴 |
+| Module mock in a test | Does the mock respect the real signature? | 🟡 |

package/templates/guide/code-review/module-python.md

@@ -0,0 +1,77 @@
+# Ecosystem Module — Python
+
+For diffs in Python. Apply the section matching your perspective, on top of your perspective file.
+
+## What the Tooling Covers (all perspectives)
+
+Check what runs in the repo before starting, and skip what is covered:
+
+| Tool | Covers |
+| --- | --- |
+| Ruff / Flake8 | Mutable default argument, bare `except:`, `== None`, unused import or variable |
+| Ruff (`ASYNC`, `S` rules) | Blocking call in async context, common security patterns (`shell=True`, `assert` in production) |
+| mypy / pyright | Inconsistent signatures, unhandled `Optional` — **depending on the configured strictness**; without strict mode, most typing is unchecked |
+| Black / Ruff format | All formatting |
+
+If a tool is absent, its items belong to the review.
+
+## Correctness
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Parameter default that is a list, dict, set, or function call | Evaluated once, at definition: the object is shared across calls. Unless the linter covers it. | 🔴 |
+| Class attribute initialized with a mutable value | Shared by all instances. Intended? | 🔴 |
+| Function defined in a loop, or comprehension capturing the loop variable | Late binding: the function reads the value at call time, not definition time. | 🔴 |
+| List or dict assigned to another variable, then modified | Reference copy, not value. Also watch shallow copies of nested structures. | 🔴 |
+| Truthiness test on a value that can be `0`, `""`, `[]`, `{}` | `if x:` is false for these. Was `if x is not None:` intended? | 🔴 |
+| `is` comparing values (beyond `None`, `True`, `False`) | Identity, not equality. Works by accident on small ints and interned strings. | 🔴 |
+| Collection modified while iterated | Undefined behavior. Iterate over a copy or build a new collection. | 🔴 |
+| Custom objects in a `dict` or `set` | Are `__hash__` and `__eq__` consistent? A mutable object as key is a trap. | 🟡 |
+| `datetime` built without timezone | Naive vs aware comparison raises. `datetime.now()` without a timezone in domain code is almost always a bug. | 🔴 |
+| `except:` or `except Exception:` added | Catches what it should not. Which precise exception is meant? | 🔴 |
+| `except ...: pass`, or `except ...: return None` | Can the caller distinguish "absent" from "failed"? | 🔴 |
+| `try` block covering several operations | Does it catch exceptions from lines other than the one targeted? Narrow it. | 🟡 |
+| Exception caught and re-raised | `raise New(...) from e` keeps the cause; without `from e` it is lost. | 🟡 |
+| `logger.error` in an `except` | `logger.exception` captures the traceback; `logger.error` does not. | 🟡 |
+| `assert` validating an input | Assertions vanish under `-O`. Not a validation mechanism. | 🔴 |
+| `finally` containing `return` or `break` | It silently discards any in-flight exception. Is discarding intended? | 🔴 |
+| `open`, connection, cursor, lock, session acquired without `with` | Released on all paths, including exception and early return? | 🔴 |
+| Custom context manager added | Does `__exit__` release on exception? Does it return a truthy value, swallowing the exception? | 🔴 |
+| Coroutine called without `await` | It never runs, silently. Search for this systematically: the most frequent async bug. | 🔴 |
+| Blocking call in an `async` function (`requests`, `time.sleep`, sync DB call) | Blocks the whole event loop, not just the task. | 🔴 |
+| `asyncio.create_task` without keeping the reference | The task can be collected before completion. Keep the reference, attach error handling. | 🔴 |
+| `asyncio.gather` with `return_exceptions=True` | Are the returned exceptions inspected, or treated as results? Without the flag: one exception cancels the others — intended? | 🔴 |
+| Mutable state shared between tasks or threads | Protected? Non-atomic read-then-write. | 🔴 |
+| `ThreadPoolExecutor` or `multiprocessing` introduced | Are the passed objects serializable? Are worker exceptions retrieved? | 🟡 |
+| `Optional` return added | Do all callers handle the absent case? | 🔴 |
+
+## Change Safety
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Relation accessed in a loop (ORM) | Lazy loading fires per iteration: N+1. Eager loading possible? | 🔴 |
+| Query built with `.format()`, f-string, or concatenation | Parameterize. Allowlist for dynamic identifiers. | 🔴 |
+| `filter` without `limit` on a growing table | Bounded volume? | 🔴 |
+| Session or transaction with a wide scope | Does it contain a network call? Does it close on error paths? | 🔴 |
+| Auto-generated migration | Reviewed? Auto-generation regularly produces unwanted column drops and re-creations. Cross-check with the safety perspective's migration items. | 🔴 |
+| `bulk_*` or mass insertion | Signals, validation, and application-level defaults are bypassed. Intended? | 🟡 |
+| External data (JSON, environment, HTTP response) annotated with a precise type | The annotation is a declaration. Is there runtime validation at the boundary? | 🔴 |
+| `pickle`, `marshal`, `shelve`, `yaml.load` on untrusted data | Arbitrary code execution. `yaml.safe_load` for YAML. | 🔴 |
+| `eval`, `exec`, `compile` with non-constant input | — | 🔴 |
+| `subprocess` with `shell=True`, or command built by concatenation | Pass an argument list. | 🔴 |
+| `os.path.join` with a user-supplied segment | Does the resolved path stay under the base directory? | 🔴 |
+| `random` used for a token, password, or session id | `secrets` for anything cryptographic. | 🔴 |
+| `verify=False`, permissive TLS context | — | 🔴 |
+
+## Quality
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| `Any` introduced in a public signature | Real dynamic boundary, or surrender? | 🟡 |
+| `# type: ignore` added | Targeted at a precise error code, with a comment? | 🟡 |
+| `cast()` used | It rests on a guarantee the checker cannot see. Does that guarantee exist? | 🟡 |
+| `pytest.raises` without `match=` | Verifies that *some* exception of the type is raised, not that it comes from the right place. | 🟡 |
+| Fixture with `module` or `session` scope holding mutable state | State leaks between tests; order-dependent results. | 🟡 |
+| `mock.patch` on an import path | Patched where the target is *used*, not where it is defined? Classic failure: the patch does not take, the test passes while testing nothing. | 🔴 |
+| Bare `Mock()` configured | Accepts any attribute and any call. `autospec=True` or `spec=` constrains to the real contract. | 🟡 |
+| Test depending on `datetime.now`, the filesystem, or the network | Flakiness. | 🟡 |

package/templates/guide/code-review/module-typescript-strict.md

@@ -0,0 +1,84 @@
+# Ecosystem Module — Strict TypeScript
+
+For diffs in TypeScript with `strict` enabled. Apply the section matching your perspective, on top of your perspective file.
+
+<!-- Maintainers: the JavaScript-runtime rows also live in module-javascript.md; keep them in sync. -->
+
+## What the Tooling Covers (all perspectives)
+
+With `strict` active, skip nullability findings on typed values — the compiler handles them. Check which of these are also active, and skip what they cover:
+
+| Setting | If active, skip |
+| --- | --- |
+| `noUncheckedIndexedAccess` | Index access assumed defined |
+| `exactOptionalPropertyTypes` | Absent property vs property set to `undefined` |
+| ESLint `no-floating-promises` | Unawaited promises |
+| ESLint `no-misused-promises` | Promise passed where a boolean or `void` is expected |
+| Formatter (Prettier, Biome) | All formatting |
+
+The limit that shapes this whole module: **the compiler verifies nothing at runtime.** Everything entering the program from outside is typed by declaration, not by verification. That is the main source of bugs that pass compilation.
+
+## Correctness
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Truthiness test on a value that can be `0`, `""`, or `false` | `if (x)` is false for these. Was `if (x != null)` intended? | 🔴 |
+| `??` replaced by `\|\|` or the reverse | `\|\|` triggers on every falsy value, `??` only on `null` and `undefined`. On a number or boolean, the difference is a bug. | 🔴 |
+| `find`, `pop`, `shift`, `at`, `match` | They return `undefined` or `null`. Is that case handled? | 🔴 |
+| Custom type predicate (`x is T`) added | Does the body really verify what the signature claims? A false predicate is a lie the compiler propagates everywhere. | 🔴 |
+| `switch` on a union, without `default` or exhaustiveness check | A future member will pass silently. A `default` assigning to `never` forces a compile error. | 🟡 |
+| Async function called without `await` or `.catch` | Floating promise: the result is ignored and a rejection surfaces far from its origin. Unless ESLint covers it. | 🔴 |
+| `await` missing where the result is read | The code manipulates the promise instead of the value. Frequent symptom: an always-true condition. | 🔴 |
+| `async` callback passed to a sync-expecting API (`forEach`, `filter`, `sort`, event handler) | The return is ignored, errors are lost, order is not guaranteed. | 🔴 |
+| `try`/`catch` around an async call | Is the `await` **inside** the `try`? Outside it, the `catch` misses the rejection — unless the rejection is deliberately handled elsewhere. | 🔴 |
+| `await` in a loop | Sequential on purpose, or parallelizable? | 🟡 |
+| `Promise.all` on a collection of unbounded size | Unbounded parallelism: connection exhaustion, rate limiting downstream. | 🔴 |
+| `Promise.all` where partial failure is acceptable — or `allSettled` whose statuses are not inspected | Is the failure mode chosen on purpose? `allSettled` keeps the successes; uninspected, it swallows the failures. | 🔴 |
+| State updated after an async operation (frontend) | The component may be unmounted, or an older response may arrive after a newer one. Cancellation or guard? | 🔴 |
+| `sort()` on numbers without a comparator | Lexicographic: `[10, 9, 1]` becomes `[1, 10, 9]`. | 🔴 |
+| Arithmetic on money | Binary floats have no decimal exactness. Integers in the smallest unit, or a decimal library. | 🔴 |
+| Integer from an external system | JSON deserialization silently loses precision beyond the safe range. | 🔴 |
+| `Date` built from a string | Non-ISO parsing is implementation-dependent. Implicit timezone: client or server? | 🔴 |
+| Copy via `{...x}` or `Object.assign` | Shallow: nested structures stay shared. Is sharing intended, or are they mutated downstream? | 🔴 |
+| Mutation of a received parameter, array, or object | Does the caller expect its value to change? `readonly` prevents nothing at runtime. | 🔴 |
+| `JSON.stringify` on an object holding `undefined`, `Map`, `Set`, `BigInt`, or a date | Silent loss, or exception. Can such values actually reach this payload? | 🟡 |
+| Regex with the `g` flag reused | `lastIndex` persists between calls: alternating results. | 🔴 |
+| Regex built from user input | Escaping, and catastrophic backtracking. | 🔴 |
+| `catch (e)` | `e` is `unknown`: the thrown value is not necessarily an `Error`. Is `e.message` read without a check? | 🟡 |
+| Error wrapped in a new one | Is `cause` used to keep the origin? | 🟡 |
+| Discriminated error type extended | Do all consumption points handle the new member? | 🔴 |
+| New import | Is the package in the manifest? Does the imported method exist in the **installed version**? | 🔴 |
+| Import cycle introduced | Depending on evaluation order, a value can be `undefined` at load time. | 🔴 |
+
+## Change Safety
+
+The type of external data is a declaration, not a guarantee — the most important point of this module.
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| HTTP response, queue message, file content, `localStorage` typed without validation | Is there runtime validation — schema, predicate, parser? Otherwise the type is a wish. | 🔴 |
+| Environment variable read | Its real type is `string \| undefined`. Validated at startup, or read ad hoc with a `!`? | 🔴 |
+| URL, route, or form parameter | Always a string. Is the conversion checked? `Number("abc")` yields `NaN` without an error. | 🔴 |
+| Validation schema added or modified | Is the type inferred from the schema the source of truth, or does a parallel interface exist that can drift? | 🟡 |
+| Type shared between client and server | Do both sides read the same definition, or two copies? | 🟡 |
+| Import from a deep path of a package | Public API, or implementation detail? | 🟡 |
+
+## Quality
+
+The keywords `as`, `any`, and `!` are the signature of low-quality typing: each one turns off a verification.
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| `as X` on a value of external origin | The assertion is a promise by the developer, not a verification. What does it rest on? | 🔴 |
+| `as unknown as X`, or double assertion | Bypasses the guard against non-overlapping assertions. Almost always a wrong model. | 🔴 |
+| `!` (non-null assertion) added | Does the guarantee really exist, or does it mask an unhandled case? On an environment variable or a search result, almost always the latter. | 🔴 |
+| `any` introduced | Real dynamic boundary, or surrender? `unknown` forces narrowing; `any` disables everything — downstream callers included. | 🟡 |
+| `@ts-ignore` or `@ts-expect-error` added | `@ts-expect-error` fails when the error disappears; `@ts-ignore` never does. Is the reason commented? | 🟡 |
+| Type widened (`string` where a literal union existed, `object`, `{}`, `Function`) | Deliberate loss of precision, or drift? | 🟡 |
+| Return type absent on an exported function | Inference silently propagates a type change to all callers. | 🟡 |
+| Generic type parameter used once in the signature | It constrains nothing and infers nothing: a plain type is simpler. Layered conditional or mapped types deserve the same question. | 🟡 |
+| Domain identifiers typed `string` | Two identifiers of different natures are interchangeable for the compiler. Branded type worth it? | 🟡 |
+| Object literal assigned through an intermediate variable | Excess-property checking only applies to direct literals: a typo passes. `satisfies` keeps both checking and inference. | 🟡 |
+| `as any` in a test to build a value | Does the test still validate the contract, or only the path? | 🟡 |
+| Assertion on a promise without `await` in a test | The test passes no matter what. | 🔴 |
+| Module mock in a test | Does the mock respect the real signature? An untyped mock accepts everything and detects no contract drift. | 🟡 |

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

@@ -0,0 +1,54 @@
+# Perspective — Code Quality
+
+A code review, above all, guarantees that the codebase stays healthy. This perspective is also the one that produces the most noise for the least value: apply it sparingly.
+
+## Repository Conventions
+
+The orchestrator gives you the repo's coding conventions (instruction files, coding-style skills). Flag only explicit violations, citing the rule. Convention adherence is the strongest quality signal available: it is written down, so it is not a matter of taste.
+
+Also check consistency by example: does the new code match its neighbors in structure, error handling, and naming? Correct but mismatched code is a finding.
+
+## Design and Size
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Function clearly larger than its neighbors | Can it be split without forcing? Deep nesting usually marks the split points. | 🟡 |
+| Abstraction introduced with a single implementation | Does it solve a present problem, or an anticipated one? | 🟡 |
+| Boolean parameter added to an existing function | Does the function now do two things? | 🟡 |
+| New file | Is it in the right place per the repo's conventions? | 🟡 |
+
+## DRY and YAGNI
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| New code resembling existing code | Does a repo utility already do this? Verify it exists before proposing a factorization — proposing to extract what already exists is a classic false positive. | 🟡 |
+| Same logic duplicated inside the diff | Extractable into one function? | 🟡 |
+| Dead code, unused import, unreachable branch introduced | — | 🟡 |
+| Export added | Is it imported from anywhere? | 🟡 |
+
+## Suspicious Values
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Fallback to empty string or zero (`?? ""`, `or 0`, …) | Is the empty value really meant, or does it mask an absence that should be handled or raised? | 🟡 |
+| Empty object or empty collection as a default or placeholder | Same question: does it hide an unhandled case? | 🟡 |
+| Unexplained numeric or textual constant | Is its origin guessable? | 🟡 |
+
+## Comments
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Comment describing *what* the code does | Should it describe *why* instead — or be removed? Ask for no comment on clear code. | 🟡 |
+| Comment justifying the current task ("added for X", "now handles Y") | It is noise once merged. | 🟡 |
+
+## Tests
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Behavior change without a test | Is the modified behavior verified anywhere? | 🟡 |
+| Test added | Would it fail if the behavior it claims to verify broke? A test derived from the implementation proves the code does what the code does. | 🔴 |
+| Vague assertion (truthiness, non-null, "does not throw") | Does it check the expected value, or only that something happened? | 🟡 |
+| Test covering only the nominal path | The three most forgotten cases: empty collection, external-call failure, absent value. | 🟡 |
+| 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. | 🔴 |

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

@@ -0,0 +1,62 @@
+# Code Reviewer — Common Rules
+
+You are one of several reviewers examining the same branch, each from a different perspective. Read your perspective file (and ecosystem module, if given), then review the diff. Your final message is your report; the orchestrator merges it with the other reviewers' reports.
+
+## Scope
+
+- Review the changes between the merge-base and HEAD (the orchestrator gives you both): `git diff <merge_base> HEAD`. The review target is the branch as committed.
+- Fresh eyes: derive everything from the code and the diff. Do not read specs, plans, summaries, or any file in the task directory (e.g., under `.plans/`).
+- Read-only: never modify the working tree, the index, or HEAD.
+
+## Method
+
+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.
+
+A signal is a place to look, not a verdict. Answering the question means first understanding what the code is trying to do; a finding is a mismatch between that intent and the actual behavior. A deliberate pattern producing the intended behavior is nothing to report.
+
+## Severities
+
+| Marker | Level | Meaning |
+| --- | --- | --- |
+| 🔴 | Important | Would break behavior, leak data, or block a rollback. Fix before merge. |
+| 🟡 | Nit | Worth fixing, does not block. |
+| 🟣 | Pre-existing | Real bug, present before this diff, in code the diff touches. |
+
+A checklist severity is a ceiling: a 🟡 item never becomes 🔴 without an explicit contextual reason. 🟣 findings are the most valuable of the three — a human reviewer reads the change, not its surroundings — so report them rather than trimming them "to stay in scope".
+
+## The Bar for Reporting a Finding
+
+Report a finding only when all of these hold:
+
+1. **Evidence, not inference.** The claim rests on code you read, cited as `file:line`. A deduction from a function's name is a guess, not evidence.
+2. **Concrete trigger.** You can name the input, state, or call sequence that produces the problem. Without it, you have a worry, not a finding.
+3. **Introduced by this diff.** Otherwise it is 🟣.
+4. **Beyond the tooling.** The formatter, linter, compiler, type-checker, or an existing test would miss it. The orchestrator tells you which tools are active.
+5. **Discrete and actionable.** One precise defect with a fixable remedy, matching the level of rigor of the rest of the codebase.
+6. **The author would fix it** if made aware.
+
+Exception: a high-impact risk (data loss, security) that you could not fully verify may be reported with an explicit uncertainty note.
+
+When in doubt, prefer silence over noise: a wrong finding costs the author a read, a reply, and some trust in the review. Zero findings is a valid outcome. And the converse: continue past the first finding until you have covered your whole perspective.
+
+## What Not to Report
+
+- Anything the formatter, linter, compiler, or type-checker already enforces: formatting, import order, naming style.
+- Personal preferences between equivalent idioms.
+- Generated files, lockfiles, vendored code, snapshots — read them only to check coherence with the rest of the diff.
+- Test coverage as a metric, without a specific unverified behavior.
+- Rephrasing of comments or messages, unless they are wrong.
+
+A pattern repeated N times is one finding with the count, not N findings.
+
+## Report Format
+
+Return your report as your final message:
+
+- One line per finding: severity marker, `path:line` (or `path:start-end`), then one paragraph — what is wrong, why it matters, and the scenario that triggers it. Add a suggested fix when it is not obvious.
+- The first sentence states the defect, in present tense and plain words. Evidence, trigger, and remedy follow, in short sentences.
+- Compare the branch to the base, never commit to commit — how the code got there is noise.
+- Matter-of-fact tone. State the severity honestly; no flattery, no hedging.
+- End with `Perspective summary:` and one sentence.