@evertonferreira96/agents 0.1.3 → 0.1.5

package/.claude/agents/api.md

@@ -15,12 +15,11 @@ When the change touches SQL, schema, migrations, indexes, seeds or repositories,
 
 ## When invoked
 
-1. Read the brief. If a DoR field (objective, AC, context, deps) is empty, stop and return the gap.
+1. Read the brief. If a DoR field (objective, AC, context, deps) is empty, stop and return the gap. A `Spike: yes` brief (skill `brief`) has no DoR: build only the throwaway it asks for in your own worktree, lint only, no tests, commit on its spike branch, never merge or push.
 2. If `graphify-out/graph.json` exists, query it, then read only the cited files.
 3. Follow the `arch-api` skill and the pattern file named in the brief. Do not invent endpoints, tables or event names.
 4. New integration, table or ownership boundary: stop and ask the orchestrator to run `/architect` first.
-5. Tests: pure rule -> unit; new endpoint -> integration + error mapping; external integration -> contract; incident fix -> regression.
-   Build test-first per the preloaded `tdd` skill, one red-green slice at a time, only at the seams the brief lists (from the plan's Test seams). No seam in the brief: return the gap, do not pick one yourself. A bug with no known cause: call the Skill tool with "diagnosing-bugs" before touching code.
+5. Tests: build test-first per the preloaded `tdd` skill, one red-green slice at a time, only at the seam rows the brief lists, each at its level (e2e, entry, service, repository, unit; where each lives is in the "Níveis de teste (plano)" section of the `arch-api` reference `references/review.md`). The user confirmed those rows at the ticket gate (or the orchestrator took the default levels while the user was away, ADR 0010): they are the pre-agreed seams `tdd` asks for, so never ask for confirmation, and never add a row. No seam in the brief, or the ticket needs a test at a level or interface not listed: return the gap, do not pick one yourself. Run the slow suites (integration, e2e) when the ticket has rows at those levels and the environment allows; say which did not run and why. A bug with no known cause (a diagnosis ticket): call the Skill tool with "diagnosing-bugs" before touching code; its loop goes at whatever seam reaches the bug, and you return that seam as the proposed row for the fix ticket instead of a gap.
 6. Call out idempotency, timeouts, retries and data ownership when touching integrations or state machines.
 7. Run the verification loop. Not done until every applicable check is green.
 8. Work in the worktree named in the brief. Commit only if the brief says Commit: yes, with scoped `git add <paths>`; otherwise leave changes uncommitted for the orchestrator. No push, no PR, no ticket writes.

package/.claude/agents/app.md

@@ -13,14 +13,14 @@ You own the mobile app code. Do not edit API, web or infra files.
 
 ## When invoked
 
-1. Read the brief. If a DoR field (objective, AC, context, deps) is empty, stop and return the gap.
+1. Read the brief. If a DoR field (objective, AC, context, deps) is empty, stop and return the gap. A `Spike: yes` brief (skill `brief`) has no DoR: build only the throwaway it asks for in your own worktree, lint only, no tests, commit on its spike branch, never merge or push.
 2. If `graphify-out/graph.json` exists, query it, then read only the cited files.
 3. Follow the `arch-app` skill and the pattern file in the brief (boundaries, screens, services, env).
 4. Visual work: consume the mobile design system tokens and components. No new UI library, no literal colors. Missing component or token: return it as a gap for `/ui`.
    Motion, gestures, sheets or haptics in the ticket: read `.claude/skills/animate-expo/SKILL.md` (and `apple-design/SKILL.md` for springs, drag, materials) before writing it; these are manual skills, loaded by reading the file. A web view that must feel native on a phone: `mobile-native/SKILL.md`.
 5. Do not invent API payloads; consume the generated client or list backend gaps.
 6. Add or update tests in the repo's existing style.
-   Build test-first per the preloaded `tdd` skill, one red-green slice at a time, only at the seams the brief lists (from the plan's Test seams). No seam in the brief: return the gap, do not pick one yourself. A bug with no known cause: call the Skill tool with "diagnosing-bugs" before touching code.
+   Build test-first per the preloaded `tdd` skill, one red-green slice at a time, only at the seam rows the brief lists, each at its level (e2e, entry, service, repository, unit; where each lives is in the "Níveis de teste (plano)" section of the `arch-app` reference `references/review.md`). The user confirmed those rows at the ticket gate (or the orchestrator took the default levels while the user was away, ADR 0010): they are the pre-agreed seams `tdd` asks for, so never ask for confirmation, and never add a row. No seam in the brief, or the ticket needs a test at a level or interface not listed: return the gap, do not pick one yourself. Run the slow suites (integration, e2e) when the ticket has rows at those levels and the environment allows; say which did not run and why. A bug with no known cause (a diagnosis ticket): call the Skill tool with "diagnosing-bugs" before touching code; its loop goes at whatever seam reaches the bug, and you return that seam as the proposed row for the fix ticket instead of a gap.
 7. Run the verification loop. Not done until every applicable check is green.
 8. Work in the worktree named in the brief. Commit only if the brief says Commit: yes, with scoped `git add <paths>`; otherwise leave changes uncommitted for the orchestrator. No push, no PR, no ticket writes, no store builds.
 

package/.claude/agents/product.md

@@ -1,6 +1,6 @@
 ---
 name: product
-description: Readonly scope agent that turns a request into a plan with outcome, testable acceptance criteria, test seams and DoD before M/L work. Do not use for writing code, infra or tickets.
+description: Readonly scope agent that turns a request into a plan with outcome, testable acceptance criteria, test seams per level and DoD before M/L work. Do not use for writing code, infra or tickets.
 model: opus
 effort: xhigh
 tools: Read, Grep, Glob, Bash
@@ -18,9 +18,10 @@ You are the readonly product/scope agent. You write nothing: you return the plan
 ## 1. Read first
 
 1. The brief, and the ticket when an id is given (`gh issue view` or the text in the brief). Never update or comment on it.
-2. `docs/plans/<task>.md` if the orchestrator already created it at worktree time: keep its title, ticket, size and status.
-3. `GLOSSARY.md`, if present: use its terms throughout the plan, and flag where the request uses a different word for the same thing.
+2. `docs/plans/<task>.md` if the orchestrator already created it at worktree time: keep its title, ticket, size and status. Read its `## Grill record` before anything else in the repo: it is the user's intent as stated in the grill, round by round, with reasons, rejected alternatives and constraints. It outranks the decisions block in the brief, which only summarizes it.
+3. `GLOSSARY.md` (or the context `GLOSSARY.md` that `GLOSSARY-MAP.md` points to), if present: use its terms throughout the plan. A word the request uses for something the glossary names differently, or a domain concept the plan needs that the glossary lacks, goes to the plan's Terms section.
 4. ADRs in `docs/adr/` for the area touched: do not re-litigate them. A request that contradicts an Accepted ADR is an open question, not a decision.
+   A wayfinder map, when the brief names one (`docs/plans/<effort>/map.md`): its Decisions so far, and the tickets they link, are settled like Accepted ADRs; its Out of scope binds your Scope.
 5. The code: entrypoints, modules and existing tests in the area. If `graphify-out/graph.json` exists, query it first and read only the cited files.
 
 ## 2. Build the plan
@@ -32,27 +33,37 @@ Work the sections in this order; each one narrows the next.
 3. **User stories.** For L, or whenever more than one actor is involved. `As an <actor>, I want <feature>, so that <benefit>`. Cover every actor and every path: happy, failure, empty, permission. For M with a single actor, write `n/a` and let the acceptance criteria carry it.
 4. **Acceptance criteria.** Testable checks (given/when/then or checklist). Every story has at least one criterion; every criterion is observable from outside the code.
 5. **Decisions.** Modules built or modified, their interfaces, schema changes, API contracts, specific interactions, product rules the ticket clarified. No file paths and no code: they go stale. One exception: a snippet from a prototype that encodes a decision more precisely than prose (state machine, schema, type shape), trimmed to the decision and marked as coming from the prototype.
-6. **Test seams.** Where the feature will be tested: the public interfaces through which its behavior is observed. Prefer existing seams to new ones, the highest seam that still reaches the behavior, and as few as possible (the ideal is one). For each seam: what it catches, what it misses, and prior art (a similar test already in the repo, or `none`). Implementers run `tdd` against these seams and the verifier checks them.
+6. **Test seams.** Where the feature will be tested, level by level: one row per level and public interface through which its behavior is observed. The levels are `e2e` (the whole flow of a criterion through the running app and a real database), `entry` (one route, controller, Server Action or screen entry: contract, validation, authorization, error codes), `service` (the use case with its ports faked: business rules and decisions), `repository` (the adapters at the boundary: the persistence adapter against a real database, never a mock, and an external-system adapter against recorded responses of that system) and `unit` (pure rules, mappers, schemas, utils: every edge case). Where each level lives in the stack, and how it is written, is in the "Níveis de teste (plano)" section of the `arch-*` testing reference for the stacks touched: `.claude/skills/arch-api/references/review.md`, `.claude/skills/arch-web/references/tests.md`, `.claude/skills/arch-app/references/review.md`; the `repository` level is `.claude/skills/arch-db/references/review.md` section 9.
+   - Default by size, which the ticket gate shows only where you depart from it: M covers every level the change touches, plus `entry` for each route or action it changes; L covers every level, plus one `e2e` per criterion flow (happy path and the one or two failures that hurt most). S has no plan: `/quick` tests at the level of the file it touched.
+   - Each level proves only what no lower level can: rule detail lives in `unit` and `service`, never repeated in `entry` or `e2e`; `entry` asserts contract, validation, authorization and error codes; `e2e` asserts the flow. Fill `Leaves to` with the row that covers what this one does not.
+   - For each row: level, seam, the criteria it proves, what it catches, what it leaves to another row, and prior art (a similar test already in the repo, or `none`). Every criterion has at least one row. Prefer existing seams to new ones.
+   - A level the repo cannot run yet (no e2e runner, no database in tests) is an open question, not a silently dropped row.
+   - Leave `Confirmed: pending`; the orchestrator dates it at the ticket gate. Implementers run `tdd` against these rows and the verifier checks them.
 7. **Tickets.** Break the work into tracer bullets: each ticket cuts a complete vertical path (schema, API, UI, tests), is demoable on its own, fits one agent in one context window, and proves one or more of the seams above. Give each its `Blocked by` edges; a ticket with none can start now. Prefactoring that makes the change easy is its own first ticket. A wide mechanical refactor (rename a column, retype a shared symbol) is not a tracer bullet: sequence it as expand -> migrate in batches -> contract. Name the agent per ticket (`/api`, `/web`, `/app`, `/ui`, `/infra`) and the paths it owns; tickets that can run in parallel own disjoint paths. `/architect` first on any architecture trigger: new domain, integration, storage/ownership, sync/async flow, retry/timeout/fallback, regulatory/ops impact. `/security` before the final commit on any security trigger: auth, secrets, PII, payments, public routes.
-8. **DoR gate.** Each item filled, or flagged as a blocker: outcome, testable AC, dependencies and access (APIs, envs, credentials, other teams), in/out scope, repos and paths, seams, tickets with edges.
+8. **DoR gate.** Each item filled, or flagged as a blocker: outcome, testable AC, dependencies and access (APIs, envs, credentials, other teams), in/out scope, repos and paths, seams with their level and criteria, tickets with edges.
 9. **Open questions.** Missing product facts: states, actors, regions, limits, error behavior. Never fill them with a guess.
+10. **Terms.** Each domain word the plan introduces or uses differently from the glossary: a one- or two-sentence definition of what it is, the synonyms to avoid, and `new` or `conflicts with GLOSSARY.md (<entry>)`. Definitions come from the Grill record, the ticket or the code; one you would have to invent is an open question. `n/a` when the plan uses only glossary terms.
 
 ## Constraints
 
+- Every decision, criterion and out-of-scope item traces to the Grill record, the ticket or the wayfinder map named in the brief. Never reintroduce an alternative the record marks as rejected. Where the code contradicts the record, or the record is silent on something the plan needs, write an open question.
 - No edits, no commits, no ticket writes. Hook `readonly-guard` enforces it.
 - Do not invent product rules, endpoints, tables or events. A missing fact is an open question.
 - Do not interview the user. Questions go in the return block; the orchestrator asks.
 
 ## Return to the orchestrator (max ~2,000 tokens; details in files)
 
-- Plan text in the `docs/plans/README.md` template, every section filled or `n/a` with the reason
+- Plan text in the `docs/plans/README.md` template, every section except Session state and Grill record (the orchestrator owns those) filled or `n/a` with the reason
+- Where the Test seams depart from the default levels for the size, and why
 - DoR gate: pass, or the blocking gaps
 - Open questions for the user
 - The frontier: tickets with no blockers, and which of them can run in parallel
 
 ## Working if
 
+- Each decision in the plan can be traced to a Grill record entry, the ticket or the wayfinder map.
 - The orchestrator can brief every ticket from the plan alone, without asking you anything else.
 - No path appears outside Scope and no code appears in Decisions.
-- Every seam says what it catches and misses; every ticket is demoable on its own.
+- Every seam row names its level, the criteria it proves, what it catches and which row covers what it leaves; every criterion has a row; every ticket is demoable on its own.
+- No assertion is planned at two levels.
 

package/.claude/agents/quick.md

@@ -21,7 +21,7 @@ You apply one small change in one file. Nothing else.
 1. Work in the worktree named in the brief.
 2. Read only the file(s) named in the brief. Do not explore the repo.
 3. Apply the smallest change that solves the request. Match the surrounding style.
-4. Run the repo's lint and the targeted test for that file, if a script exists. Skip a check only when no script exists.
+4. Add or update the test at the level of the file you touched (unit for a rule or util, service for a use case, repository for an adapter), in the style of its neighbor; no new level, no e2e. Run the repo's lint and that targeted test, if a script exists. Skip a check only when no script exists.
 5. Never add dependencies, files, endpoints or tables. If the change needs any of them, or touches a second file or a contract, stop and return `escalate to M` with the reason.
 6. Commit only if the brief says `Commit: yes`, with a conventional commit and a HEREDOC message. Otherwise leave the change uncommitted.
 

package/.claude/agents/ui.md

@@ -21,7 +21,7 @@ You are the design engineer. You own tokens, shared components, DESIGN.md/PRODUC
 
 ## When invoked
 
-1. Read the brief. If DESIGN.md / PRODUCT.md exist, read them. If not, run `/impeccable init` and `/impeccable document` once to create them.
+1. Read the brief. If DESIGN.md / PRODUCT.md exist, read them. If not, run `/impeccable init` and `/impeccable document` once to create them. A `Spike: yes` brief (a wayfinder prototype ticket) skips that setup: read `.claude/skills/prototype/SKILL.md`, build its variants behind the picker in your own worktree, lint only, commit on the spike branch, never merge or push.
 2. Read the token source and the existing components before adding anything.
 3. Palette, typography and style choices: use the `ui-ux-pro-max` search scripts (`python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<query>" --domain <domain> || python .claude/skills/ui-ux-pro-max/scripts/search.py "<query>" --domain <domain>`; `python` is the Windows fallback), then fit results to existing tokens.
 4. Apply `emil-design-eng` principles. Read by situation (file paths under `.claude/skills/`):

package/.claude/agents/verifier.md

@@ -22,14 +22,16 @@ You review on two axes and report them apart, never merged: **Spec** (does the d
 ## Setup
 
 1. Run every command with `cd <worktree> && ...`. Never verify the shared cwd.
-2. Read the plan: AC, Test seams, Tickets, DoD. Read the ticket when the plan names one (read only).
+2. Read the plan: AC, Test seams (with its `Confirmed:` line), Tickets, Terms, DoD. Read the ticket when the plan names one (read only).
 3. Read the diff: `git -C <worktree> diff <base>...HEAD` for committed work, plus `git -C <worktree> status --porcelain` and `git -C <worktree> diff` for uncommitted work. Both count.
-4. Run the repo's lint, build/typecheck and tests yourself. Do not trust pasted output.
+4. Run the repo's lint, build/typecheck and tests yourself, including the slow suites the plan's levels need (`test:integration`, `test:e2e` or the repo's equivalents for `repository`, `entry` and `e2e` rows): the Stop hook runs only the fast suite, so this is where they run, once per task. A suite that cannot run here (no database, no runner) is reported as not run with the reason. Do not trust pasted output.
 
 ## Pass 1: Spec
 
 - Each acceptance criterion against code and tests: met, partial, missing.
-- Each seam in the plan's Test seams table has a test that exercises it through its public interface; a test placed at a seam the plan did not list is a finding too.
+- Each row of the plan's Test seams table has a test at its level that exercises that interface, and each criterion is tested at every level its rows list; a test placed at a level or interface no row lists is a finding too, except a diagnosis loop test, which becomes the fix ticket's row. A level the plan lists whose suite did not run is a finding with the reason.
+- A bug fix: its regression test exists at the seam row the fix ticket lists, or the missing seam is a finding.
+- `Confirmed:` still `pending` under Test seams: report it as unconfirmed seams (the user has not seen the levels), not as Blocked by itself.
 - Behavior the diff adds that no criterion asked for.
 - DoD: diff inside the scoped paths (list any file outside); docs updated when a route, job, store, integration or fallback changed; no secrets, tokens, `.env*` or credentials in the diff.
 
@@ -38,6 +40,8 @@ You review on two axes and report them apart, never merged: **Spec** (does the d
 - Rules: `AGENTS.md`, every `.claude/rules/*.md` whose `paths:` match the diff, and the `review.md` under `.claude/skills/arch-*/references/` for the stacks touched. Cite the rule for each breach.
 - Smell baseline: `.claude/skills/review/references/smells.md`. Each smell is a judgement call, named and quoted; a documented repo rule overrides it.
 - Quality lens: load skill `ponytail-review` (logic, safety, load, tests on risky code, speed, every line needed).
+- Tests: the same assertion at two levels (a lower level already proves it) is a duplicated test; a mock where the level forbids one (`repository` and `e2e` run against a real database) is a breach of the `arch-*` testing reference.
+- Glossary: a name in the diff (type, route, table, event, test name) that contradicts `GLOSSARY.md`, or uses one of its `_Avoid_` words, is a finding citing the entry. A term the plan's Terms section marks `confirmed` counts as settled; one still `new` (the user was away at the gate) is reported as unconfirmed, not as a breach.
 - Skip anything tooling already enforces.
 
 ## Constraints
@@ -51,6 +55,6 @@ You review on two axes and report them apart, never merged: **Spec** (does the d
 - Verdict: Ready / Ready with nits / Blocked (Blocked when either axis has Critical or High, or a check failed)
 - Worktree and base ref verified
 - Commands run with pass/fail and output excerpt
-- Spec: AC coverage per criterion, seam coverage, scope / docs / secrets checks, findings
+- Spec: AC coverage per criterion, seam coverage per row and level (suites not run, with the reason), scope / docs / secrets checks, findings
 - Standards: rule breaches, smells, quality findings
 - Findings most severe first within each axis; no single ranking across axes

package/.claude/agents/web.md

@@ -13,14 +13,14 @@ You own the web app code. Do not edit API, mobile, worker or infra files.
 
 ## When invoked
 
-1. Read the brief. If a DoR field (objective, AC, context, deps) is empty, stop and return the gap.
+1. Read the brief. If a DoR field (objective, AC, context, deps) is empty, stop and return the gap. A `Spike: yes` brief (skill `brief`) has no DoR: build only the throwaway it asks for in your own worktree, lint only, no tests, commit on its spike branch, never merge or push.
 2. If `graphify-out/graph.json` exists, query it, then read only the cited files.
 3. Follow the `arch-web` skill and the pattern file in the brief. Reuse the repo's service, block, form and listing conventions.
 4. Visual work: consume tokens and components from the design system. Do not invent a UI library, literal colors or new primitives. Missing component or token: return it as a gap for `/ui`.
    - Pages used on phones (viewport, notch, tap/hover, input zoom, 100vh): apply `mobile-native`.
 5. Locale, money, dates and id formats match neighboring screens. Do not invent API payloads; list backend gaps.
 6. Add or update tests in the repo's existing style.
-   Build test-first per the preloaded `tdd` skill, one red-green slice at a time, only at the seams the brief lists (from the plan's Test seams). No seam in the brief: return the gap, do not pick one yourself. A bug with no known cause: call the Skill tool with "diagnosing-bugs" before touching code.
+   Build test-first per the preloaded `tdd` skill, one red-green slice at a time, only at the seam rows the brief lists, each at its level (e2e, entry, service, repository, unit; where each lives is in the "Níveis de teste (plano)" section of the `arch-web` reference `references/tests.md`). The user confirmed those rows at the ticket gate (or the orchestrator took the default levels while the user was away, ADR 0010): they are the pre-agreed seams `tdd` asks for, so never ask for confirmation, and never add a row. No seam in the brief, or the ticket needs a test at a level or interface not listed: return the gap, do not pick one yourself. Run the slow suites (integration, e2e) when the ticket has rows at those levels and the environment allows; say which did not run and why. A bug with no known cause (a diagnosis ticket): call the Skill tool with "diagnosing-bugs" before touching code; its loop goes at whatever seam reaches the bug, and you return that seam as the proposed row for the fix ticket instead of a gap.
 7. Run the verification loop. Not done until every applicable check is green.
 8. Work in the worktree named in the brief. Commit only if the brief says Commit: yes, with scoped `git add <paths>`; otherwise leave changes uncommitted for the orchestrator. No push, no PR, no ticket writes.
 

package/.claude/hooks/orchestrator-guard.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# PreToolUse Edit|Write|MultiEdit|NotebookEdit: the main session (no agent_id) writes only docs/plans, docs/adr, docs/README.md, .claude/ and root *.md.
+# PreToolUse Edit|Write|MultiEdit|NotebookEdit: the main session (no agent_id) writes only docs/plans, docs/adr, docs/README.md, .claude/, root *.md
+# and the context glossaries of a multi-context repo (<context>/GLOSSARY.md, <context>/docs/adr/*.md; see skill domain-modeling).
 input=$(cat)
 
 field() {
@@ -43,6 +44,7 @@ rel=${rel#./}
 
 case "$rel" in
   docs/plans/*|docs/adr/*|docs/README.md|.claude/*) exit 0 ;;
+  */GLOSSARY.md|*/docs/adr/*.md) exit 0 ;;
   */*) deny "$rel" ;;
   *.md) exit 0 ;;
   *) deny "$rel" ;;

package/.claude/hooks/post-compact.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# PostCompact / SessionStart(compact): re-inject the newest active plan after context compaction.
+# PostCompact / SessionStart(compact): re-inject the newest active plan after context compaction,
+# and the newest active wayfinder map (docs/plans/<effort>/map.md with Status: active) when there is one.
 input=$(cat)
 
 if command -v jq >/dev/null 2>&1; then
@@ -19,8 +20,23 @@ while IFS= read -r f; do
   plan=$f
   break
 done < <(ls -t "$dir"/*.md 2>/dev/null)
-[ -n "$plan" ] || exit 0
+map=""
+while IFS= read -r f; do
+  grep -Eiq '^status: *active' "$f" || continue
+  map=$f
+  break
+done < <(ls -t "$dir"/*/map.md 2>/dev/null)
+
+[ -n "$plan" ] || [ -n "$map" ] || exit 0
 
-printf 'Re-injected after compaction. Active plan: %s\n' "${plan#$cwd/}"
-head -n 120 "$plan"
+if [ -n "$plan" ]; then
+  printf 'Re-injected after compaction. Active plan: %s\n' "${plan#$cwd/}"
+  head -n 120 "$plan"
+fi
+if [ -n "$map" ]; then
+  [ -n "$plan" ] && printf '\n'
+  rel=${map#$cwd/}
+  printf 'Re-injected after compaction. Active wayfinder map: %s (tickets in %s/decisions/)\n' "$rel" "${rel%/map.md}"
+  head -n 120 "$map"
+fi
 exit 0

package/.claude/hooks/stop-verify.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# Stop: run lint and test before the session may finish, only when the tree has changes.
+# Stop: run lint and the fast test suite before the session may finish, only when the tree has changes.
+# Fast suite: `test:unit` when package.json has it, otherwise `test`. Integration and e2e run once per task in /verifier (ADR 0010).
 input=$(cat)
 
 if command -v jq >/dev/null 2>&1; then
@@ -32,8 +33,12 @@ fi
 log=$(mktemp)
 trap 'rm -f "$log"' EXIT
 
-for script in lint test; do
-  grep -q "\"$script\"[[:space:]]*:" package.json || continue
+has() { grep -q "\"$1\"[[:space:]]*:" package.json; }
+scripts=lint
+if has "test:unit"; then scripts="$scripts test:unit"; elif has test; then scripts="$scripts test"; fi
+
+for script in $scripts; do
+  has "$script" || continue
   if command -v timeout >/dev/null 2>&1; then
     timeout 300 "$pm" run "$script" >"$log" 2>&1
   else

package/.claude/rules/adr.md

@@ -0,0 +1,42 @@
+---
+paths: ["docs/adr/**", "**/docs/adr/**"]
+---
+
+# ADRs
+
+A project's ADRs are its own. The config never ships, overwrites or deletes anything under `docs/adr/`, not even a README (`PROJECT_OWNED` in `scripts/bootstrap.mjs`). This rule is the template and the lifecycle; skills and agents point here.
+
+## Where
+
+- One file per decision: `docs/adr/NNNN-<slug>.md`. Create `docs/adr/` with the first ADR.
+- Multi-context repo (`GLOSSARY-MAP.md` at the root): context decisions live in `<context>/docs/adr/` with their own numbering; system-wide ones in `docs/adr/`.
+
+## Numbering
+
+- `NNNN` is 4 digits, zero-padded, next after the highest existing number (`0001`, `0002`, ...). Never reuse a number.
+- `<slug>` is lowercase kebab-case of the title.
+- ADRs are immutable once Accepted. To change a decision, write a new ADR and set the old one to `Superseded by NNNN`.
+
+## When and how
+
+- Skill `domain-modeling` decides whether a decision earns an ADR (hard to reverse, surprising without context, the result of a real trade-off). This rule decides how it looks and lives, and wins over that skill's `ADR-FORMAT.md`.
+- `/architect` returns an ADR proposal, the orchestrator copies it into `docs/plans/<task>.md`, and at DoD creates the ADR file in the same diff as the change.
+- `Proposed` while grilling or charting a wayfinder map; `Accepted` only with the change that implements it. An Accepted ADR changes only in its Status line; a new ADR supersedes it.
+
+## Template
+
+```markdown
+# NNNN - <title>
+
+Status: Proposed | Accepted | Partly superseded by NNNN (<which part>) | Superseded by NNNN | Deprecated
+Date: YYYY-MM-DD
+
+## Context
+<forces, constraints, the problem; link the plan>
+
+## Decision
+<what we do, in present tense>
+
+## Consequences
+<what gets easier, what gets harder, rejected alternatives and why>
+```

package/.claude/skills/arch-api/references/review.md

@@ -6,6 +6,23 @@ Abra ao escrever testes, ao abrir um domínio novo, ao planejar a migração de
 
 ## 1. Testes
 
+### Níveis de teste (plano)
+
+O plano (`docs/plans/<task>.md`, seção Test seams) declara uma linha por nível e interface; o usuário confirma a tabela no gate de tickets. Nesta stack, cada nível mora aqui:
+
+| Nível do plano | Onde mora | Pega | Deixa para outro nível |
+|---|---|---|---|
+| `unit` | `services/<assunto>.rules.spec.ts`, `common/utils/<tipo>/<nome>.<tipo>.unit.spec.ts` | regra pura: limites, casos de borda | orquestração do caso de uso |
+| `service` | `services/<acao>.service.spec.ts` e `services/<domain>-access.spec.ts`, com port e policy falsos da fixture | regra do caso de uso, `code` de recusa sem escrita, retorno válido contra o schema de resposta, matriz de acesso | SQL e pipeline HTTP |
+| `repository` | `adapters/<tecnologia>.<domain>.repository.adapter.spec.ts`, contra banco real em container (`arch-db` §9); adapter de sistema externo em `common/<capacidade>/adapters/`, contra respostas gravadas desse sistema | SQL, filtro ausente, sort fora da whitelist, paginação, constraint virando `code`, isolamento de tenant; no adapter externo, mapeamento do payload e tradução de erro e timeout | regra |
+| `entry` | `test/e2e/<assunto>.e2e.spec.ts`: uma rota na app Nest inteira | guards, pipes (`.strict()`), filter, status e `code`, rota no documento | regra em detalhe (`service`), SQL (`repository`) |
+| `e2e` | `test/e2e/<fluxo>.e2e.spec.ts`: a sequência de rotas que realiza um critério, com banco real | o fluxo ponta a ponta: caminho feliz e as uma ou duas falhas que mais doem | casos de borda (`unit`, `service`) |
+
+- Cada nível prova só o que nenhum nível abaixo prova; a mesma asserção em dois níveis é teste duplicado.
+- `repository`, `entry` e `e2e` rodam na suíte lenta (`test:integration`, `test:e2e` ou o equivalente do repo), no `/verifier`. O hook de Stop roda só a rápida (`test:unit`, ou `test` quando ela não existe).
+- Repo sem banco nos testes ou sem e2e configurado: o nível vira open question no plano, não linha omitida.
+- O "Mínimo por endpoint" abaixo é o piso de cada nível.
+
 ### Onde fica cada um
 
 ```txt

package/.claude/skills/arch-app/references/review.md

@@ -19,6 +19,21 @@ Antes de escrever teste, confirme o runner: script `test` no app ou no monorepo,
 - Regra que hoje mora inline no service e merece teste: extraia para `domains/` e teste lá.
 - Lacuna de ferramenta ou de script entra no PR com o risco que ficou descoberto; adicionar a ferramenta é decisão separada, com setup e script próprios.
 
+### Níveis de teste (plano)
+
+O plano (`docs/plans/<task>.md`, seção Test seams) declara uma linha por nível e interface; o usuário confirma a tabela no gate de tickets. Nesta stack, os níveis caem nas camadas da tabela acima:
+
+| Nível do plano | Camada | Deixa para outro nível |
+|---|---|---|
+| `unit` | `domains/`, `schemas/`, `common/utils/`, regra de kernel | quem chama e quando |
+| `service` | service da feature, com `authedRequest` e `environment` mockados | a regra pura (`unit`) |
+| `entry` | module / screen com React Native Testing Library | regra e falha da API (`service`) |
+| `repository` | não existe no app: os dados vêm da API, que testa o banco; wrapper de storage fica em `unit`, com o módulo mockado | - |
+| `e2e` | Detox ou Maestro já configurado: o fluxo de um critério no device | casos de borda |
+
+- Cada nível prova só o que nenhum nível abaixo prova; a mesma asserção em dois níveis é teste duplicado.
+- `e2e` roda no `/verifier`, nunca no hook de Stop. Sem Testing Library ou sem Detox/Maestro, o nível vira open question no plano.
+
 Exemplo (domain):
 
 ```ts

package/.claude/skills/arch-db/references/review.md

@@ -136,6 +136,8 @@ Se o repo tem uma pasta de ADRs, siga o formato de lá. Crie ADR quando a decis
 
 ## 9. Testes que o banco exige
 
+É o nível `repository` do plano (`docs/plans/<task>.md`, seção Test seams). Roda na suíte lenta (`test:integration` ou o equivalente do repo), no `/verifier`; o hook de Stop roda só a rápida. Repo sem banco nos testes: o nível vira open question no plano, não mock.
+
 - Integração com banco real (container) para repositório e migration; mock de driver não prova SQL.
 - Migration: `up` em banco limpo, `down`, `up` de novo; e `up` sobre um dump com volume quando a tabela é grande.
 - Concorrência: duas transações disputando a mesma invariante; esperado: uma vence, a outra recebe o `code` de conflito.

package/.claude/skills/arch-web/references/tests.md

@@ -11,6 +11,21 @@ O que testar em cada camada, onde o teste mora e como mockar a fronteira. Runner
 - Fixtures, fábricas e helpers compartilhados em `src/test/`.
 - Os guards (`scripts/check-*.mjs`) fazem parte do gate: estrutura errada falha no `guard`, não na revisão.
 
+## Níveis de teste (plano)
+
+O plano (`docs/plans/<task>.md`, seção Test seams) declara uma linha por nível e interface; o usuário confirma a tabela no gate de tickets. Nesta stack, cada nível mora aqui (o detalhe de cada camada está em "Por camada", abaixo):
+
+| Nível do plano | Onde mora | Pega | Deixa para outro nível |
+|---|---|---|---|
+| `unit` | mappers, schemas, `blocks/<rota>.utils.ts`, `shared/` | regra pura, normalização, cada estado do resolver | quem chama e quando |
+| `service` | service `server-only` (leitura) e passo interno, com a fronteira mockada | 404 por id inválido, sessão, falha mapeada, `cached` x `no-store` | validação e permissão da escrita |
+| `entry` | Server Action (service `'use server'`) com a fronteira mockada; bloco server chamado como função; ilha com Testing Library | validação, `authorization.forbidden`, falha upstream com `code`, sucesso e invalidação; os três `status` do bloco; `fieldErrors` no campo | regra pura (`unit`) |
+| `repository` | não existe no web: a fronteira é o client OpenAPI, e o banco é testado na API | - | - |
+| `e2e` | runner de navegador do repo (Playwright, Cypress) contra a app rodando | o fluxo de um critério na tela: caminho feliz e as uma ou duas falhas que mais doem | casos de borda |
+
+- Cada nível prova só o que nenhum nível abaixo prova; a mesma asserção em dois níveis é teste duplicado.
+- `e2e` roda no `/verifier`, nunca no hook de Stop. Repo sem runner de navegador: o nível vira open question no plano, e adicionar o runner é decisão separada.
+
 ## Por camada
 
 | Camada | Teste | Cobre |

package/.claude/skills/brief/SKILL.md

@@ -9,7 +9,7 @@ Subagents start with empty context: they see only their definition and this brie
 
 ## Gate
 
-Fields 1-4 are the Definition of Ready. If any is empty, do not delegate: call `/product` first.
+Fields 1-4 are the Definition of Ready. If any is empty, do not delegate: call `/product` first. Research and spike briefs (below) have no DoR.
 
 ## Short brief (S only)
 
@@ -19,12 +19,37 @@ For `/quick`. Use the full template below for M/L.
 - Objective: <one sentence>
 - File(s): <exact paths>
 - Change: <1-2 sentences>
+- Test: <the level of the file touched (unit, service, repository) and the test file to add or update>
 - Worktree: <absolute path of the task worktree>
 - Commit: no
 - DoD: lint + targeted test green
 - Return: max 500 tokens
 ```
 
+## Research brief (wayfinder research tickets, any fact-finding)
+
+For a read-only `Explore` subagent: no worktree, no DoR, no files written.
+
+```markdown
+- Question: <the fact a decision waits on>
+- Sources: primary only (official docs, source code, specs, first-party APIs); <where to start, if known>
+- Do not investigate: <settled areas>
+- Return: findings with a source for every claim, open points, under 2k tokens. Write no files.
+```
+
+## Spike brief (wayfinder prototype or task tickets)
+
+For `/ui` or the owning implementer. A spike answers a question; it is throwaway, so it has no AC, seams or DoR and skill `tdd` does not apply.
+
+```markdown
+- Spike: yes
+- Question: <what the prototype or task must show>
+- Shape: <UI variants behind the picker (skill prototype) | single-file logic demo | the manual step to perform>
+- Worktree: own (isolation: worktree) | Branch: spike/<effort>-<NN> | Commit: yes
+- Rules: lint only, no tests; never merged, never pushed; no secrets in the branch
+- Return: branch, how to run it (one command), what it shows, under 1k tokens
+```
+
 ## Template (M/L)
 
 ```markdown
@@ -54,10 +79,14 @@ For `/quick`. Use the full template below for M/L.
 ## 6. Constraints & tools
 - <rules, skills to load, commands allowed, no new libraries, no new tables, etc.>
 - Vocabulary: <terms from GLOSSARY.md this ticket touches, with their one-line definitions>
+- Test seams (<confirmed by the user at the ticket gate on <date> | defaults taken by the orchestrator, user away (ADR 0010)>; either way they are the pre-agreed seams skill `tdd` requires, so do not ask anyone to confirm them):
+  - <S#> <level> - <seam (public interface)> - proves <ACs> - leaves to <S#>
+  Test only at these rows, each at its level. A test this ticket needs at a level or interface not listed: stop and return it as an open question; never add a row yourself. Exception: a diagnosis ticket (bug with no known cause) builds its `diagnosing-bugs` loop at whatever seam reaches the bug and returns that seam as the proposed row for the fix ticket.
 
 ## 7. Definition of Done
 - [ ] lint, build/typecheck and tests green, output pasted (last lines)
-- [ ] a test exists at every seam listed in docs/plans/<task>.md (Test seams)
+- [ ] a test exists at every seam row above, at its level; no assertion repeated at two levels
+- [ ] the fast suite green; the slow suites (integration, e2e) run when the ticket has rows at those levels and the environment allows, else say which did not run and why
 - [ ] diff only inside the paths in scope
 - [ ] docs updated in the same diff when a route, job, store, integration or fallback changed
 - [ ] no secrets, tokens or `.env*` in the diff
@@ -79,7 +108,7 @@ For `/quick`. Use the full template below for M/L.
 ## Notes
 
 - One brief per agent. Parallel agents get disjoint paths.
-- `Commit: no` with `Worktree: <task-wt>` for sequential work; `Commit: yes` with spawn isolation `worktree` for parallel scopes. See skill `orchestrate` section 6.
+- `Commit: no` with `Worktree: <task-wt>` for sequential work; `Commit: yes` with spawn isolation `worktree` for parallel scopes. See skill `orchestrate` section 8.
 - Paste only what the agent needs; link files instead of pasting them.
 - For `/verifier`: pass only `Worktree`, `Base ref`, the DoD and the plan path. No implementation narrative.
 

package/.claude/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/.claude/skills/domain-modeling/GLOSSARY-FORMAT.md

@@ -0,0 +1,60 @@
+# GLOSSARY.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `GLOSSARY.md` at the repo root.
+
+**Multiple contexts:** A `GLOSSARY-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Glossary Map
+
+## Contexts
+
+- [Ordering](./src/ordering/GLOSSARY.md): receives and tracks customer orders
+- [Billing](./src/billing/GLOSSARY.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/GLOSSARY.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `GLOSSARY-MAP.md` exists, read it to find contexts
+- If only a root `GLOSSARY.md` exists, single context
+- If neither exists, create a root `GLOSSARY.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.