skillpacks 0.1.1 → 0.1.2

package/packs/project-fleet/codex/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/codex/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/codex/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/codex/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/codex/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/spin-off/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-spin-off-research.md`; product-path mode uses `research/{slug}/_working/preliminary-spin-off-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-spin-off-research.md`; product-path mode uses `research/{slug}/_working/preliminary-spin-off-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/release-ops/claude/branch-lifecycle/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — branch-lifecycle
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/branch-lifecycle-{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/branch-lifecycle-{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-branch-lifecycle-research.md`; product-path mode uses `research/{slug}/_working/preliminary-branch-lifecycle-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-branch-lifecycle-research.md`; product-path mode uses `research/{slug}/_working/preliminary-branch-lifecycle-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/release-ops/claude/branch-lifecycle/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2 - 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
 
 - Archived previous skill contract.

package/packs/release-ops/claude/branch-lifecycle/SKILL.md

@@ -2,7 +2,7 @@
 name: branch-lifecycle
 description: "Evaluate feature branches and decide whether to merge, salvage, keep open, or delete based on branch health, PR status, and stale-branch heuristics"
 type: ops
-version: v0.1
+version: v0.2
 argument-hint: "[--force] [list | pr [branch...] | review <branch-or-pr> | merge <branch-or-pr> | salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>] | cleanup]"
 ---
 
@@ -151,7 +151,7 @@ This is an exception workflow. The default repository policy is direct-to-primar
 
 ## 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/branch-lifecycle-{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/branch-lifecycle-{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/release-ops/claude/branch-lifecycle/archive/v0.1/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: branch-lifecycle
+description: "Evaluate feature branches and decide whether to merge, salvage, keep open, or delete based on branch health, PR status, and stale-branch heuristics"
+type: ops
+version: v0.1
+argument-hint: "[--force] [list | pr [branch...] | review <branch-or-pr> | merge <branch-or-pr> | salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>] | cleanup]"
+---
+
+# Branch Lifecycle
+
+Evaluate feature branches after review and drive one of four outcomes: `merge`, `salvage`, `keep-open`, or `delete`.
+
+This is an exception workflow. The default repository policy is direct-to-primary development on `main`/`master`; use this skill for legacy branches, externally introduced branches, explicit user requests for branch/PR work, or `agent-team` lane branches created by an approved parallel plan.
+
+## Arguments
+
+- **No args** or **`list`**: inventory candidate branches and recommend an action for each.
+- **`pr [branch...]`**: create PRs for branches that do not already have one and pass basic readiness checks.
+- **`review <branch-or-pr>`**: classify a branch or PR as `merge`, `salvage`, `keep-open`, or `delete`.
+- **`merge <branch-or-pr>`**: merge only if the strict merge gate passes.
+- **`salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>]`**: cherry-pick selected commits onto a fresh target branch.
+- **`cleanup`**: delete merged branches and prompt for stale unmerged branches.
+- **`--force`**: skip confirmations for safe-destructive actions (PR creation, approved merge, merged-branch deletion). Never skips confirmation for deleting an unmerged branch.
+
+## Process
+
+1. **Resolve repository context:**
+   - Detect the base branch in this order: repository default branch, `main`, then `master`.
+   - Run `git status` and report uncommitted changes before any mutating action.
+   - Use `gh` for PR metadata and merge operations when available. If `gh` is unavailable or unauthenticated, report that limitation and continue with local-only facts where possible.
+   - State clearly that normal solo-dev work should land directly on the base branch, not stay on a feature branch.
+
+2. **Build branch inventory:**
+   - Enumerate local branches except the current branch and base branch.
+   - For each branch, gather:
+     - Ahead/behind counts vs base: `git rev-list --left-right --count <base>...<branch>`
+     - Last commit date/author: `git log -1 --format="%cr|%an" <branch>`
+     - Unique commits vs base: `git log --reverse --oneline <base>..<branch>`
+     - PR status and checks, when a PR exists
+   - Flag a branch as **stale** when it has no open PR and its last commit is older than 30 days.
+
+3. **Apply the decision policy:**
+   - **Merge** only when all strict-gate checks pass:
+     - focused scope
+     - passing CI/tests or no required checks
+     - no merge conflicts
+     - approval requirements satisfied, or no required review
+     - no unresolved high-severity review findings
+   - **Salvage** when the branch is outdated, mixed in scope, or not merge-ready but contains specific commits worth keeping.
+   - **Keep-open** when the branch is active and still worth finishing on its current line of development.
+   - **Delete** when the branch is stale or below standards and no clearly valuable commits remain.
+   - Increase confidence in a `delete` recommendation when stale is combined with any of:
+     - behind base by 10 or more commits
+     - failing or missing checks on an abandoned PR
+     - obviously mixed or abandoned scope
+
+4. **Execute the requested subcommand** using the rules below.
+
+## Subcommand Actions
+
+### `list`
+
+1. Print a table with:
+   - branch
+   - age
+   - ahead/behind
+   - PR status
+   - checks
+   - recommendation
+2. Use `merge`, `salvage`, `keep-open`, or `delete` in the recommendation column.
+3. Include a brief reason for non-merge recommendations, such as `stale`, `mixed scope`, `behind base`, or `failing checks`.
+
+### `pr [branch...]`
+
+1. Use the supplied branches, or find local branches without an open PR.
+2. Refuse to create a PR for:
+   - the current branch
+   - the base branch
+   - branches already marked `delete`
+3. For each eligible branch:
+   - summarize commits unique to the branch
+   - confirm with AskUserQuestion unless `--force`
+   - create the PR with `gh pr create`
+4. If a branch is a better `salvage` candidate than a PR candidate, say so and do not open the PR automatically.
+
+### `review <branch-or-pr>`
+
+1. Resolve the target to a branch and, if present, its PR.
+2. Evaluate:
+   - scope focus
+   - CI/tests
+   - conflicts
+   - approval state
+   - stale status
+   - whether the branch contains a small set of clearly reusable commits
+3. Output:
+   - target summary
+   - branch facts
+   - findings
+   - recommended action: `merge`, `salvage`, `keep-open`, or `delete`
+   - the reason tied to the decision policy
+
+### `merge <branch-or-pr>`
+
+1. Resolve the target to an open PR. If the branch has no PR, stop and recommend `pr` or `salvage`.
+2. Re-check the strict merge gate.
+3. If any merge gate fails, stop and explain which requirement failed.
+4. Confirm with AskUserQuestion unless `--force`.
+5. Merge with squash by default: `gh pr merge <number> --squash`
+   - Respect `CLAUDE.md` if it specifies a different merge strategy.
+6. Report the merged PR and resulting commit hash.
+
+### `salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>]`
+
+1. Resolve the source branch and target base branch.
+   - Default target base is the detected repository base branch.
+   - If `--onto` is provided, use that branch as the target base.
+2. Show the commit list unique to the source branch in chronological order.
+3. Determine which commits to keep:
+   - if `--commits` is provided, use those SHAs in the given order
+   - otherwise, ask the user to choose commits explicitly
+4. Create a fresh target branch from the chosen base, using a name derived from the source branch such as `salvage/<source>-<date>`.
+5. Cherry-pick the selected commits in order.
+6. If a conflict occurs:
+   - stop immediately
+   - report the conflicted files and the standard `git cherry-pick --continue` / `--abort` next steps
+   - do not auto-resolve or continue
+7. Report the new branch name and the preserved commits.
+8. Never delete the source branch automatically after salvage.
+
+### `cleanup`
+
+1. Find merged branches and confirm deletion unless `--force`.
+2. Delete local merged branches with `git branch -d`.
+3. If the matching remote branch exists, delete it too after the same confirmation scope.
+4. Identify stale unmerged branches and print their recommendation reasons.
+5. Ask for confirmation before deleting each unmerged branch individually.
+   - Even with `--force`, never auto-delete an unmerged branch.
+6. If a stale branch looks salvageable, recommend `salvage` instead of deleting it immediately.
+
+## Constraints
+
+- Never force-push or rewrite history.
+- Never merge a PR that fails the strict gate.
+- Never auto-delete an unmerged branch.
+- Never auto-delete a source branch after salvage.
+- Never cherry-pick the full branch implicitly; salvage is commit-selective by default.
+- If the working tree is dirty and the requested action is mutating, warn first and stop unless the user explicitly wants to continue.
+- Prefer reporting and stopping over making branch-history decisions silently.
+
+
+## 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/branch-lifecycle-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/release-ops/claude/release/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — release
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/release-{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/release-{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-release-research.md`; product-path mode uses `research/{slug}/_working/preliminary-release-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-release-research.md`; product-path mode uses `research/{slug}/_working/preliminary-release-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/release-ops/claude/release/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2 - 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
 
 - Archived previous skill contract.

package/packs/release-ops/claude/release/SKILL.md

@@ -2,7 +2,7 @@
 name: release
 description: Version bump, generate changelog, tag, and prepare a release
 type: shipping
-version: v0.1
+version: v0.2
 argument-hint: "[patch|minor|major] or [specific version like 1.2.3]"
 ---
 
@@ -88,7 +88,7 @@ Manage the release ceremony: version bump, changelog generation, git tag, and op
 
 ## 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/release-{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/release-{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