@mastra/factory 0.16.0-alpha.9 → 0.16.1-alpha.0

package/factory-skills/factory-review/references/archaeology.md

@@ -0,0 +1,225 @@
+# Archaeology — command recipes
+
+Zero judgment in this file. These are known-working command shapes; adapt them to the repository and preserve only decisive evidence in the review record.
+
+**Shell notes.** `gh` output can carry ANSI codes that break `jq`; use `gh`'s built-in `--jq` or prefix with `NO_COLOR=1`. `timeout` is not a command on macOS. Quote paths with spaces.
+
+## Resolve the PR before prediction
+
+```bash
+# Accepts a number, URL, or branch. Keep the first query minimal.
+gh pr view <pr> --json number,title,body,author,baseRefName,url,closingIssuesReferences \
+  --jq '{number,title,author:.author.login,base:.baseRefName,url,issues:[.closingIssuesReferences[]?.number],body}'
+```
+
+`baseRefName` is the comparison branch; it may not be `main`. Extract the problem statement from `body` and ignore implementation/change-list sections until after the pre-diff model is written.
+
+Owner/repo for later calls:
+
+```bash
+gh repo view --json nameWithOwner --jq .nameWithOwner
+```
+
+## Open the PR after the pre-diff model
+
+```bash
+# Resolve the head now that isolation is over
+gh pr view <pr> --json headRefName,headRefOid --jq '{head:.headRefName,headSha:.headRefOid}'
+
+# Changed files
+gh pr view <pr> --json files --jq '.files[] | "\(.path)\t+\(.additions) -\(.deletions)"'
+
+# Commit list
+gh pr view <pr> --json commits --jq '.commits[] | "\(.oid[0:8])  \(.messageHeadline)"'
+
+# Reviews and review-thread comments (with resolved state)
+gh api graphql -f query='
+  query($owner:String!,$repo:String!,$pr:Int!){
+    repository(owner:$owner,name:$repo){ pullRequest(number:$pr){
+      reviews(first:50){ pageInfo{hasNextPage endCursor} nodes{ author{login} state submittedAt body } }
+      reviewThreads(first:100){ pageInfo{hasNextPage endCursor} nodes{ isResolved isOutdated path line
+        comments(first:20){ pageInfo{hasNextPage endCursor} nodes{ author{login} createdAt body } } } }
+    }}}' -F owner=<owner> -F repo=<repo> -F pr=<pr>
+# Follow pageInfo.hasNextPage/endCursor on reviews, reviewThreads, and comments until
+# exhausted — a truncated history reads as complete and re-raises omitted findings.
+
+# PR-level (issue) comments
+gh api repos/<owner>/<repo>/issues/<pr>/comments --paginate --jq '.[] | "\(.user.login) \(.created_at)\n\(.body)\n---"'
+
+# CI status
+gh pr checks <pr> 2>&1 || true
+```
+
+If GraphQL is rate-limited, the REST equivalents (all with `--paginate`): `gh api repos/<owner>/<repo>/pulls/<pr>/files`, `.../pulls/<pr>/commits`, `.../pulls/<pr>/reviews`, `.../pulls/<pr>/comments` (review comments; no resolved state via REST — note that). Check quota with `gh api rate_limit --jq '.resources | {core:.core.remaining, graphql:.graphql.remaining}'`.
+
+## Linked issues (step 2)
+
+```bash
+gh issue view <n> --json number,title,body,author,state,labels,comments \
+  --jq '{number,title,author:.author.login,state,labels:[.labels[].name],body,comments:[.comments[] | {author:.author.login,body}]}'
+```
+
+Also scan the PR body for `#NNN`, `fixes`, `closes`, `resolves` — `closingIssuesReferences` only catches the formally linked ones.
+
+## Base-branch worktree before prediction
+
+```bash
+git fetch origin <base>
+git worktree add /tmp/review-base-<pr> origin/<base>
+```
+
+A clean existing base checkout is also fine. Do not open the PR head until the pre-diff model is written.
+
+## Head and diff after prediction
+
+```bash
+# Fork heads are not on origin/<head>; fetch the PR ref and pin the worktree to the head SHA
+gh pr view <pr> --json headRefOid --jq .headRefOid   # <sha>
+git fetch origin refs/pull/<pr>/head
+git worktree add --detach /tmp/review-head-<pr> <sha>
+git -C /tmp/review-head-<pr> diff origin/<base>...HEAD --stat
+git -C /tmp/review-head-<pr> diff origin/<base>...HEAD
+```
+
+## History — when relevant
+
+```bash
+# Recent history of each core file (last 20 commits, not the whole log)
+git log --oneline -20 origin/<base> -- <file>
+
+# Who wrote the changed lines, in what commit (run on the base worktree against the pre-PR lines)
+git blame -L <start>,<end> origin/<base> -- <file>
+
+# From a blame SHA to its PR
+gh pr list --search "<sha>" --state merged --json number,title,url --jq '.[]'
+# or
+gh api "repos/<owner>/<repo>/commits/<sha>/pulls" --jq '.[] | {number,title,html_url}'
+```
+
+Read the originating PR's description and review thread. That's where the reason lives.
+
+## History — deep (on trigger)
+
+```bash
+# When was a string introduced or removed
+git log -S "<exact string>" --oneline origin/<base> -- <path-or-dot>
+
+# Reverts touching the area
+git log --oneline origin/<base> --grep="^Revert" -- <path>
+
+# The reverted attempt itself
+gh pr view <n> --json title,body,reviews,comments
+
+# Closed-unmerged PRs with the same idea (strongest precedent signal)
+gh pr list --search "<feature terms> is:closed is:unmerged" --state closed --limit 20 --json number,title,closedAt,url --jq '.[]'
+
+# Issues describing the same symptom under other words
+gh issue list --search "<symptom terms>" --state all --limit 20 --json number,title,state,url --jq '.[]'
+```
+
+## Related PRs and issues (when overlap or precedent could matter)
+
+```bash
+# Open PRs touching the same files (merge-order risk)
+gh pr list --state open --limit 50 --json number,title,files --jq '.[] | select(.files[].path | test("<path-fragment>")) | {number,title}'
+
+# By feature/function name, open and closed
+gh pr list --search "<term>" --state all --limit 20 --json number,title,state,url --jq '.[]'
+gh issue list --search "<term>" --state all --limit 20 --json number,title,state,url --jq '.[]'
+```
+
+Search terms: the feature name, the file path, the function names touched, the error message from the issue.
+
+## Callers
+
+```bash
+# Every reference to a changed symbol, on the PR branch
+git grep -nE "\b<symbol>\b" -- '*.ts' '*.tsx' '*.js'
+
+# Including string references (config keys, docs, dynamic imports)
+git grep -n "<symbol>" -- ':!*.lock'
+
+# Near-twin helper search: grep for the *verb* and the *shape*, not the name
+git grep -nE "function (with|create|make)?[A-Za-z]*(Retry|retry)" -- 'packages/*.ts'
+```
+
+Classify every hit: callers to account for versus definitions, comments, documentation, and string references. Read each match before treating it as a caller — a search that also hits the definition or a doc is not evidence of a caller.
+
+## Test on base — when needed
+
+Use this only when code reasoning cannot establish whether the regression evidence would fail without the fix and the answer would materially affect confidence. Never replace production files in the current checkout with base versions. Use a disposable worktree; if it cannot be prepared cleanly, stop rather than falling back to modifying the live checkout.
+
+```bash
+ROOT=$(git rev-parse --show-toplevel)
+HEAD=$(gh pr view <pr> --json headRefOid --jq .headRefOid)
+git fetch origin refs/pull/<pr>/head   # fork heads are not on origin/<head>
+MB=$(git merge-base origin/<base> "$HEAD")
+WT="${TMPDIR:-/tmp}/review-tob-<pr>-$$"
+test ! -e "$WT" || exit 1
+git -C "$ROOT" worktree add "$WT" "$MB"
+cd "$WT"
+
+# Only the test files the PR added or modified (a deleted path does not exist at $HEAD)
+git diff --diff-filter=AM "$MB"..."$HEAD" --name-only -- '**/*.test.*' '**/*.spec.*' '**/__tests__/**' > .test-files
+test -s .test-files || { echo "no test files changed — nothing to run"; }
+xargs -a .test-files git checkout "$HEAD" --
+
+# Build what the tests need, using the repo's documented shape (AGENTS.md / CONTRIBUTING). Do not improvise build commands.
+# Inspect package.json scripts and lockfiles first; run everything with GH_TOKEN and GITHUB_TOKEN unset (the PR's code runs here).
+# Then run only those files, keeping the test command's own exit status (pipefail so tail cannot mask a failure):
+set -o pipefail
+test -s .test-files && env -u GH_TOKEN -u GITHUB_TOKEN xargs -a .test-files pnpm vitest run --reporter=dot --bail 1 2>&1 | tail -40
+
+cd "$ROOT"
+git worktree remove --force "$WT"
+```
+
+Expected: red. Green means the test doesn't catch the regression — that's a finding, not a success. Record the decisive assertion, not the full output.
+
+## Run the thing (public-api, behavior-change, docs)
+
+A scratch project that consumes the package through its public export, not source imports. Build the package per the repo's documented command first (send build output to a separate log, not the transcript). This executes the PR's code: inspect its scripts and lockfile first and run with GH_TOKEN and GITHUB_TOKEN unset.
+
+```bash
+mkdir -p /tmp/review-run-<pr> && cd /tmp/review-run-<pr>
+# link or install the workspace package, write a 10-line script that exercises the claim, run it
+env -u GH_TOKEN -u GITHUB_TOKEN node demo.mjs 2>&1 | tee /tmp/review-run-<pr>/with.txt
+```
+
+For behavior changes, run the same script against a base build into `without.txt`. Summarize the observed difference in the review record; retain transcripts only when they help reproduce it.
+
+## Changeset
+
+```bash
+git diff origin/<base>...HEAD --name-only -- .changeset/
+cat .changeset/*.md   # on the branch; read the level and the packages
+```
+
+## CODEOWNERS / who likely knows
+
+```bash
+# Owners for the touched paths
+grep -n "<path-fragment>" .github/CODEOWNERS 2>/dev/null
+# Or the people who've touched the file most recently
+git shortlog -sn --since="1 year ago" origin/<base> -- <file> | head -5
+```
+
+Name a person under **Open questions**, not "someone."
+
+## Long memory — recovery searches
+
+| Memory      | What the reviewer "just knows"                      | Recover from                                                                                                                                                                                                         |
+| ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Decisions   | "We chose X over Y because…"                        | Originating PRs (blame → PR), nearest AGENTS.md, design docs, `git grep -nE "because                                \| workaround \| don't  \| see #" -- <files>` near the changed lines                             |
+| Scars       | "Last time someone touched this it broke Z"         | `git log --grep="^Revert" -- <path>`; test names that encode bugs (`git grep -nE "should not                        \| regression \| double \| race" -- <test files>`); `gh issue list --search "<area> regression"` |
+| Users       | "Half the community calls this with a string"       | `git grep -n "<api>" -- examples/ docs/`; `gh issue list --search "<api>"`; call sites in the repo                                                                                                                   |
+| Conventions | "We always go through the storage abstraction here" | The sibling feature; the three closest public neighbors; the package `CHANGELOG.md` for recent movement in the area                                                                                                  |
+
+## Cleanup
+
+```bash
+git worktree remove --force /tmp/review-base-<pr> 2>/dev/null
+git worktree remove --force /tmp/review-head-<pr> 2>/dev/null
+```
+
+Leave the handoff artifact in place so a re-review can reuse the recorded design and earlier findings.

package/factory-skills/factory-review/references/categories/README.md

@@ -0,0 +1,34 @@
+# Category pages
+
+One page per common PR category. After recording your own design and before opening the diff, load the pages relevant to the problem. As the actual change reveals additional categories, load those pages before reviewing their portions in depth. Do not skip relevant pages because the main skill seems sufficient. Use their review focus, traps, and approval criteria; reading is required, while checks are selected according to the change and its risks. Every page has the same shape:
+
+- **Reviewing** — the _object_ under review. It's not the diff; it's a causal claim, an interface, an equivalence proof, a set of numbers. Same diff format, different thing under scrutiny.
+- **Read first** — what to read before the diff. Reading the diff first is the wrong first move for almost every category.
+- **Done means** — what has to be true for you to approve. This is the bar the category contributes.
+- **Trap** — the characteristic way this category fools a reviewer. Knowing the trap is most of the page's value.
+- **Attention** — where scrutiny goes. Some categories are 80% interface / 20% implementation; some the inverse.
+- **Questions** — the activated subset of the question bank, written out.
+- **Signals → branches** — when you see X, do Y. Opens only when the signal fires.
+- **Verify** — useful ways to falsify the important claims. Recipes in `../archaeology.md`.
+
+Consider every entry below against the behavior, compatibility boundaries, and failure modes the change touches, not just the PR's headline category. These pages contain broadly useful review knowledge; their names are not exclusive labels, and the triggers below are examples, not exclusions. If a page could plausibly help, err on the side of reading it. Reading more guidance does not require running every check it describes.
+
+PRs are often mixed. Keep materially different conclusions separate. "Should be split" is a finding when mixing makes a portion harder to review than it would be alone; do not average distinct conclusions into one.
+
+| Page                      | Reviewing                                         | When relevant                                                                                                                              |
+| ------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mechanical.md`           | That it's _only_ that                             | Renames, formatting, generated files, lockfiles, or version bumps whose noise could hide substantive changes.                              |
+| `bug-fix.md`              | A causal claim                                    | Correctness fixes, regressions, defensive patches, or claims that an observed symptom is resolved.                                         |
+| `behavior-change.md`      | Impact on everyone who relied on the old behavior | Changed defaults, ordering, thresholds, errors, retries, or other observable behavior—even with no API signature change.                   |
+| `internal-capability.md`  | Architectural fit                                 | New internal mechanisms or integration with existing layers, hooks, registries, or lifecycle handling.                                     |
+| `public-api.md`           | The interface                                     | New or changed public signatures, options, return types, errors, exports, or cross-package APIs.                                           |
+| `refactor.md`             | An equivalence proof                              | Moved or restructured code, replaced implementations, or cleanup that claims to preserve behavior—even inside a feature or fix.            |
+| `schema-storage.md`       | Irreversibility and the upgrade path              | Persisted data, migrations, wire/config formats, or compatibility between independently upgraded packages—even without a schema migration. |
+| `performance.md`          | Numbers                                           | Performance claims, hot-path changes, caches, allocations, or work that grows with input size.                                             |
+| `infra-tooling.md`        | Blast radius on every developer                   | Build/CI/scripts, install or release behavior, dependencies, published files, or package exports.                                          |
+| `security.md`             | Completeness                                      | Untrusted input, permissions, secrets, filesystem/network trust boundaries, or vulnerability fixes—not just security-labeled PRs.          |
+| `docs.md`                 | Truth                                             | Changed docs or examples, or API/behavior changes that could leave existing documentation false.                                           |
+| `tests-only.md`           | Whether they'd catch anything                     | New, changed, weakened, or removed tests, mocks, fixtures, or shared test helpers—even alongside production changes.                       |
+| `revert.md`               | That it's clean and the reason is recorded        | Full or partial reversions, manual undoing of earlier work, or rollback changes with dependent work still present.                         |
+| `large-cross-cutting.md`  | Whether it should be one PR                       | Multiple concerns, packages, or architectural boundaries; mixed changes whose interactions or structure make review difficult.             |
+| `experimental-flagged.md` | Isolation                                         | Experiments, feature flags, opt-in execution paths, or claims that disabling a feature leaves existing behavior untouched.                 |

package/factory-skills/factory-review/references/categories/behavior-change.md

@@ -0,0 +1,36 @@
+# Behavior change (no new API)
+
+A default, an ordering, a threshold, a format, a timing — something existing users observe changes, without a new surface.
+
+**Reviewing:** impact on everyone who relied on the old behavior.
+**Read first:** the callers and consumers of the changed thing — on the base, before the diff.
+**Done means:** every affected caller is accounted for; the changeset level matches (a changed default is breaking); a changelog line exists that a user would understand.
+**Trap:** labeled `patch`; nobody grepped the callers.
+**Attention:** the consumers, not the change. The change is usually small; the blast radius isn't.
+
+## Questions
+
+- **Who relied on the old behavior?** Grep every consumer — in the repo, in `examples/`, in docs, in issues that mention the API. The author fixed it for their case.
+- **Was the old behavior a decision or an accident?** `blame` the lines, open the originating PR, read why. If it was a decision, the PR must argue with it, not replace it. If the author doesn't know it was a decision, they haven't.
+- **What happens to existing users on upgrade?** Walk it: a user on the previous version with existing config/code/data updates. What silently changes? Silent behavior changes are worse than errors — nothing tells the user.
+- **Is the changeset level honest?** A `patch` that changes a default is a breaking change wearing a disguise.
+- **What would the changelog line say?** If a user reading it wouldn't know whether they're affected, it's not written yet.
+- **Does the description match the code?** Behavior changes are the most common thing smuggled into PRs labeled "fix" or "refactor."
+- **Is there a compatibility path?** A flag, a deprecation window, an opt-in — or is it a hard cut? If hard, is that justified?
+- **Cross-package.** If the changed behavior is observed across a package boundary, what does the other side see when only one of them upgrades?
+- **In-flight work.** Other open PRs that depend on the old behavior.
+
+## Signals → branches
+
+- Category was triaged as "bug fix" but the diff changes a default/order/threshold → re-categorize; the description undersells scope — finding
+- Changeset says `patch` → check whether any consumer's observable output changes; if yes, request the correct level before merge
+- Originating PR explains the old behavior → deep history; the PR must engage with that reasoning
+- No caller grep in the description → do it; every hit is a question
+
+## Verify
+
+- **Run it, before and after.** Write a minimal script that exercises the changed behavior through the public surface. Run on base (old behavior) and on the branch (new), then record the decisive difference.
+- Grep callers/consumers on the branch: `archaeology.md` → Callers.
+- `git blame -L` the changed lines on the base; open the originating PR.
+- `ls .changeset/` and read the level.
+- `gh pr list --search` for open PRs touching the same files.

package/factory-skills/factory-review/references/categories/bug-fix.md

@@ -0,0 +1,37 @@
+# Bug fix
+
+**Reviewing:** a causal claim — "X was the cause, and this removes it."
+**Read first:** the issue and its repro → the test → the diff. Never the diff first.
+**Done means:** you believe the cause; the fix lives at the cause; the evidence distinguishes the regression from working behavior.
+**Trap:** symptom patch; "why now" unanswered.
+**Attention:** the cause, not the code. The code is judged by whether it addresses the cause you independently arrived at.
+
+## Questions
+
+- **Where does the value first become wrong?** The tell is _where_ the fix lives relative to where the bug was _observed_. A fix at the observation site — a null check where it crashed, a `?.`, a re-sort before display, a retry around the failing call — is almost always a symptom patch. Ask _why_ was the value null / out of order / failing, and follow the data backwards until you find where it _became_ wrong. That's where the fix belongs.
+- **Does this make the bug impossible, or just unobserved here?** If the same bad state can reach another consumer, it's a patch.
+- **Why now?** Bugs have a cause. Either the code was always wrong (then why did it work before — what assumption changed?) or something changed (which commit — `git log -S`, bisect). A real fix can name the cause. "It was broken so I made it not broken" can't.
+- **Does your theory match theirs?** Your prediction included your own theory of the cause. If the author's fix is somewhere other than where your theory says the value goes wrong, one of you is wrong, and finding out which is the review's first job.
+- **Is the fix more defensive, or more correct?** More checks, more fallbacks, more catch blocks — correct code has fewer branches, not more. A fix that adds branches is a symptom patch until proven otherwise.
+- **Did the fix turn a loud failure into a silent one?** A swallowing try/catch or a masking default that makes the symptom disappear without fixing the state.
+- **Would the test have failed before the fix?** For a bug fix this is the central test question. Establish the counterfactual from the assertion and base implementation; code reasoning is enough when the answer is deterministic. Green on base means the test proves nothing, but executing on base is useful only when the answer remains uncertain.
+- **Does the test name match the claim?** "Fixes ordering under concurrent writes" → is there a test with concurrent writes, or one write that checks order? The gap between claim and test scope is where the bugs live.
+- **What does the assertion actually assert?** `toBeDefined()`, `toHaveBeenCalled()`, `not.toThrow()` pass for almost any implementation. A real test asserts the specific value or behavior.
+- **Is the code under test the real code?** If the thing being fixed is mocked out, the test is testing the mock.
+- **Who else calls the changed function?** The author fixed it for their caller. Do the others still work?
+
+## Signals → branches
+
+- Fix lives at the observation site (null check, `?.`, retry, re-sort) → trace the data backwards to where it becomes wrong; that's the finding
+- Fix adds branches rather than removing them → symptom patch until proven otherwise
+- Description can't name the cause, only the symptom → "why now" is unanswered; go deep on history
+- Old, stable code → deep history; something changed, find the commit
+- Test asserts weakly or mocks the fixed module → run test-on-base; expect it to be green (i.e. useless)
+- The same pattern (e.g. the same null check) appears in more than one place in the diff → the fix is at the consumers, not the source
+
+## Verify
+
+- **test-on-base** (`archaeology.md` → Test on base): use it when the regression test is central and code reasoning cannot establish whether it distinguishes the bug—for example, weak assertions, mocked paths, concurrency, integration behavior, or multiple code paths that could satisfy it. Green means it does not distinguish the regression; whether that blocks depends on what other evidence proves the fix.
+- Use `git log -S "<removed or changed string>"` when a deletion or condition change has unclear history.
+- Account for callers whose behavior could change.
+- If the issue has a useful repro, run it on base and on the branch and record the observed difference.

package/factory-skills/factory-review/references/categories/docs.md

@@ -0,0 +1,32 @@
+# Docs
+
+**Reviewing:** truth. Not prose quality — whether the claims match the code.
+**Read first:** the code the docs describe, on the base (or on the branch if the docs accompany a code change).
+**Done means:** material claims match the code; new or changed examples run; nothing that was true is now stated falsely.
+**Trap:** reviewing prose quality instead of correctness.
+**Attention:** examples and API claims. Adjectives don't matter; signatures, defaults, and behavior do.
+
+## Questions
+
+- **Does each claim match the code?** Every "defaults to X," "returns Y," "throws when Z" — find the line that makes it true. Docs drift from code silently and the drift is what users hit.
+- **Do the examples run?** Copy each example into a scratch file, run it against the package. An example that doesn't compile is worse than no example.
+- **Is anything now stale?** If the docs accompany a code change, what _else_ in the docs referenced the old behavior? Grep the docs tree for the old name/default.
+- **Does it describe what, or why?** "Set `foo` to enable bar" is what. Users need "set `foo` when X; leave it off when Y because Z." Missing _why_ isn't a correctness failure, but it's the difference between docs that get read and docs that get skipped.
+- **Would a user find it?** Is it in the place a user would look — next to its siblings, linked from the index?
+- **Is it complete for the surface?** A new option documented without its interaction with existing options; an error case not mentioned.
+- **Terminology.** Same terms as the rest of the docs and the code? A doc that calls it a "session" when the code says "thread" creates a support ticket.
+- **Prose only if it's wrong.** Typos and phrasing are nits at most. Don't spend the review on them.
+
+## Signals → branches
+
+- Example with an import → run it; imports are where examples rot first
+- A default or return type stated → find it in the code; if you can't in 30 seconds, it's probably wrong
+- Docs accompany a rename or default change → grep the whole docs tree for the old term
+- New feature docs with no mention of failure modes → check whether the feature has any; if it does, request that they be documented
+
+## Verify
+
+- Run new or changed examples in a scratch project through the public package surface; sample unchanged examples only when broad edits create uncertainty.
+- For each material default/return/throw claim, find the supporting code.
+- `grep -rn "<old term>" docs/` on the branch if anything was renamed.
+- If the docs site has a build (`pnpm build` in the docs package), run it — broken links and MDX errors surface there.

package/factory-skills/factory-review/references/categories/experimental-flagged.md

@@ -0,0 +1,34 @@
+# Experimental / behind a flag
+
+**Reviewing:** isolation. The bar on polish is lower; the bar on containment is higher.
+**Read first:** the flag boundary — where the flag is checked, and everything on the "off" side of it.
+**Done means:** off by default; zero effect when off; removable without surgery; a plan for graduating or deleting it.
+**Trap:** the flag leaks — "off" still changes something; "temporary" code that stays forever.
+**Attention:** the off path. The on path is experimental by declaration; the off path is production.
+
+## Questions
+
+- **Is it actually off by default?** Find the default. Find every place the flag is read. Config, env var, constructor option — one of them defaulting to on is a leak.
+- **Zero effect when off?** Trace the off path. New imports still load; new constructor args still validate; new fields still serialize. Any of these is an effect when off.
+- **Where is the flag checked?** One place (good) or scattered through the codebase (each check is a place the flag can be forgotten)?
+- **Is it removable?** When the experiment ends, can the flag and the off-path be deleted in one PR without touching unrelated code? If the flag check is woven into existing logic, it isn't.
+- **Is there a plan?** Graduation criteria, an owner, a date, or an issue. "Temporary" without a plan is permanent.
+- **Does the on path get the normal review?** Lower polish bar, not zero. Security and data-integrity questions still apply — an experiment that corrupts data is still corruption.
+- **Public surface.** Does the flag itself become public API? If users can set it, removing it later is a breaking change.
+- **Tests.** Both paths tested? The off path especially — it's what everyone runs.
+- **Docs.** Is it documented as experimental, or documented as if stable?
+
+## Signals → branches
+
+- Flag read in more than ~3 places → request consolidation so the flag can be removed cleanly
+- Off path has new imports / side effects at module load → leak; request isolation before merge
+- Flag exposed in public config with no "experimental" marking → it's public API now; changeset and docs questions apply
+- No tracking issue / no owner → request one, and ask for the removal plan
+- Experiment touches storage or wire format → load `schema-storage.md` regardless of the flag; data written under the experiment outlives it
+
+## Verify
+
+- **Run the off path** on the branch with the flag unset; diff observable behavior against base. It should be identical; record any meaningful difference.
+- Grep every read of the flag: `grep -rn "<flag name>"` on the branch — count and list.
+- Confirm the default with a pointer.
+- Tests: `grep -n "<flag>" <test files>` — both branches exercised?

package/factory-skills/factory-review/references/categories/infra-tooling.md

@@ -0,0 +1,37 @@
+# Infra / build / CI / tooling
+
+Build config, CI workflows, lint/format config, scripts, dev tooling, monorepo plumbing, release machinery.
+
+**Reviewing:** blast radius on every developer and every future PR.
+**Read first:** what happens to someone who pulls this tomorrow — a fresh clone, a stale branch, a rebase.
+**Done means:** testable before merge; rollback is clear; the change can't break `main` for everyone on landing.
+**Trap:** works on the author's machine.
+**Attention:** the failure modes on machines that aren't the author's — CI runners, fresh clones, Windows, older Node, no network.
+
+## Questions
+
+- **Who does this hit?** Every developer, every CI run, every release? Or one package's tests? Blast radius sets the depth.
+- **Can it be tested before merge?** CI changes are notoriously only testable by merging. Did the author run it on a branch? Is there output?
+- **What's the rollback?** A revert is enough — unless the change also mutated caches, lockfiles, generated files, or published something.
+- **Fresh clone.** Does `pnpm install && pnpm build` still work from nothing? Does a stale branch rebased onto this break in a way the error message explains?
+- **Lockfile changes.** Are they explained? A lockfile diff with no dependency change in `package.json` is a question.
+- **Determinism and platform.** Path separators, shell (`sh` vs `bash` vs `zsh`), `timeout` doesn't exist on macOS, GNU vs BSD flags, case sensitivity, line endings.
+- **Secrets and permissions.** CI workflows that gain a token or a permission scope. Least privilege?
+- **Speed.** Does this add minutes to every CI run? Cache behavior?
+- **Does it change what gets published?** Build output, exports map, `files` in package.json — the most silent breakage there is.
+- **Is it the documented shape?** AGENTS.md / CONTRIBUTING describe how to build and test. Does this change keep them true, or do the docs need to change with it?
+
+## Signals → branches
+
+- Workflow file changed with no evidence it ran → ask for the run link; without it, `inferred`
+- Lockfile changed alone → find the cause; unexplained lockfile churn is a finding
+- Build output or exports map touched → this is a packaging change; verify with `pnpm pack` and a consumer install
+- Shell script uses bash-isms or GNU flags → platform finding
+- Cache key changed → check both the hit path and the miss path
+
+## Verify
+
+- **Fresh-clone install and build** in a temp worktree when install/build behavior is part of the claim: use the repository's documented command shape and record the decisive result.
+- If a workflow changed, find the run for this branch in `gh run list --branch <head>` and read it.
+- If packaging changed: `pnpm pack` the affected package, install the tarball into a scratch project, import the public entry.
+- Run the script on macOS if the author is on Linux, or note that you couldn't.

package/factory-skills/factory-review/references/categories/internal-capability.md

@@ -0,0 +1,35 @@
+# New internal capability (no public surface)
+
+**Reviewing:** architectural fit.
+**Read first:** the closest sibling feature, side by side with the new one.
+**Done means:** uses the same primitives and layers as the sibling; hooks into what it should; nothing reinvented.
+**Trap:** reinvented wheel; bypassed layer.
+**Attention:** the seams — where the new code touches the existing system. The internals of the new code matter less than what it goes through and around.
+
+## Questions
+
+- **Find the sibling.** Whatever this does, something similar exists. Read how _it_ does it. Same primitives, or a second event bus / retry loop / cache / helper that exists three directories over? Reinvention is the #1 sign of not knowing the internals.
+- **Trace one call end-to-end.** Main entry point to the bottom, every layer. It should go through what everything else goes through (validation, logging, tracing, storage abstraction) rather than around. The bypass is invisible in the diff — it's the _absence_ of a call — so you have to trace, not read.
+- **What should it have hooked into?** Lifecycle hooks, middleware, processors, registries, cleanup. Capability that doesn't register is invisible to observability, plugins, teardown.
+- **Which existing code did the author model this on?** A good answer names a file. No answer means they didn't look.
+- **Should this exist, and here?** Do we want to own this? Does it belong in this package, this layer? Would an example or a plugin have served?
+- **Is it over-built?** Abstraction with one caller, options no caller sets, a registry for two entries, indirection between two things that could talk directly. What does it buy _today_?
+- **What does this assume, and where is it enforced?** "Always called after init," "never concurrent." Name it; find the enforcement.
+- **Resource lifecycle.** Handles, listeners, timers, subscriptions, child processes — everything opened must be closed. Leaks don't show in tests.
+- **What will the next PR in this area need?** Does this make it easier or harder? Abstractions that fit one use case make the second worse.
+- **Tests as spec.** Cover the implementation, read only the tests — can you reconstruct what it does? Tests of implementation details ("calls internal helper with args") break on refactor and catch no bugs.
+
+## Signals → branches
+
+- A helper/utility added that has a near-twin in the repo → grep for the twin; request consolidation; two implementations of one thing will diverge
+- Entry point doesn't pass through the layer the sibling does → request routing through the layer before merge unless the author can justify the bypass
+- No sibling exists → the "should this exist" question gets more weight, and the design review is on you — compare against the three closest things anyway
+- "Extensible," "pluggable," "generic" in the description → over-built check
+- Opens something (listener, timer, stream) with no matching close → trace teardown
+
+## Verify
+
+- Compare the sibling's entry point with the new one; record only divergences that affect the review.
+- Trace the layers the sibling's call passes through and confirm the important ones on the new path with pointers.
+- Grep for near-twin helpers: `archaeology.md` → Callers / twin search.
+- If it's exercisable without a public surface (internal test harness, existing example), run it.

package/factory-skills/factory-review/references/categories/large-cross-cutting.md

@@ -0,0 +1,35 @@
+# Large / cross-cutting
+
+Many packages, many concerns, or simply too big to review in one sitting.
+
+**Reviewing:** whether it should be one PR at all.
+**Read first:** the structure — the file list grouped by package and by kind of change — not the content.
+**Done means:** either split into reviewable units, or reviewed as a series with a design doc or plan up front, each unit under its own category's rules.
+**Trap:** reviewing 3,000 lines in one sitting and calling it done.
+**Attention:** the structure and the seams between concerns. Content review happens per-unit, after the structure question is settled.
+
+## Questions
+
+- **How many independent changes are in here?** Group the file list by concern. Each group that could land on its own is a candidate PR. Independent changes in one PR get one review's attention divided by N.
+- **Can it be reviewed in one sitting?** If you can't, you're not reviewing it — you're skimming it. That's the honest answer, and it's the finding.
+- **Is there a plan or design doc?** Large changes without a stated design are a design review disguised as a code review. Ask for the design; review that first.
+- **What's the merge risk?** How long has this been open; how far has the base moved; how many in-flight PRs touch the same files.
+- **Which parts are which category?** A large PR is always mixed. Triage each portion: the refactor part, the API part, the fix part. Each gets its own page and its own bar.
+- **Is the size the problem, or the scope?** 2,000 lines of generated code is mechanical. 2,000 lines of hand-written changes across five packages is scope.
+- **Can it be reviewed as a stack?** If the author can't split, can the commits be reviewed in order as if they were a stack? Only if the commits are clean units.
+- **What does "approve" mean here?** You cannot vouch for 3,000 lines. Be explicit about what you reviewed deeply and what you skimmed — in the handoff and, if posted, in the review comment.
+
+## Signals → branches
+
+- File list spans >2 packages with different kinds of change → "should be split" finding; propose the split
+- No design doc and the description is a change list → needs discussion; ask for the design before the code
+- Commits are "wip," "fix," "more" → cannot be reviewed as a stack; split is the only path
+- Commits are clean units → review in commit order; each commit under its own category
+
+## Verify
+
+- Group `git diff <base>...HEAD --stat` by concern and propose a split when it would improve reviewability.
+- Use `git log --oneline <base>..HEAD` to assess whether commits are reviewable units.
+- Verify high-risk units under their relevant category guidance.
+- Search for in-flight PRs touching the same paths when merge-order risk is plausible.
+- Be explicit about what you reviewed deeply and what you did not; no arbitrary line threshold determines sufficiency.

package/factory-skills/factory-review/references/categories/mechanical.md

@@ -0,0 +1,36 @@
+# Mechanical
+
+Typo, formatting, lockfile, version bump, dependency bump, generated code, rename-only.
+
+**Reviewing:** that it's _only_ that.
+**Read first:** the file list and the line count. Not the content.
+**Done means:** CI green; nothing else in the diff; the generated output matches the generator.
+**Trap:** something real hiding in 2,000 lines of generated noise.
+**Attention:** the parts that aren't mechanical. Find them, or confirm there are none.
+
+## Questions
+
+- **Is every hunk the same kind of change?** A formatting PR with one hunk that isn't formatting. A rename with one hunk that changes a default. Scan for the odd one out; that's the whole review.
+- **Line count vs. what the change should need.** A version bump that touches 40 files — why? A typo fix that touches a lockfile — why?
+- **Generated code: does it match the generator?** Regenerate and diff. Hand edits to generated files are a finding.
+- **Dependency bump: what changed in the dependency?** Read the dependency's changelog between the two versions. A "patch" bump can carry a behavior change. A major bump is not mechanical — re-categorize.
+- **Lockfile: is the diff explained by the `package.json` diff?** Unexplained lockfile churn is a question.
+- **Rename: every caller?** A rename that misses a string reference (config key, docs, error message, a dynamic import) breaks silently.
+- **Does CI actually cover it?** Formatting changes in files CI doesn't lint; generated files CI doesn't regenerate.
+
+## Signals → branches
+
+- One hunk that isn't the same kind as the rest → re-categorize that hunk under its real category; the mixing is itself a finding (it hid a real change in noise)
+- Dependency major bump → not mechanical; load `behavior-change.md` and read the dependency's migration guide
+- Generated file with no generator run in the commit list → regenerate and diff
+- Rename with fewer callers updated than the grep finds → request the missing callers before merge
+
+## Verify
+
+- Categorize every hunk by kind: `git diff <base>...HEAD --stat` then skim each file's diff for the odd hunk.
+- Generated code: run the generator on the branch; `git status` should be clean.
+- Dependency bump: `gh api repos/<dep-owner>/<dep-repo>/releases` or the package's CHANGELOG for the range; note anything behavioral.
+- Rename: grep the old name repo-wide on the branch, including docs, config, and string literals.
+- CI green: `gh pr checks`.
+
+Most mechanical PRs produce a handoff of Triage + Verdict. That's correct, not lazy.

package/factory-skills/factory-review/references/categories/performance.md

@@ -0,0 +1,33 @@
+# Performance
+
+**Reviewing:** numbers.
+**Read first:** the benchmark and its input shape — before the code change.
+**Done means:** before/after measured on a representative input; behavior unchanged; the win is where the description says it is.
+**Trap:** faster on a toy input; correctness quietly changed to get the number.
+**Attention:** the measurement first, then equivalence. A perf PR is a refactor with a number attached — it has to pass the refactor bar _and_ show the number.
+
+## Questions
+
+- **What's n in production?** Not "is it O(n)" — what's the real input size and shape? A win at 50 items that regresses at 50k, or vice versa, is a loss.
+- **Is this the hot path?** An extra allocation per token matters; in setup it doesn't. Conversely, an optimization off the hot path is complexity for nothing.
+- **What was measured, how, on what?** Wall clock? Allocations? Under load? Cold or warm? One run or many? Was the baseline measured the same way, on the same machine, same session?
+- **Did behavior change?** Perf PRs remove work. Was any of that work load-bearing — an ordering guarantee, a validation, a flush? Apply the refactor questions: tests unchanged, deletions justified.
+- **Is the complexity worth the number?** A 3% win that adds a cache with invalidation logic is a net loss in maintenance. Ask what the number _buys_ a user.
+- **Does the win survive the real environment?** Node version, bundler, the actual storage backend, network in the loop.
+- **Caches and memoization.** Invalidation, memory growth, key collisions, behavior when the cache is cold.
+- **Is there a simpler win?** Sometimes the measured bottleneck is one line away from a trivial fix and the PR built a subsystem around it.
+
+## Signals → branches
+
+- No numbers in the description → the claim is unverified; ask for the benchmark or run one
+- Numbers but no input description → run at 10× and 100× the likely input; report both
+- Tests changed → re-categorize as behavior change; the number may have been bought with correctness
+- A cache or memo introduced → invalidation and memory questions; look for the test that exercises invalidation
+- "Should be faster" without measurement → inferred; not a perf PR until measured
+
+## Verify
+
+- **Reproduce the measurement** on base and branch with the same harness and input. `hyperfine` works for CLI-shaped things; a scripted loop can measure library calls. Record the method and material result.
+- **Scale the input** to production shape and re-run.
+- Refactor verification: tests untouched (`git diff <base>...HEAD --stat -- '**/*.test.*'` empty), suite green.
+- If a cache was added: write a case that invalidates and confirm behavior.