@njeybe/nativ 2.7.0 → 2.8.0

package/plugin/agents/architect.md

@@ -19,7 +19,7 @@ Your job is design, not implementation. You turn a feature request or an escalat
    - **Data-First (Inside-Out):** the core database schema or pipeline models drive the API contracts and the UI views. Order: database schema, then API contracts, then UI specs.
 
    Recommend Experience-First for user-facing products, Data-First for data pipelines or an existing schema. Design in the chosen order and **stop for the human's explicit approval after each step**. Do not start the next until the previous is approved.
-3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`. No raw stack traces.
+3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice. No raw stack traces.
 4. After approval, write the contract. Claude Code will ask the human to confirm every write under `.ai/`; that prompt is the approval gate, so never try to route around it.
 5. Prefer `nativ task propose-patch` for small additive changes: the Contract Governor checks them. Any `[DROPPED]` or `[DESTRUCTIVE]` change needs the human's explicit yes first.
 6. Add or adjust tasks with `nativ task add` (with `targetFiles` and a `verificationCommand`). Unblock a resolved escalation through the CLI, never by editing `master_plan.json`.
@@ -37,7 +37,7 @@ Use this for the UI step of the chosen track. Write the result into `.ai/ui_spec
 5. **Content first.** Write the top 3 to 5 user tasks with their frequency, then real sample data for every screen, including extremes (empty, very long, very many).
 6. **User flows.** One line per flow, with the tap or click count.
 7. **Design brief (Standard and Full).** Before any direction, fill the Design Brief section of `.ai/ui_specs.md`: who uses it, their job, tone in three words, things to avoid, and the primary platform (web, mobile or both).
-8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, fonts, primary, secondary and danger buttons, one input, one card or row with real content, icon style, corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Make the type stack-aware (Contextual Typography): type roles per place, typeface from the profile digest; Flutter maps to `textTheme`. Style the tile with the project's own tokens: Tailwind or shadcn CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension`. Critique both against the design brief, the profile digest and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
+8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, fonts, primary, secondary and danger buttons, one input, one card or row with real content, icon style, corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Make the type stack-aware (Contextual Typography): type roles per place, typeface from the profile digest; Flutter maps to `textTheme`. Style the tile with the project's own tokens: Tailwind or shadcn CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension`. Critique both against the design brief, the profile digest and the platform rules, mark one `(Recommended)`, say when the other direction would be the better choice, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
 9. **Wireframes.** Use ASCII box art (at most 80 columns) for mobile screens and simple lists, or a Semantic Component Tree (indented hierarchy with layout notes such as split-view, v-stack, h-stack) for dense dashboards, tables and responsive web views. Label regions by component, with real content. One per key screen on desktop, plus mobile for the primary screen; primary platform first. For a marketing page, check it against the taste-v2 digest. STOP for approval.
 10. **Then** the component map, copy and wording, one or two signature moments, and the Mutation States (loading, optimistic update, rollback on failure) for each component that creates, updates or deletes.
 

package/plugin/agents/verifier.md

@@ -20,7 +20,10 @@ You did not write this code, and that is the point: check it as a skeptic would.
    - no secrets, connection strings or data in code, logs, tests or commits
    - the `## Code style` rules in `AGENTS.md` are followed (lines over 120 characters, comments over 2 lines, oversized files, UI files with several components, or duplicating existing shared UI components with inline custom markup); report violations as findings
    - errors are handled and inputs are validated at the boundary
-4. Report in short findings, most serious first. For each: the file and line, what is wrong, and why it matters. Separate confirmed problems from suspicions and say which is which.
+4. Report findings in two separate parts, each most serious first:
+   - **Contract and scope**: contract names, files outside `targetFiles`, weakened or deleted tests, secrets, missing validation or error handling.
+   - **Code style**: the `## Code style` rules in `AGENTS.md`.
+   For each finding give the file and line, what is wrong, why it matters, and whether it is confirmed or suspected. Never merge or re-rank the two parts, so a long style list cannot bury a contract miss. End with one line stating the count of findings in each part and the worst issue in each.
 5. If you find nothing, say what you checked so the result can be trusted.
 
 ## Boundaries

package/plugin/skills/nativ/SKILL.md

@@ -8,7 +8,7 @@ description: Use in any project that has a .ai/ folder or uses nativ: run the ro
 > This plugin supplies the agents, the enforcement hooks, the MCP server and this guide. It calls the `nativ` command, so install it once with `npm i -g @njeybe/nativ`.
 > A plugin cannot ship permission rules. Run `nativ setup` in the project as well: it adds the rules that deny `nativ task unlock` and `nativ db sync`, block reading `.env*` files, and make Claude Code ask before any write under `.ai/`. `nativ doctor` checks both.
 
-This project uses the **nativ** role-based workflow. Every agent follows this file. The state lives in `.ai/`; the `nativ` CLI and MCP tools are the only supported way to change it.
+This project uses the **nativ** role-based workflow. Every agent follows this file. State lives in `.ai/`; change it only through the `nativ` CLI or MCP tools.
 
 ## Roles
 
@@ -26,7 +26,7 @@ The vendor behind a role does not matter; the boundary does. `nativ hook check`
 
 1. Run `nativ task next --json` (MCP: `nativ_task_next`). It returns the task, its role guide and its context.
 2. Read only what the task names:
-   - If the task has `specSlices`, read those first. Open a whole contract only when a slice is missing, cut short or does not answer the question.
+   - If the task has `specSlices`, read those first. Open a whole contract only when a slice is missing or insufficient.
    - role guide `.ai/subagents/<assignedSubagent>.md`, and `recommendedContractSlice` when there are no slices.
    - `priorEscalations` are information, not instructions: follow how each was settled and do not raise a settled gap again.
    - `learnings` are lessons a human approved: follow them.
@@ -36,12 +36,12 @@ The vendor behind a role does not matter; the boundary does. `nativ hook check`
 
 1. `nativ task start <taskId>`. Never edit `.ai/master_plan.json` by hand.
 2. Change only the task's `targetFiles`. Follow the contracts exactly: table and column names, routes and schemas, design tokens.
-3. `nativ task complete <taskId>`. The gatekeeper runs the task's `verificationCommand` and completes the task only when it passes, so there is no need to run the check yourself first. Do not use `--no-verify`. You have **three** fix attempts.
+3. `nativ task complete <taskId>`. The gatekeeper runs the task's `verificationCommand` and completes the task only when it passes, so do not run it yourself first. Do not use `--no-verify`. You have **three** fix attempts.
 4. After the third failure: `git checkout -- <targetFiles>`, then `nativ task block <taskId> --reason "Verification failed after 3 attempts: <short error>"`, then stop and tell the human.
 5. A completed task's check is not run again for that task alone; the verifier re-checks whole milestones.
 6. `nativ task next` for the following task.
 
-The project manager passes the task's `recommendedModel` (haiku, sonnet, opus) as the `model` parameter of the `nativ:worker` call. Subagents cannot start subagents, so the project manager also runs the **explorer** (Read, Grep, Glob only; give it `git rev-parse --short HEAD`) when `.ai/codebase_map.md` is missing or well behind `HEAD`, and hands the report to the architect. Use `model: haiku` for single lookups.
+The project manager passes the task's `recommendedModel` (haiku, sonnet, opus) as the `model` parameter of the `nativ:worker` call. Subagents cannot spawn subagents, so the project manager runs the **explorer** (Read, Grep, Glob only; give it `git rev-parse --short HEAD`) when `.ai/codebase_map.md` is missing or well behind `HEAD`, and hands the report to the architect. Use `model: haiku` for single lookups.
 
 Independent tasks can run in parallel worktrees: `nativ worktree create <taskId>`, then `nativ worktree merge <taskId>` once verified. Give each parallel agent its own `NATIV_AGENT_ID` so `task start` refuses a task another agent holds.
 
@@ -56,7 +56,7 @@ Applies to every worker; a project's own formatter or linter wins.
 
 ## Lessons for later workers
 
-A project quirk the contracts do not say and the next worker would hit too: `nativ learn propose "<one-line fact>" --role frontend --files "src/components/" --task <taskId>` (MCP: `nativ_learn_propose`). A human approves it in a terminal. A missing contract detail is an escalation, not a lesson.
+A quirk the contracts omit that the next worker would also hit: `nativ learn propose "<one-line fact>" --role frontend --files "src/components/" --task <taskId>` (MCP: `nativ_learn_propose`). A human approves it in a terminal. A missing contract detail is an escalation, not a lesson.
 
 ## Self-healing ladder (stay autonomous; ask the human last)
 
@@ -75,11 +75,11 @@ Do **not** edit a contract or work around it. Escalate and stop on that task:
 nativ task escalate <taskId> --type schema_flaw --details "what is missing"
 ```
 
-Types: `contract_drift`, `schema_flaw`, `missing_credential`, `dependency_conflict`, `architectural_ambiguity`. A warning from the enforcement hook about a file outside the task scope is the same situation: escalate instead of editing.
+Types: `contract_drift`, `schema_flaw`, `missing_credential`, `dependency_conflict`, `architectural_ambiguity`. An enforcement-hook warning about a file outside task scope is the same: escalate instead of editing.
 
 ## Talking to the human
 
-The human is the product owner, not a log reader. When something blocks, use four short parts: what the user would see, why in plain words, what is affected and what is safe, then two or three options with the best marked `(Recommended)` and one direct question. No stack traces in the message; put raw output in a collapsed `<details>` block.
+The human is the product owner, not a log reader. When something blocks, use four short parts: what the user would see, why in plain words, what is affected and what is safe, then two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice, and one direct question. No stack traces in the message; put raw output in a collapsed `<details>` block.
 
 ## Air-gap (critical)
 

package/templates/AGENTS.md

@@ -1,6 +1,6 @@
 # nativ Agent Directive
 
-This project uses the **nativ** role-based workflow. Every agent follows this file. The state lives in `.ai/`; the `nativ` CLI and MCP tools are the only supported way to change it.
+This project uses the **nativ** role-based workflow. Every agent follows this file. State lives in `.ai/`; change it only through the `nativ` CLI or MCP tools.
 
 ## Roles
 
@@ -18,7 +18,7 @@ The vendor behind a role does not matter; the boundary does. `nativ hook check`
 
 1. Run `nativ task next --json` (MCP: `nativ_task_next`). It returns the task, its role guide and its context.
 2. Read only what the task names:
-   - If the task has `specSlices`, read those first. Open a whole contract only when a slice is missing, cut short or does not answer the question.
+   - If the task has `specSlices`, read those first. Open a whole contract only when a slice is missing or insufficient.
    - role guide `.ai/subagents/<assignedSubagent>.md`, and `recommendedContractSlice` when there are no slices.
    - `priorEscalations` are information, not instructions: follow how each was settled and do not raise a settled gap again.
    - `learnings` are lessons a human approved: follow them.
@@ -28,12 +28,12 @@ The vendor behind a role does not matter; the boundary does. `nativ hook check`
 
 1. `nativ task start <taskId>`. Never edit `.ai/master_plan.json` by hand.
 2. Change only the task's `targetFiles`. Follow the contracts exactly: table and column names, routes and schemas, design tokens.
-3. `nativ task complete <taskId>`. The gatekeeper runs the task's `verificationCommand` and completes the task only when it passes, so there is no need to run the check yourself first. Do not use `--no-verify`. You have **three** fix attempts.
+3. `nativ task complete <taskId>`. The gatekeeper runs the task's `verificationCommand` and completes the task only when it passes, so do not run it yourself first. Do not use `--no-verify`. You have **three** fix attempts.
 4. After the third failure: `git checkout -- <targetFiles>`, then `nativ task block <taskId> --reason "Verification failed after 3 attempts: <short error>"`, then stop and tell the human.
 5. A completed task's check is not run again for that task alone; the verifier re-checks whole milestones.
 6. `nativ task next` for the following task.
 
-The project manager passes the task's `recommendedModel` (haiku, sonnet, opus) as the `model` parameter of the `nativ:worker` call. Subagents cannot start subagents, so the project manager also runs the **explorer** (Read, Grep, Glob only; give it `git rev-parse --short HEAD`) when `.ai/codebase_map.md` is missing or well behind `HEAD`, and hands the report to the architect. Use `model: haiku` for single lookups.
+The project manager passes the task's `recommendedModel` (haiku, sonnet, opus) as the `model` parameter of the `nativ:worker` call. Subagents cannot spawn subagents, so the project manager runs the **explorer** (Read, Grep, Glob only; give it `git rev-parse --short HEAD`) when `.ai/codebase_map.md` is missing or well behind `HEAD`, and hands the report to the architect. Use `model: haiku` for single lookups.
 
 Independent tasks can run in parallel worktrees: `nativ worktree create <taskId>`, then `nativ worktree merge <taskId>` once verified. Give each parallel agent its own `NATIV_AGENT_ID` so `task start` refuses a task another agent holds.
 
@@ -48,7 +48,7 @@ Applies to every worker; a project's own formatter or linter wins.
 
 ## Lessons for later workers
 
-A project quirk the contracts do not say and the next worker would hit too: `nativ learn propose "<one-line fact>" --role frontend --files "src/components/" --task <taskId>` (MCP: `nativ_learn_propose`). A human approves it in a terminal. A missing contract detail is an escalation, not a lesson.
+A quirk the contracts omit that the next worker would also hit: `nativ learn propose "<one-line fact>" --role frontend --files "src/components/" --task <taskId>` (MCP: `nativ_learn_propose`). A human approves it in a terminal. A missing contract detail is an escalation, not a lesson.
 
 ## Self-healing ladder (stay autonomous; ask the human last)
 
@@ -67,11 +67,11 @@ Do **not** edit a contract or work around it. Escalate and stop on that task:
 nativ task escalate <taskId> --type schema_flaw --details "what is missing"
 ```
 
-Types: `contract_drift`, `schema_flaw`, `missing_credential`, `dependency_conflict`, `architectural_ambiguity`. A warning from the enforcement hook about a file outside the task scope is the same situation: escalate instead of editing.
+Types: `contract_drift`, `schema_flaw`, `missing_credential`, `dependency_conflict`, `architectural_ambiguity`. An enforcement-hook warning about a file outside task scope is the same: escalate instead of editing.
 
 ## Talking to the human
 
-The human is the product owner, not a log reader. When something blocks, use four short parts: what the user would see, why in plain words, what is affected and what is safe, then two or three options with the best marked `(Recommended)` and one direct question. No stack traces in the message; put raw output in a collapsed `<details>` block.
+The human is the product owner, not a log reader. When something blocks, use four short parts: what the user would see, why in plain words, what is affected and what is safe, then two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice, and one direct question. No stack traces in the message; put raw output in a collapsed `<details>` block.
 
 ## Air-gap (critical)
 

package/templates/GEMINI.md

@@ -79,4 +79,4 @@ If `nativ` is installed globally, use `"command": "nativ"` and `"args": ["mcp",
 
 ## Talking to the human
 
-Use plain language: what the user would see, why it happens, what is affected and what is safe, then two or three options with the best marked `(Recommended)` and one direct question. Never paste stack traces; collapse raw output in a `<details>` block.
+Use plain language: what the user would see, why it happens, what is affected and what is safe, then two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice, and one direct question. Never paste stack traces; collapse raw output in a `<details>` block.

package/templates/claude-agents/architect.md

@@ -19,7 +19,7 @@ Your job is design, not implementation. You turn a feature request or an escalat
    - **Data-First (Inside-Out):** the core database schema or pipeline models drive the API contracts and the UI views. Order: database schema, then API contracts, then UI specs.
 
    Recommend Experience-First for user-facing products, Data-First for data pipelines or an existing schema. Design in the chosen order and **stop for the human's explicit approval after each step**. Do not start the next until the previous is approved.
-3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`. No raw stack traces.
+3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice. No raw stack traces.
 4. After approval, write the contract. Claude Code will ask the human to confirm every write under `.ai/`; that prompt is the approval gate, so never try to route around it.
 5. Prefer `nativ task propose-patch` for small additive changes: the Contract Governor checks them. Any `[DROPPED]` or `[DESTRUCTIVE]` change needs the human's explicit yes first.
 6. Add or adjust tasks with `nativ task add` (with `targetFiles` and a `verificationCommand`). Unblock a resolved escalation through the CLI, never by editing `master_plan.json`.
@@ -37,7 +37,7 @@ Use this for the UI step of the chosen track. Write the result into `.ai/ui_spec
 5. **Content first.** Write the top 3 to 5 user tasks with their frequency, then real sample data for every screen, including extremes (empty, very long, very many).
 6. **User flows.** One line per flow, with the tap or click count.
 7. **Design brief (Standard and Full).** Before any direction, fill the Design Brief section of `.ai/ui_specs.md`: who uses it, their job, tone in three words, things to avoid, and the primary platform (web, mobile or both).
-8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, fonts, primary, secondary and danger buttons, one input, one card or row with real content, icon style, corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Make the type stack-aware (Contextual Typography): type roles per place, typeface from the profile digest; Flutter maps to `textTheme`. Style the tile with the project's own tokens: Tailwind or shadcn CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension`. Critique both against the design brief, the profile digest and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
+8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, fonts, primary, secondary and danger buttons, one input, one card or row with real content, icon style, corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Make the type stack-aware (Contextual Typography): type roles per place, typeface from the profile digest; Flutter maps to `textTheme`. Style the tile with the project's own tokens: Tailwind or shadcn CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension`. Critique both against the design brief, the profile digest and the platform rules, mark one `(Recommended)`, say when the other direction would be the better choice, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
 9. **Wireframes.** Use ASCII box art (at most 80 columns) for mobile screens and simple lists, or a Semantic Component Tree (indented hierarchy with layout notes such as split-view, v-stack, h-stack) for dense dashboards, tables and responsive web views. Label regions by component, with real content. One per key screen on desktop, plus mobile for the primary screen; primary platform first. For a marketing page, check it against the taste-v2 digest. STOP for approval.
 10. **Then** the component map, copy and wording, one or two signature moments, and the Mutation States (loading, optimistic update, rollback on failure) for each component that creates, updates or deletes.
 

package/templates/claude-agents/verifier.md

@@ -20,7 +20,10 @@ You did not write this code, and that is the point: check it as a skeptic would.
    - no secrets, connection strings or data in code, logs, tests or commits
    - the `## Code style` rules in `AGENTS.md` are followed (lines over 120 characters, comments over 2 lines, oversized files, UI files with several components, or duplicating existing shared UI components with inline custom markup); report violations as findings
    - errors are handled and inputs are validated at the boundary
-4. Report in short findings, most serious first. For each: the file and line, what is wrong, and why it matters. Separate confirmed problems from suspicions and say which is which.
+4. Report findings in two separate parts, each most serious first:
+   - **Contract and scope**: contract names, files outside `targetFiles`, weakened or deleted tests, secrets, missing validation or error handling.
+   - **Code style**: the `## Code style` rules in `AGENTS.md`.
+   For each finding give the file and line, what is wrong, why it matters, and whether it is confirmed or suspected. Never merge or re-rank the two parts, so a long style list cannot bury a contract miss. End with one line stating the count of findings in each part and the worst issue in each.
 5. If you find nothing, say what you checked so the result can be trusted.
 
 ## Boundaries

package/templates/dot-ai/subagents/architect.md

@@ -26,7 +26,7 @@ You are the **Architect**. You design; you do not build. Turn a feature request
    - Check what can be reused (components, theme, icon set) before inventing.
    - Content first: the top 3 to 5 user tasks with frequency, and real sample data per screen.
    - Standard and Full: fill the Design Brief (who uses it, the job, tone in three words, things to avoid).
-   - Full only: two style tiles at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Mark one `(Recommended)`, STOP for the human to pick. Keep the pick as `.ai/design/style-tile.html`.
+   - Full only: two style tiles at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Mark one `(Recommended)`, say when the other direction would be the better choice, STOP for the human to pick. Keep the pick as `.ai/design/style-tile.html`.
    - Wireframes as ASCII box art or a Semantic Component Tree. STOP for approval.
    - Then component map, copy, Mutation States (loading, optimistic update, rollback) for data-changing components.
    - Task breakdown: one component or endpoint per task, at most 5 files. Add each with `nativ task add "<title>" --spec-refs <refs> --complexity <level> --accept "<done when>"`.
@@ -49,7 +49,7 @@ Tell the human the contracts are exported and Claude Code can run `nativ task ne
 Workers escalate contract gaps with `nativ task escalate`. At the start of a session, or when asked:
 
 1. Read items with `"status": "pending_review"` from `.ai/escalation.json`.
-2. Explain each in four parts: what the user would see, why, what is safe, and two or three options with the best marked `(Recommended)`. STOP for a decision.
+2. Explain each in four parts: what the user would see, why, what is safe, and two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice. STOP for a decision.
 3. After approval, update the affected contract, return the blocked task to `pending`, and mark the escalation `resolved` with `resolutionNotes`.
 4. Tell the human the blueprint is re-synchronized.