skillpacks 0.1.1 → 0.1.2

package/packs/product-testing/codex/uat/archive/v0.10/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: uat
+description: Create user acceptance test journeys from a target user's perspective, with role-based scenarios, acceptance criteria, and evidence capture
+type: analysis
+version: v0.10
+argument-hint: "[--variant-evaluation] [optional: persona, feature, release, journey, app, or variation spec]"
+interview_depth: none
+---
+
+## Pack Availability Guard
+
+Before telling the user to run a skill from another project-local pack, check `.agents/project.json.enabled_packs`. If the target pack is not enabled, recommend `$pack install <pack>` instead of the target skill. Global skills are always valid. Skills from this same pack are valid because the current skill is already running from that pack.
+
+# UAT
+
+Invoke as `$uat`.
+
+Create a user acceptance testing plan from the perspective of a potential or target user. Read the product surface, specs, journeys, stories, roadmap, and relevant research, then produces realistic end-to-end user journeys that validate whether the product satisfies user goals.
+
+UAT is not dogfooding. Dogfood asks how the app owner can adopt the product into their own workflow to understand and evaluate it. UAT asks whether a target user can complete meaningful real-world journeys and would accept the product as fit for use.
+
+This is a human-run acceptance plan, not automated testing. Do not start servers, drive browsers, call APIs, create accounts, or perform the scenarios yourself.
+
+When invoked with `--variant-evaluation` (or when the user asks to test/review UI variants), create a hands-on evaluation plan for built UX/UI variants before `$consolidate-variations`. This mode helps the user try each variant in a comparable way and capture enough evidence to form a defensible consolidation opinion.
+
+## Process
+
+### 0. Product-Path Scope Resolution
+
+Resolve research scope by product path before using code or app structure as a hint:
+
+1. If `$ARGUMENTS` names a non-archived `research/{slug}/` directory or a product-path ID whose `scope_path` points there, use that path. Treat `{slug}` as the product/app name, not the ICP, audience, or segment label.
+2. If `$ARGUMENTS` names only `research/_archive/{slug}/` or a manifest entry with `status: archived` or legacy `status: abandoned`, stop and warn that the path is archived; do not write or update scoped outputs there.
+3. Read `research/.progress.yaml` when present. Normalize legacy `active_path` to `active_paths` on read and write back `active_paths` on manifest updates. Treat legacy `abandoned` as `archived`; exclude `archived`, `abandoned`, `deferred`, `revisit_candidate`, `promoted`, and any `scope_path` under `research/_archive/` from active target selection.
+4. If active product paths exist in the manifest, use those paths. If multiple active paths exist, ask which one to target unless this skill explicitly supports cross-path output.
+5. If no active manifest target exists, list non-archived product directories under `research/`, excluding `research/_archive/` and dot directories. Auto-select only when exactly one exists; ask when multiple exist.
+6. If no product directories exist, use flat `research/` single-product mode.
+7. Detect monorepo/app/package structure only as a secondary hint. Suggest creating a missing `research/{slug}/` product path when code clearly exposes an app, but do not require code or monorepo detection before using `research/{slug}/`.
+
+When product path `{slug}` is active, read and write research under `research/{slug}/`, specs under `specs/{slug}/`, and treat top-level `research/*.md` files as flat-mode documents or cross-path summaries.
+
+1. **Resolve project context**
+   - Read `.agents/project.json` if it exists.
+   - Use `project_type` and `enabled_packs` when present.
+   - If project metadata is missing, infer the project type from repo signals:
+     - business-app: SaaS, marketplace, productivity, workflow, enterprise, or user-facing app
+     - devtool: SDK, CLI, API, library, infrastructure, docs, examples, or package-first developer workflow
+     - game: game engine files, playable prototypes, store assets, or game-specific README/spec language
+     - generic: no strong domain signal
+   - Read `README.md`, `AGENTS.md`, `CLAUDE.md`, relevant `docs/`, `specs/`, `spec.md`, and `tasks/` files when present.
+
+2. **Load user evidence**
+   - Business app: read `research/icp.md`, `research/journey-map.md`, `research/customer-feedback.md`, `research/metrics.md`, and `research/mvp-gap.md` when present.
+   - Devtool: read `research/devtool-user-map.md`, `research/devtool-dx-journey.md`, `research/devtool-integration-map.md`, docs, examples, and package manifests when present.
+   - Game: read `research/game-audience.md`, `research/game-fantasy.md`, `research/game-core-loop.md`, `research/game-prototype-test.md`, and `research/game-playtest-metrics.md` when present.
+   - Generic: use specs, README, routes, tests, examples, issue descriptions, and task acceptance criteria.
+   - In product-path workspaces with `research/{slug}/` or `specs/{slug}/`, produce product-path-scoped UAT journeys for the requested app. If no app is specified and multiple apps are plausible, ask the user to choose.
+
+2b. **Variant evaluation mode**
+   - Trigger this branch when invoked with `--variant-evaluation`, when `specs/ui-layout-variations-*.md` exists for the requested topic, or when the user asks how to test/review built variants.
+   - Read `specs/ui-layout-variations-[topic].md`, `specs/ux-variations-[topic].md`, `specs/ui-requirements-[topic].md`, built variant routes/components, and any existing `research/uat-variant-evaluation-[topic].md`.
+   - Identify each variant, its intended thesis, implementation location, and the target user task it should support.
+   - Create comparable journeys that make the user perform the same core task in every variant, then capture variant-specific strengths, friction, confidence, and rejection signals.
+   - Include a side-by-side comparison matrix and a "Ready for `$consolidate-variations`?" checklist.
+   - Human execution still belongs in `tasks/manual-todo.md`; this skill writes the plan and manual tasks, but does not run the variants.
+   - After writing files, recommend `$consolidate-variations` only as the next step after the manual evaluation tasks are completed or when the user explicitly says they have already evaluated the variants.
+   - Stop after this branch. Do not generate generic target-user acceptance journeys unless the user also requested them.
+
+3. **Define acceptance perspective**
+   - Identify 1-3 target user personas or roles from the evidence.
+   - For each selected persona, define the job-to-be-done, context, goal, constraints, and acceptance threshold.
+   - Prefer external target users, buyers, evaluators, administrators, developers, or players over the product owner unless the owner is also the target user.
+   - If the target user is unclear, stop and recommend `$customer-discovery`, `$journey-map`, or the relevant pack research skill. For `$customer-discovery`, `$journey-map`, and other pack-based skills, apply the Pack Availability Guard — if the target skill's pack is not in `.agents/project.json` `enabled_packs`, recommend `$pack install <pack>` before the skill.
+
+4. **Create UAT journeys**
+   - Generate 3-7 journeys unless the user requested a narrower focus.
+   - Cover at least one critical happy path, one realistic obstacle or recovery path, and one return-use or handoff path when supported by the product evidence.
+   - Each journey must include:
+     - target user
+     - user goal
+     - real-world trigger
+     - setup and preconditions
+     - end-to-end task sequence
+     - expected user-visible success state
+     - acceptance criteria
+     - non-acceptance signals
+     - evidence to capture
+     - tester notes prompt
+     - follow-up routing
+   - Use concrete product language from specs and journeys. Avoid vague instructions such as "verify the feature works."
+
+5. **Classify follow-up work**
+   - Human-run UAT journeys go in `tasks/manual-todo.md` under `## UAT Journeys`.
+   - Use `_(after: research/uat-plan.md)_` unless the journey blocks or follows a known roadmap step. If tied to a known step, use `_(blocks: Step N.X)_` or `_(after: Step N.X)_`.
+   - Do not put human-run UAT journeys in `tasks/todo.md`.
+   - Implementation or documentation fixes discovered after a completed UAT run belong in `tasks/todo.md`, but do not invent fixes before the user journey has been attempted.
+   - One-time evidence collection belongs in `tasks/record-todo.md`.
+   - Recurring release acceptance checks belong in `tasks/recurring-todo.md` only when there is a clear release cadence.
+   - If a journey needs click-by-click help for a human-only external blocker, recommend `$guide`.
+
+6. **Present findings before writing when risk is high**
+   - If source material is thin, contradictory, or missing target-user evidence, summarize the gap and ask whether to proceed with assumptions.
+   - If source material is sufficient, write the plan and task sections directly.
+
+## Deliverables
+
+- `research/uat-plan.md` - persona assumptions, journey matrix, source evidence, acceptance checklist, result log template, and follow-up guidance.
+- In variant evaluation mode: `research/uat-variant-evaluation-[topic].md` - variant inventory, task script, comparison matrix, result logs, and consolidation readiness checklist.
+- `tasks/manual-todo.md` - append or replace only the `## UAT Journeys` section.
+- `tasks/recurring-todo.md` - optional, only when recurring UAT is useful and not already tracked.
+
+If `tasks/manual-todo.md` does not exist, create it with a `# Manual Tasks - [Project Name]` title, a short note that these items require human-only action, and the UAT section. Preserve all non-UAT sections when updating an existing file.
+
+Use this journey format in `research/uat-plan.md`:
+
+```markdown
+### Journey N: [Name]
+
+- Target user: [persona or role]
+- User goal: [what the user is trying to accomplish]
+- Trigger: [real-world reason the user starts]
+- Setup: [accounts, data, environment, permissions, or sample state needed]
+- Task sequence:
+  - [step the human tester performs as the target user]
+- Expected success state: [observable user-visible result]
+- Acceptance criteria:
+  - [ ] [specific criterion]
+- Non-acceptance signals: [confusion, delay, missing affordance, incorrect result, trust issue, or blocker]
+- Evidence to capture: [screenshots, recordings, notes, timestamps, records, command output, or artifacts]
+- Tester notes prompt: [question that captures whether the target user would accept this]
+- Follow-up routing: [manual note, $customer-discovery, $journey-map, $guide, or task promotion guidance]
+
+#### UAT result log
+
+- Status: Not run | Pass | Fail | Blocked
+- Evidence captured:
+- Tester notes:
+- Follow-up tasks promoted:
+```
+
+Use this variant evaluation format in `research/uat-variant-evaluation-[topic].md`:
+
+```markdown
+## Variant Evaluation Plan
+
+### Variant Inventory
+
+| Variant | Implementation location | Thesis | Primary task |
+|---|---|---|---|
+
+### Shared Evaluation Script
+
+- Target user:
+- Scenario:
+- Setup:
+- Core task sequence:
+- Success criteria:
+- Non-acceptance signals:
+- Evidence to capture:
+
+### Per-Variant Result Log
+
+#### [Variant name]
+
+- Status: Not run | Pass | Fail | Blocked
+- Evidence captured:
+- What worked:
+- What felt wrong:
+- Time/friction notes:
+- Keep for consolidation:
+- Reject for consolidation:
+- Confidence: Low | Medium | High
+
+### Side-by-Side Comparison Matrix
+
+| Dimension | Variant A | Variant B | Variant C | Current preference | Evidence |
+|---|---|---|---|---|---|
+
+### Ready for `$consolidate-variations`?
+
+- [ ] Every built variant has been tried or explicitly skipped.
+- [ ] Evidence exists for each kept/rejected design element.
+- [ ] Open blockers are documented.
+- [ ] The user has enough confidence to converge.
+```
+
+Use this item format in `tasks/manual-todo.md`:
+
+```markdown
+## UAT Journeys
+
+- [ ] Run UAT journey: [Journey name] as [target user] _(after: research/uat-plan.md)_ - capture evidence in `research/uat-plan.md`.
+```
+
+## Task Classification
+
+- Human UAT journey execution goes in `tasks/manual-todo.md`.
+- Variant evaluation tasks go in `tasks/manual-todo.md` under `## UAT Journeys` and should reference `research/uat-variant-evaluation-[topic].md`.
+- Immediate implementation or documentation fixes confirmed by completed UAT go in `tasks/todo.md`.
+- One-time condition-gated evidence collection goes in `tasks/record-todo.md`.
+- Release-cadence UAT checks go in `tasks/recurring-todo.md`.
+- Do not put non-blocking records or recurring obligations in `tasks/todo.md` unless they have been explicitly promoted into current execution work.
+
+## Constraints
+
+- Do not run or operate the product in this skill.
+- Do not start dev servers, launch browsers, use Playwright, call APIs, create accounts, or perform CLI workflows.
+- Do not mark journeys complete; only a human tester can do that after performing them.
+- Do not recommend `$consolidate-variations` before variant evaluation evidence exists, unless the user explicitly confirms they have already reviewed the variants and are ready to converge.
+- Do not duplicate existing unchecked UAT or manual tasks. Reference existing items when they already cover the same journey.
+- Prefer evidence-backed target-user journeys over exhaustive feature coverage.
+- Keep dogfood and UAT separate: use `$dogfood` for owner/operator adoption into the builder's workflow; use `$uat` for target-user acceptance journeys.
+- If no credible user journey, story, spec, or product surface can be found, stop and recommend `$customer-discovery`, `$journey-map`, or the relevant pack research skill. Apply the Pack Availability Guard for pack-based skills.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/uat-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/project-fleet/claude/clone-spec-store/ALIGNMENT-PAGE.md

@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-clone-spec-store-research.md`; product-path mode uses `research/{slug}/_working/preliminary-clone-spec-store-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-clone-spec-store-research.md`; product-path mode uses `research/{slug}/_working/preliminary-clone-spec-store-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Required inline questions.** In `review` pages, each gate must contain at least one required inline question placed directly under the content it governs, inside a visually distinct question block. Each question must use radio-button inputs and include two standing options after the skill-generated choices: "Other / None of the above" backed by a multi-line text box for free-form input, and "Need clarification" backed by an optional notes box where the user can explain what is unclear. When any radio option other than "Other" or "Need clarification" is selected, show an optional "Additional notes" text box beneath it so the user can qualify their choice. Generate questions based on what genuinely needs user input -- do not add filler questions. Do not create a separate bottom "Decisions & Clarifications" section. Confirmed pages must not keep these as required input controls; render the answered decisions as read-only records.
 

package/packs/project-fleet/claude/skill-inventory/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — skill-inventory
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/skill-inventory-{topic}.html`. Use a normalized topic slug derived from the app, feature, research subject, report subject, or output filename.
+Alignment pages are optional for this operational skill. By default, report the outcome inline and write only the skill's normal durable artifacts (`tasks/*.md`, reports, queues, benchmark notes, status docs, or other skill-specific files). Build `alignment/skill-inventory-{topic}.html` only when the user explicitly requests an alignment page or when the agent explicitly identifies a concrete clarification/review need that cannot be resolved cleanly in conversation or the normal artifacts. When an alignment page is created, use the full contract below and a normalized topic slug derived from the app, feature, research subject, report subject, or output filename.
 
 **Visual rendering tier.** Each alignment page declares a rendering tier:
 - `document` (default) — text, tables, approval gates. No charts or interactive elements.
@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-skill-inventory-research.md`; product-path mode uses `research/{slug}/_working/preliminary-skill-inventory-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-skill-inventory-research.md`; product-path mode uses `research/{slug}/_working/preliminary-skill-inventory-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Required inline questions.** In `review` pages, each gate must contain at least one required inline question placed directly under the content it governs, inside a visually distinct question block. Each question must use radio-button inputs and include two standing options after the skill-generated choices: "Other / None of the above" backed by a multi-line text box for free-form input, and "Need clarification" backed by an optional notes box where the user can explain what is unclear. When any radio option other than "Other" or "Need clarification" is selected, show an optional "Additional notes" text box beneath it so the user can qualify their choice. Generate questions based on what genuinely needs user input -- do not add filler questions. Do not create a separate bottom "Decisions & Clarifications" section. Confirmed pages must not keep these as required input controls; render the answered decisions as read-only records.
 

package/packs/project-fleet/claude/skill-inventory/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.1 - 2026-06-12
+
+- Made alignment pages optional by default: report inline and write the skill's normal durable artifacts unless the user requests an alignment page or the agent identifies a concrete clarification/review need.
+
 ## v0.0 - 2026-05-31
 
 - Added initial report-only downstream skill inventory workflow with bundled scanner guidance.

package/packs/project-fleet/claude/skill-inventory/SKILL.md

@@ -2,7 +2,7 @@
 name: skill-inventory
 description: Inventory downstream repository Claude and Codex skill installs from a control-repo manifest, classify managed local skill-copy drift against canonical agentic-skills sources, and produce report-only Markdown or JSON guidance without refreshing, deleting, or mutating downstream repos.
 type: ops
-version: v0.0
+version: v0.1
 argument-hint: "[--manifest <path>] [--repo <path>] [--format markdown|json]"
 ---
 
@@ -78,7 +78,7 @@ If no local paths are found, the scanner must fail non-destructively and print a
 
 ## Alignment Page
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/skill-inventory-{topic}.html`.
+By default, this skill reports results inline and writes only its normal durable artifacts (for example `tasks/*.md`, reports, queues, benchmark notes, status docs, or other skill-specific files). Do not build an alignment page automatically. Create `alignment/skill-inventory-{topic}.html` only when the user explicitly requests an alignment page or when you explicitly identify a concrete clarification/review need that cannot be handled cleanly inline; when you create one, follow `ALIGNMENT-PAGE.md` in this skill's directory.
 
 ## Default Shipping Contract
 

package/packs/project-fleet/claude/skill-inventory/archive/v0.0/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: skill-inventory
+description: Inventory downstream repository Claude and Codex skill installs from a control-repo manifest, classify managed local skill-copy drift against canonical agentic-skills sources, and produce report-only Markdown or JSON guidance without refreshing, deleting, or mutating downstream repos.
+type: ops
+version: v0.0
+argument-hint: "[--manifest <path>] [--repo <path>] [--format markdown|json]"
+---
+
+# Skill Inventory
+
+Invoke as `/skill-inventory`.
+
+Use this skill from a control repository that manages downstream repositories and needs to know whether copied local skill roots are current, stale, pinned, unmanaged, or missing their canonical source.
+
+## V1 Contract
+
+Report-only — do not modify tracked files.
+
+- Do not run `scripts/pack.sh refresh`.
+- Do not run delete, cleanup, remove, prune, or reinstall commands.
+- Do not edit `.claude/skills/**`, `.codex/skills/**`, `.agents/project.json`, or any file inside downstream repositories.
+- Do not add an apply route in v1. Suggest exact follow-up commands only after the inventory report shows what is needed.
+- Only write control-repo artifacts: `tasks/skill-inventory.md`, `alignment/skill-inventory-{topic}.html`, task notes, prompt history, and normal shipping docs.
+
+## Process
+
+1. Read repo instructions first: `AGENTS.md`, `CLAUDE.md`, or the local equivalent.
+2. Capture the visible `/skill-inventory` invocation under `prompts/skill-inventory/` before substantive work, following the repo prompt-history convention.
+3. Resolve downstream repos from a manifest before scanning. Default manifest search order:
+   - `tasks/downstream-repos.md`
+   - `tasks/fleet-queue.md`
+   - `tasks/repo-seeding.md`
+4. Require a Markdown table column named `Local Path` or `Path` for local checkout paths. Remote-only `owner/repo` cells are not scannable; ask for a local path instead of guessing.
+5. Run the bundled scanner from this skill directory. Default output is the durable Markdown report:
+
+   ```bash
+   bash scripts/skill-inventory.sh --out tasks/skill-inventory.md --format markdown
+   ```
+
+   Useful variants:
+
+   ```bash
+   bash scripts/skill-inventory.sh --manifest tasks/downstream-repos.md --out tasks/skill-inventory.md
+   bash scripts/skill-inventory.sh --repo ../downstream-app --out -
+   bash scripts/skill-inventory.sh --format json --out -
+   ```
+
+6. The scanner sources the control repo's canonical `scripts/skill-links.sh` and uses `skill_install_status` for status classification. Do not reimplement the drift semantics manually.
+7. Review the report and build `alignment/skill-inventory-{topic}.html` using `ALIGNMENT-PAGE.md` when producing a durable report. The page must render the report, evidence, assumptions, action hints, and approval gates without context loss.
+8. End with:
+   - **Next work:** the most specific inventory follow-up, usually adding missing local paths or reviewing stale rows.
+   - **Recommended next command:** usually `/skill-inventory --manifest <path>` to rerun after manifest fixes, or `/project-fleet --status` when no inventory remediation is needed.
+
+## Status Categories
+
+Use the exact categories emitted by `skill_install_status`:
+
+- `ok`: managed copy matches the canonical source content.
+- `stale`: canonical source content changed since the managed copy was installed.
+- `unknown`: marker exists but lacks `source_sha`; refresh is needed later to enable deterministic tracking.
+- `missing-source`: marker points to a source directory that no longer exists.
+- `pinned`: symlinked install, usually to `archive/<version>`, intentionally frozen.
+- `not-managed`: skill directory is not an agentic-skills managed install.
+
+## Report Expectations
+
+`tasks/skill-inventory.md` should include:
+
+- control repo, manifest path, generated timestamp, and report-only notice;
+- repo-level totals across Claude and Codex skill roots;
+- per-agent rows for `.claude/skills/*` and `.codex/skills/*`;
+- installed and canonical version fields when available;
+- source path evidence for managed or pinned installs;
+- action hints for `stale`, `unknown`, and `missing-source`, including exact suggested follow-ups such as `scripts/pack.sh refresh`;
+- a clear statement that the scan did not run refresh, delete, cleanup, install, or other mutation commands.
+
+If no local paths are found, the scanner must fail non-destructively and print a manifest template with a `Local Path` column.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/skill-inventory-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/project-fleet/claude/skill-inventory/scripts/skill-inventory.sh

@@ -250,23 +250,35 @@ TEMPLATE
 
 declare -a REPO_PATHS=()
 declare -a REPO_LABELS=()
-declare -A SEEN_REPOS=()
+declare -a SEEN_REPOS=()
+
+repo_seen() {
+  local candidate="$1"
+  local existing
+  [[ ${#SEEN_REPOS[@]} -gt 0 ]] || return 1
+  for existing in "${SEEN_REPOS[@]}"; do
+    [[ "$existing" == "$candidate" ]] && return 0
+  done
+  return 1
+}
 
 add_repo_path() {
   local raw="$1"
   local base="$2"
   local resolved
   resolved="$(canonical_dir_or_path "$(resolve_path_from_base "$raw" "$base")")"
-  if [[ -z "${SEEN_REPOS[$resolved]:-}" ]]; then
-    SEEN_REPOS["$resolved"]=1
+  if ! repo_seen "$resolved"; then
+    SEEN_REPOS+=("$resolved")
     REPO_PATHS+=("$resolved")
     REPO_LABELS+=("$(basename "$resolved")")
   fi
 }
 
-for repo in "${repo_args[@]}"; do
-  add_repo_path "$repo" "$PWD"
-done
+if [[ ${#repo_args[@]} -gt 0 ]]; then
+  for repo in "${repo_args[@]}"; do
+    add_repo_path "$repo" "$PWD"
+  done
+fi
 
 if [[ -n "$manifest_path" ]]; then
   manifest_base="$(dirname "$manifest_path")"
@@ -286,14 +298,39 @@ manifest_display="${manifest_label:-explicit --repo only}"
 
 declare -a INSTALL_ROWS=()
 declare -a REPO_ROWS=()
-declare -A STATUS_TOTALS=()
-for status in "${STATUS_ORDER[@]}"; do
-  STATUS_TOTALS["$status"]=0
-done
+STATUS_TOTAL_OK=0
+STATUS_TOTAL_STALE=0
+STATUS_TOTAL_UNKNOWN=0
+STATUS_TOTAL_MISSING_SOURCE=0
+STATUS_TOTAL_PINNED=0
+STATUS_TOTAL_NOT_MANAGED=0
 TOTAL_REPOS=0
 TOTAL_INSTALLS=0
 TOTAL_AGENT_ROOTS=0
 
+status_total() {
+  case "$1" in
+    ok) printf '%s\n' "$STATUS_TOTAL_OK" ;;
+    stale) printf '%s\n' "$STATUS_TOTAL_STALE" ;;
+    unknown) printf '%s\n' "$STATUS_TOTAL_UNKNOWN" ;;
+    missing-source) printf '%s\n' "$STATUS_TOTAL_MISSING_SOURCE" ;;
+    pinned) printf '%s\n' "$STATUS_TOTAL_PINNED" ;;
+    not-managed) printf '%s\n' "$STATUS_TOTAL_NOT_MANAGED" ;;
+    *) printf '0\n' ;;
+  esac
+}
+
+increment_status_total() {
+  case "$1" in
+    ok) STATUS_TOTAL_OK=$((STATUS_TOTAL_OK + 1)) ;;
+    stale) STATUS_TOTAL_STALE=$((STATUS_TOTAL_STALE + 1)) ;;
+    unknown) STATUS_TOTAL_UNKNOWN=$((STATUS_TOTAL_UNKNOWN + 1)) ;;
+    missing-source) STATUS_TOTAL_MISSING_SOURCE=$((STATUS_TOTAL_MISSING_SOURCE + 1)) ;;
+    pinned) STATUS_TOTAL_PINNED=$((STATUS_TOTAL_PINNED + 1)) ;;
+    not-managed) STATUS_TOTAL_NOT_MANAGED=$((STATUS_TOTAL_NOT_MANAGED + 1)) ;;
+  esac
+}
+
 status_hint() {
   case "$1" in
     ok) printf 'No action.' ;;
@@ -321,11 +358,13 @@ scan_repo() {
   local exists="yes"
   local claude_count=0
   local codex_count=0
-  local -A repo_status=()
+  local repo_ok=0
+  local repo_stale=0
+  local repo_unknown=0
+  local repo_missing_source=0
+  local repo_pinned=0
+  local repo_not_managed=0
   local status
-  for status in "${STATUS_ORDER[@]}"; do
-    repo_status["$status"]=0
-  done
 
   TOTAL_REPOS=$((TOTAL_REPOS + 1))
 
@@ -350,8 +389,15 @@ scan_repo() {
         INSTALL_ROWS+=("${label}"$'\t'"${repo_path}"$'\t'"${agent}"$'\t'"${skill}"$'\t'"${status}"$'\t'"${recorded}"$'\t'"${current}"$'\t'"${source}"$'\t'"${hint}")
         count=$((count + 1))
         TOTAL_INSTALLS=$((TOTAL_INSTALLS + 1))
-        repo_status["$status"]=$((repo_status["$status"] + 1))
-        STATUS_TOTALS["$status"]=$((STATUS_TOTALS["$status"] + 1))
+        case "$status" in
+          ok) repo_ok=$((repo_ok + 1)) ;;
+          stale) repo_stale=$((repo_stale + 1)) ;;
+          unknown) repo_unknown=$((repo_unknown + 1)) ;;
+          missing-source) repo_missing_source=$((repo_missing_source + 1)) ;;
+          pinned) repo_pinned=$((repo_pinned + 1)) ;;
+          not-managed) repo_not_managed=$((repo_not_managed + 1)) ;;
+        esac
+        increment_status_total "$status"
       done < <(find "$root" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) -print | LC_ALL=C sort)
     fi
     if [[ "$agent" == "claude" ]]; then
@@ -361,7 +407,7 @@ scan_repo() {
     fi
   done
 
-  REPO_ROWS+=("${label}"$'\t'"${repo_path}"$'\t'"${exists}"$'\t'"${claude_count}"$'\t'"${codex_count}"$'\t'"${repo_status[ok]}"$'\t'"${repo_status[stale]}"$'\t'"${repo_status[unknown]}"$'\t'"${repo_status[missing-source]}"$'\t'"${repo_status[pinned]}"$'\t'"${repo_status[not-managed]}")
+  REPO_ROWS+=("${label}"$'\t'"${repo_path}"$'\t'"${exists}"$'\t'"${claude_count}"$'\t'"${codex_count}"$'\t'"${repo_ok}"$'\t'"${repo_stale}"$'\t'"${repo_unknown}"$'\t'"${repo_missing_source}"$'\t'"${repo_pinned}"$'\t'"${repo_not_managed}")
 }
 
 for i in "${!REPO_PATHS[@]}"; do
@@ -404,12 +450,12 @@ Report-only notice: this scan did not run refresh, delete, cleanup, install, or
 | Repositories scanned | ${TOTAL_REPOS} |
 | Agent skill roots found | ${TOTAL_AGENT_ROOTS} |
 | Skill installs inspected | ${TOTAL_INSTALLS} |
-| ok | ${STATUS_TOTALS[ok]} |
-| stale | ${STATUS_TOTALS[stale]} |
-| unknown | ${STATUS_TOTALS[unknown]} |
-| missing-source | ${STATUS_TOTALS[missing-source]} |
-| pinned | ${STATUS_TOTALS[pinned]} |
-| not-managed | ${STATUS_TOTALS[not-managed]} |
+| ok | $(status_total ok) |
+| stale | $(status_total stale) |
+| unknown | $(status_total unknown) |
+| missing-source | $(status_total missing-source) |
+| pinned | $(status_total pinned) |
+| not-managed | $(status_total not-managed) |
 
 ## Repositories
 
@@ -475,7 +521,7 @@ render_json() {
     idx=$((idx + 1))
     comma=","
     [[ $idx -eq ${#STATUS_ORDER[@]} ]] && comma=""
-    printf '    "%s": %s%s\n' "$status" "${STATUS_TOTALS[$status]}" "$comma"
+    printf '    "%s": %s%s\n' "$status" "$(status_total "$status")" "$comma"
   done
   printf '  },\n'
   printf '  "repositories": [\n'

package/packs/project-fleet/codex/clone-spec-store/ALIGNMENT-PAGE.md

@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-clone-spec-store-research.md`; product-path mode uses `research/{slug}/_working/preliminary-clone-spec-store-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-clone-spec-store-research.md`; product-path mode uses `research/{slug}/_working/preliminary-clone-spec-store-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Required inline questions.** In `review` pages, each gate must contain at least one required inline question placed directly under the content it governs, inside a visually distinct question block. Each question must use radio-button inputs and include two standing options after the skill-generated choices: "Other / None of the above" backed by a multi-line text box for free-form input, and "Need clarification" backed by an optional notes box where the user can explain what is unclear. When any radio option other than "Other" or "Need clarification" is selected, show an optional "Additional notes" text box beneath it so the user can qualify their choice. Generate questions based on what genuinely needs user input -- do not add filler questions. Do not create a separate bottom "Decisions & Clarifications" section. Confirmed pages must not keep these as required input controls; render the answered decisions as read-only records.
 

package/packs/project-fleet/codex/project-fleet/ALIGNMENT-PAGE.md

@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-project-fleet-research.md`; product-path mode uses `research/{slug}/_working/preliminary-project-fleet-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-project-fleet-research.md`; product-path mode uses `research/{slug}/_working/preliminary-project-fleet-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Required inline questions.** In `review` pages, each gate must contain at least one required inline question placed directly under the content it governs, inside a visually distinct question block. Each question must use radio-button inputs and include two standing options after the skill-generated choices: "Other / None of the above" backed by a multi-line text box for free-form input, and "Need clarification" backed by an optional notes box where the user can explain what is unclear. When any radio option other than "Other" or "Need clarification" is selected, show an optional "Additional notes" text box beneath it so the user can qualify their choice. Generate questions based on what genuinely needs user input -- do not add filler questions. Do not create a separate bottom "Decisions & Clarifications" section. Confirmed pages must not keep these as required input controls; render the answered decisions as read-only records.