@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/spec-sync/scripts/spec_drift_check.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("spec_drift_check");

package/toolkit/skills/spec-sync/scripts/test_spec_drift_check.ts

@@ -0,0 +1 @@
+import "../../bin/tests/docs/spec_drift.test.ts";

package/toolkit/skills/srv-101-ops/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: srv-101-ops
+description: "Search machine 101 (`192.168.31.11`) directly from the current local repo name and git remotes, then inspect `/home/ivan/srv` before any SSH ops."
+---
+
+# srv-101-ops
+
+Use this skill when the current working directory belongs to a local project that may be deployed on machine `101`.
+
+## Purpose
+
+This skill keeps application repositories free of deployment facts and does **not** depend on a local registry repository.
+
+- Remote machine-level truth: `/home/ivan/srv` on `192.168.31.11`
+- Search inputs: local repo basename plus git remote repo slugs
+- Default posture: read-only inspection first, live changes only after explicit user approval
+
+## Inputs
+
+- Current local repo path or repo basename
+- SSH alias `192.168.31.11`
+
+## Helper
+
+Resolve the current repo to remote search candidates with:
+
+```bash
+$LOOMHELM_TOOLKIT_ROOT/skills/srv-101-ops/scripts/resolve-target
+```
+
+Or point it at a specific repo/path:
+
+```bash
+$LOOMHELM_TOOLKIT_ROOT/skills/srv-101-ops/scripts/resolve-target /Users/ivan/Projects/Ivan/dockrev
+$LOOMHELM_TOOLKIT_ROOT/skills/srv-101-ops/scripts/resolve-target --json blog-nextjs
+```
+
+## Workflow
+
+1. Run `resolve-target` from the current project directory.
+2. Always read these remote root docs first:
+   - `/home/ivan/srv/AGENTS.md`
+   - `/home/ivan/srv/README.md`
+3. Let `resolve-target` search `/home/ivan/srv` using:
+   - local repo basename
+   - git remote repo slugs from the current repo
+   - running Docker Compose labels when a matching container exists
+4. Use the search result in this order:
+   - validated running Compose labels, to confirm/narrow a stack or identify one when no active exact stack directory conflicts
+   - exact stack directory matches
+   - compose hits (`docker-compose.yml`, `compose.docker.yml`)
+   - deployment cards whose filename matches the target slug
+   - content-only deployment-card hits (`*.md` under a stack), as weak evidence only
+   - maintenance hits (`/home/ivan/srv/maintenance/*.md`)
+5. If exactly one stack candidate is found, inspect that stack first:
+   - active compose file (`compose.docker.yml` preferred, then `docker-compose.yml`)
+   - matching deployment card(s)
+   - matching maintenance records
+6. Read-only checks first:
+   - `docker compose -f <compose_file> ps`
+   - `docker compose -f <compose_file> logs --tail=200`
+   - `docker ps --format ...` for matching containers
+7. If multiple candidates remain after the evidence precedence above, stop and ask the owner to choose. A dependency-only deployment-card hit does not establish stack ownership.
+8. If no deployment card matches the current project, do not deploy or roll back. Read-only inspection is allowed.
+9. If the owner explicitly requests a live change, follow the matched remote deployment card and keep maintenance notes on the remote `~/srv` repo.
+
+## Guardrails
+
+- Do not depend on `/Users/ivan/Projects/Ivan/infra-101-ops` or any local registry file.
+- Do not copy remote Compose files, secrets, deployment cards, or maintenance logs into local repos.
+- Ignore remote legacy artifacts: `docker-compose.legacy.yml`, `quadlet/`, `PODMAN-*`, `MIGRATION-TO-QUADLET*`, `QUADLET-*`.
+- Do not run `/home/ivan/srv/update-containers.sh` unless the owner explicitly asks for a bulk update.
+- If search yields zero or multiple stack candidates, report that state clearly instead of guessing.

package/toolkit/skills/srv-101-ops/scripts/resolve-target

@@ -0,0 +1,370 @@
+#!/usr/bin/env ruby
+require 'json'
+require 'open3'
+require 'optparse'
+require 'pathname'
+require 'set'
+require 'shellwords'
+
+SSH_ALIAS = '192.168.31.11'.freeze
+SRV_ROOT = '/home/ivan/srv'.freeze
+ROOT_DOCS = [File.join(SRV_ROOT, 'AGENTS.md'), File.join(SRV_ROOT, 'README.md')].freeze
+IGNORE_PATTERNS = [
+  'docker-compose.legacy.yml',
+  'quadlet/',
+  'PODMAN-*',
+  'MIGRATION-TO-QUADLET*',
+  'QUADLET-*'
+].freeze
+
+options = { format: :text }
+OptionParser.new do |opts|
+  opts.banner = 'Usage: resolve-target [--json] [repo-name-or-path]'
+  opts.on('--json', 'Output JSON') { options[:format] = :json }
+end.parse!(ARGV)
+input = ARGV.shift || Dir.pwd
+
+def shell_capture(*command)
+  stdout, stderr, status = Open3.capture3(*command)
+  [stdout, stderr, status.success?]
+end
+
+def ssh_capture(script)
+  shell_capture('ssh', '-n', SSH_ALIAS, "bash -lc #{Shellwords.escape(script)}")
+end
+
+def detect_repo(input)
+  path = Pathname(input).expand_path
+  if path.exist?
+    stdout, = shell_capture('git', '-C', path.to_s, 'rev-parse', '--show-toplevel')
+    repo_root = stdout.strip.empty? ? path : Pathname(stdout.strip)
+    [repo_root.basename.to_s, repo_root.to_s]
+  else
+    [File.basename(input.to_s), nil]
+  end
+end
+
+def remote_repo_slugs(repo_root)
+  return [] unless repo_root
+
+  stdout, = shell_capture('git', '-C', repo_root, 'remote', '-v')
+  slugs = []
+  stdout.lines.each do |line|
+    parts = line.split
+    remote = parts[1]
+    next if remote.nil? || remote.empty?
+
+    remote = remote.sub(%r{\A[^:]+@}, '') if remote.start_with?('git@')
+    remote = remote.sub(%r{\Assh://[^/]+/}, '')
+    remote = remote.sub(%r{\Ahttps?://[^/]+/}, '')
+    basename = File.basename(remote)
+    basename = basename.sub(/\.git\z/, '')
+    slugs << basename unless basename.empty?
+  end
+  slugs.uniq
+end
+
+def stack_from_path(path)
+  match = path.match(%r{\A#{Regexp.escape(SRV_ROOT)}/([^/]+)(?:/|\z)})
+  match && match[1]
+end
+
+repo_name, repo_root = detect_repo(input)
+search_terms = [repo_name, *remote_repo_slugs(repo_root)].compact.map { |term| term.to_s.strip }.reject(&:empty?).uniq
+
+exact_dirs = []
+compose_matches = []
+card_matches = []
+maintenance_matches = []
+container_hits = []
+container_inventory = []
+stack_candidates = Set.new
+exact_dir_stacks = Set.new
+exact_compose_stacks = Set.new
+compose_stacks = Set.new
+card_stacks = Set.new
+direct_card_stacks = Set.new
+weak_card_stacks = Set.new
+container_project_stacks = Set.new
+container_validated_project_stacks = Set.new
+container_working_dir_stacks = Set.new
+container_working_dir_matches = Set.new
+container_label_matches = []
+
+search_terms.each do |term|
+  stdout, = ssh_capture("command find #{SRV_ROOT} -mindepth 1 -maxdepth 1 -type d -name #{Shellwords.escape(term)} -print 2>/dev/null || true")
+  stdout.lines.map(&:strip).reject(&:empty?).each do |path|
+    exact_dirs << path
+    stack = stack_from_path(path)
+    if stack
+      stack_candidates << stack
+      exact_dir_stacks << stack
+      remote_compose_files = ['compose.docker.yml', 'docker-compose.yml'].map do |name|
+        Shellwords.escape(File.join(path, name))
+      end
+      compose_check = remote_compose_files.map { |compose_path| "test -f #{compose_path}" }.join(' || ')
+      stdout, = ssh_capture("(#{compose_check}) && printf yes || true")
+      exact_compose_stacks << stack if stdout.strip == 'yes'
+    end
+  end
+
+  stdout, = ssh_capture("command grep -RIlF -- #{Shellwords.escape(term)} #{SRV_ROOT}/*/compose.docker.yml #{SRV_ROOT}/*/docker-compose.yml 2>/dev/null || true")
+  stdout.lines.map(&:strip).reject(&:empty?).each do |path|
+    compose_matches << path
+    stack = stack_from_path(path)
+    if stack
+      stack_candidates << stack
+      compose_stacks << stack
+    end
+  end
+
+  card_script = [
+    "command grep -RIlF -- #{Shellwords.escape(term)} #{SRV_ROOT}/*/*.md 2>/dev/null",
+    "| command grep -v '#{SRV_ROOT}/maintenance/'",
+    "| command grep -v '/README.md$'",
+    "| command grep -v '/AGENTS.md$'",
+    "| command grep -v '/PODMAN-'",
+    "| command grep -v '/MIGRATION-TO-QUADLET'",
+    "| command grep -v '/QUADLET-'",
+    "|| true"
+  ].join(' ')
+  stdout, = ssh_capture(card_script)
+  stdout.lines.map(&:strip).reject(&:empty?).each do |path|
+    card_matches << path
+    stack = stack_from_path(path)
+    if stack
+      stack_candidates << stack
+      card_stacks << stack
+      if File.basename(path, '.md').casecmp?(term)
+        direct_card_stacks << stack
+      else
+        weak_card_stacks << stack
+      end
+    end
+  end
+
+  filename_card_pattern = Shellwords.escape("#{term}.md")
+  maintenance_glob = Shellwords.escape("#{SRV_ROOT}/maintenance/*")
+  stdout, = ssh_capture("command find #{SRV_ROOT} -mindepth 2 -maxdepth 2 -type f -not -path #{maintenance_glob} -iname #{filename_card_pattern} -print 2>/dev/null || true")
+  stdout.lines.map(&:strip).reject(&:empty?).each do |path|
+    card_matches << path
+    stack = stack_from_path(path)
+    if stack
+      stack_candidates << stack
+      card_stacks << stack
+      direct_card_stacks << stack
+    end
+  end
+
+  stdout, = ssh_capture("command find #{SRV_ROOT}/maintenance -maxdepth 1 -type f -name #{Shellwords.escape("*#{term}*.md")} -print 2>/dev/null || true")
+  stdout.lines.map(&:strip).reject(&:empty?).each do |path|
+    maintenance_matches << path
+  end
+
+  stdout, = ssh_capture("command docker ps --format '{{.Names}}\t{{.Image}}' 2>/dev/null || true")
+  stdout.lines.map(&:strip).reject(&:empty?).each do |line|
+    container_inventory << line
+  end
+end
+
+container_hits = container_inventory.uniq.sort
+matched_container_hits = []
+container_hits.each do |line|
+  container_name = line.split("\t", 2).first
+  next if container_name.nil? || container_name.empty?
+  image = line.split("\t", 2).last.to_s
+
+  label_template = "{{index .Config.Labels \"com.docker.compose.project\"}}\t{{index .Config.Labels \"com.docker.compose.service\"}}\t{{index .Config.Labels \"com.docker.compose.project.working_dir\"}}"
+  stdout, = ssh_capture(
+    "command docker inspect --format #{Shellwords.escape(label_template)} #{Shellwords.escape(container_name)} 2>/dev/null || true",
+  )
+  stdout.lines.map(&:strip).reject(&:empty?).each do |labels|
+    project, service, working_dir = labels.split("\t", 3)
+    next if project.nil? || project.empty? || project == '<no value>'
+
+    working_dir_stack = stack_from_path(working_dir.to_s)
+    label_values = [container_name, image, project, service, working_dir, working_dir_stack].compact
+    next unless search_terms.any? do |term|
+      label_values.any? { |value| value.downcase.include?(term.downcase) }
+    end
+
+    matched_container_hits << line
+
+    container_project_stacks << project
+    if (stack = working_dir_stack)
+      remote_working_dir = Shellwords.escape(working_dir)
+      remote_compose_files = ['compose.docker.yml', 'docker-compose.yml'].map do |name|
+        Shellwords.escape(File.join(working_dir, name))
+      end
+      compose_check = remote_compose_files.map { |path| "test -f #{path}" }.join(' || ')
+      stdout, = ssh_capture("test -d #{remote_working_dir} && (#{compose_check}) && printf yes || true")
+      if stdout.strip == 'yes'
+        container_working_dir_matches << stack
+        container_validated_project_stacks << project if project == stack
+      end
+    end
+    if project.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_-]*\z/)
+      remote_project_dir = File.join(SRV_ROOT, project)
+      remote_project_path = Shellwords.escape(remote_project_dir)
+      remote_project_compose_files = ['compose.docker.yml', 'docker-compose.yml'].map do |name|
+        Shellwords.escape(File.join(remote_project_dir, name))
+      end
+      project_compose_check = remote_project_compose_files.map { |path| "test -f #{path}" }.join(' || ')
+      stdout, = ssh_capture("test -d #{remote_project_path} && (#{project_compose_check}) && printf yes || true")
+      container_validated_project_stacks << project if stdout.strip == 'yes'
+    end
+    container_label_matches << [container_name, project, service, working_dir].compact.join("\t")
+  end
+end
+container_hits = matched_container_hits.uniq.sort
+
+known_stack_candidates = exact_dir_stacks | compose_stacks
+validated_working_dir_stacks = container_working_dir_matches & known_stack_candidates
+container_working_dir_stacks = validated_working_dir_stacks
+validated_project_stacks = container_validated_project_stacks & known_stack_candidates
+container_resolution_stacks = if known_stack_candidates.empty?
+  container_working_dir_matches | container_validated_project_stacks
+else
+  container_working_dir_stacks | validated_project_stacks
+end
+raw_stack_candidates = (stack_candidates | container_working_dir_matches).to_a.sort
+
+effective_stacks, resolution_basis = if !container_resolution_stacks.empty?
+  exact_container_stacks = exact_compose_stacks & container_resolution_stacks
+  if !exact_container_stacks.empty?
+    basis = (container_working_dir_stacks & exact_container_stacks).empty? ? 'docker-compose-project-label' : 'docker-compose-working-dir-label'
+    [exact_container_stacks.to_a.sort, basis]
+  elsif !exact_compose_stacks.empty?
+    [exact_compose_stacks.to_a.sort, 'exact-stack-directory']
+  else
+    basis = (container_working_dir_stacks & container_resolution_stacks).empty? ? 'docker-compose-project-label' : 'docker-compose-working-dir-label'
+    [container_resolution_stacks.to_a.sort, basis]
+  end
+elsif !exact_compose_stacks.empty?
+  [exact_compose_stacks.to_a.sort, 'exact-stack-directory']
+elsif !exact_dir_stacks.empty?
+  [exact_dir_stacks.to_a.sort, 'exact-stack-directory']
+elsif !compose_stacks.empty?
+  [compose_stacks.to_a.sort, 'compose-match']
+elsif !direct_card_stacks.empty?
+  [direct_card_stacks.to_a.sort, 'deployment-card']
+else
+  [[], 'none']
+end
+
+stacks = effective_stacks.uniq.sort
+status = if stacks.empty?
+  'not_found'
+elsif stacks.length == 1
+  'resolved'
+else
+  'ambiguous'
+end
+resolved_stack = stacks.length == 1 ? stacks.first : nil
+compose_files = []
+card_paths = []
+
+if resolved_stack
+  ['compose.docker.yml', 'docker-compose.yml'].each do |name|
+    remote_path = File.join(SRV_ROOT, resolved_stack, name)
+    stdout, = ssh_capture("test -f #{Shellwords.escape(remote_path)} && echo #{Shellwords.escape(remote_path)} || true")
+    compose_files.concat(stdout.lines.map(&:strip).reject(&:empty?))
+  end
+
+  card_paths = card_matches.select { |path| stack_from_path(path) == resolved_stack }.uniq.sort
+end
+
+payload = {
+  repo: repo_name,
+  repo_root: repo_root,
+  ssh_alias: SSH_ALIAS,
+  srv_root: SRV_ROOT,
+  remote_root_docs: ROOT_DOCS,
+  ignore_patterns: IGNORE_PATTERNS,
+  search_terms: search_terms,
+  status: status,
+  stack_candidates: stacks,
+  all_stack_candidates: raw_stack_candidates,
+  ignored_weak_candidates: raw_stack_candidates - stacks,
+  resolution_basis: resolution_basis,
+  resolved_stack: resolved_stack,
+  exact_dirs: exact_dirs.sort.uniq,
+  exact_dir_stacks: exact_dir_stacks.to_a.sort,
+  exact_compose_stacks: exact_compose_stacks.to_a.sort,
+  compose_files: compose_files,
+  card_paths: card_paths,
+  compose_matches: compose_matches.uniq.sort,
+  compose_stacks: compose_stacks.to_a.sort,
+  card_matches: card_matches.uniq.sort,
+  card_stacks: card_stacks.to_a.sort,
+  direct_card_stacks: direct_card_stacks.to_a.sort,
+  weak_card_stacks: weak_card_stacks.to_a.sort,
+  maintenance_matches: maintenance_matches.uniq.sort,
+  container_hits: container_hits,
+  container_label_matches: container_label_matches.uniq.sort,
+  container_project_stacks: container_project_stacks.to_a.sort,
+  container_working_dir_matches: container_working_dir_matches.to_a.sort,
+  container_working_dir_stacks: container_working_dir_stacks.to_a.sort,
+  validated_project_stacks: validated_project_stacks.to_a.sort
+}
+
+if options[:format] == :json
+  puts JSON.pretty_generate(payload)
+  exit(status == 'not_found' ? 2 : status == 'ambiguous' ? 3 : 0)
+end
+
+puts "repo: #{payload[:repo]}"
+puts "repo_root: #{payload[:repo_root] || '(not detected)'}"
+puts "ssh_alias: #{payload[:ssh_alias]}"
+puts "srv_root: #{payload[:srv_root]}"
+puts "status: #{payload[:status]}"
+puts 'remote_root_docs:'
+payload[:remote_root_docs].each { |path| puts "  - #{path}" }
+puts 'search_terms:'
+payload[:search_terms].each { |term| puts "  - #{term}" }
+puts 'stack_candidates:'
+if payload[:stack_candidates].empty?
+  puts '  - (none)'
+else
+  payload[:stack_candidates].each { |stack| puts "  - #{stack}" }
+end
+puts "resolved_stack: #{payload[:resolved_stack] || '(none)'}"
+puts "resolution_basis: #{payload[:resolution_basis]}"
+puts 'compose_files:'
+if payload[:compose_files].empty?
+  puts '  - (none)'
+else
+  payload[:compose_files].each { |path| puts "  - #{path}" }
+end
+puts 'card_paths:'
+if payload[:card_paths].empty?
+  puts '  - (none)'
+else
+  payload[:card_paths].each { |path| puts "  - #{path}" }
+end
+puts 'maintenance_matches:'
+if payload[:maintenance_matches].empty?
+  puts '  - (none)'
+else
+  payload[:maintenance_matches].each { |path| puts "  - #{path}" }
+end
+puts 'container_hits:'
+if payload[:container_hits].empty?
+  puts '  - (none)'
+else
+  payload[:container_hits].each { |line| puts "  - #{line}" }
+end
+puts 'container_label_matches:'
+if payload[:container_label_matches].empty?
+  puts '  - (none)'
+else
+  payload[:container_label_matches].each { |line| puts "  - #{line}" }
+end
+puts 'ignored_weak_candidates:'
+if payload[:ignored_weak_candidates].empty?
+  puts '  - (none)'
+else
+  payload[:ignored_weak_candidates].each { |stack| puts "  - #{stack}" }
+end
+
+exit(status == 'not_found' ? 2 : status == 'ambiguous' ? 3 : 0)

package/toolkit/skills/storybook-screenshots/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: storybook-screenshots
+description: "Capture Storybook docs or canvas screenshots for local review or PR evidence."
+---
+
+# Storybook screenshots for local review or PR visual evidence
+
+Use this skill when owner-facing local review evidence or PR visual evidence should come from Storybook component/fragment stories, Storybook docs pages, or a full page/app-shell Storybook fallback already authorized by `$ui-visual-evidence`.
+
+## Responsibility boundary
+
+- Supported source types:
+  - `source_type=storybook_canvas`
+  - `source_type=storybook_docs`
+- Both are treated as mock evidence (`target_program=mock-only`), not real-program screenshots.
+- This skill does not replace other image sources such as app pages, `ui_demo` pages, internal demo pages, or diagrams.
+- For full page/flow evidence, this skill is valid only after `$ui-visual-evidence` has already selected Storybook as the fallback source under an existing explicit page-level exception.
+- For PR URL rewriting/rendering safety, use the `pr_body_image_gate.ts` helper owned by `$ui-visual-evidence`.
+
+## Default behavior
+
+- If the change is component/fragment UI and Storybook is available, default to recommend `1-3` Storybook screenshots for local review; PR evidence can reuse the same stable asset set later with its own PR URLs.
+- If full page/flow evidence is explicitly authorized to fall back to Storybook, capture the complete page/app-shell story that represents the acceptance target.
+- Prefer `storybook_docs` when a docs page shows a useful state matrix or gallery in one view.
+- Prefer `storybook_canvas` when you need to prove one exact state or one interaction step.
+- For component/fragment/reusable-state evidence, capture the Story-owned presentation surface declared by `$storybook-stories`; do not add margin in the screenshot flow.
+- If a screenshot depends on a specific mobile/tablet/desktop viewport, bind that viewport in the Storybook surface first; browser window size is an implementation detail, not the primary evidence control surface.
+- The owner can reject screenshots. If rejected, record:
+  - `PR截图=不存在`
+  - `PR截图原因=主人拒绝`
+
+## What is a valid Storybook screenshot
+
+- Capture only the Storybook-rendered content area relevant to the evidence.
+- Never include Storybook chrome: sidebar, toolbar, addons panel, story list, or browser URL bar.
+- Never capture desktop fullscreen, the OS desktop, or unrelated windows.
+- Prefer stable states that map directly to acceptance criteria.
+- Prefer element-level capture of the rendered Storybook surface; use `capture_scope=browser-viewport` only when the whole rendered browser area is itself the evidence target.
+- Page fallback captures may trim excess edge whitespace. Component captures keep their declared source surface unchanged unless the preflight can crop only excess inside that surface.
+
+By source type:
+
+- `storybook_canvas`
+  - capture the component/fragment render viewport for one story, or an authorized full page/app-shell fallback story when no qualified `ui_demo` exists
+  - best for exact default/error/loading/success states or interaction checkpoints
+- `storybook_docs`
+  - capture the docs content area or a specific gallery/grid section
+  - best for multi-state overviews, component matrices, curated docs-first summaries, and page fallback state galleries
+
+## Evidence mapping (must)
+
+For each screenshot, include:
+
+- `source_type=storybook_canvas|storybook_docs`
+- `target_program=mock-only`
+- `capture_scope=element|browser-viewport` (prefer `element`)
+- `requested_viewport=<viewport key|WIDTHxHEIGHT|none>`
+- `viewport_strategy=storybook-viewport|browser-resize-fallback`
+- `margin_policy=trim_only|require_margin`
+- `evidence_surface=component|page`
+- `surface_selector` and `target_selector` for component evidence
+- `sensitive_exclusion=N/A` (or a short explicit note)
+- `submission_gate=pending-owner-approval|approved|rejected`
+- `story_id_or_title` for canvas captures
+- `docs_entry_or_title` for docs captures
+- `state` or `scenario`
+- `evidence_note` describing what implementation result the screenshot proves
+
+Rules:
+
+- `storybook_canvas` must include `story_id_or_title`
+- `storybook_docs` must include `docs_entry_or_title`
+- If a docs capture shows multiple states, use `scenario` to describe the gallery, for example `status matrix`
+- If story/docs coverage is insufficient, update/add Storybook coverage first or explain why it is not possible
+- If the requested proof still belongs to `ui_demo` or another locked non-Storybook source, return control to `$ui-visual-evidence` instead of reporting Storybook success here.
+- Do not report `视觉证据目标源=ui_demo` from this skill; that value belongs to `$ui-visual-evidence` after the demo/browser evidence path runs.
+- For component/fragment/reusable-state Storybook evidence, set `margin_policy=require_margin`, `evidence_surface=component`, and pass selectors for the source-managed surface and target.
+- For full page/app-shell Storybook fallback, set `margin_policy=trim_only` and `evidence_surface=page`.
+
+## Viewport-safe capture contract (must)
+
+- When requested viewport matters, carry `requested_viewport` and `viewport_strategy` metadata with the capture notes.
+- For mobile evidence, resolve the CSS viewport from owner, project, spec, and the selected story/docs surface before using the default `393x852` CSS px. When the default applies, bind the stable story/docs surface to it through the repo's Storybook viewport or scenario conventions, verify the rendered viewport, then record `requested_viewport=393x852`; if the surface cannot carry the viewport, return to `$storybook-stories` or report a blocker instead of applying capture-time emulation. Do not treat the size as physical pixels or device/User-Agent emulation.
+- Default Storybook path:
+  - choose or prepare a Storybook story/docs surface that already expresses the target viewport or responsive scenario;
+  - use `viewport_strategy=storybook-viewport` whenever Storybook-native viewport controls or story-bound viewport settings are sufficient;
+  - capture the rendered Storybook content as an element, not by resizing the browser window first.
+- `capture_scope=browser-viewport` is allowed only when the whole rendered browser area is the evidence target and element capture would lose the proof.
+- Do not use browser window resizing as the normal way to satisfy a Storybook viewport request.
+- `browser-resize-fallback` is the exceptional last resort:
+  - only after Storybook-native viewport handling cannot produce the requested proof;
+  - record the reason the normal path failed;
+  - restore the previous browser window size before handoff;
+  - if restoration fails, do not treat the resized browser session as final owner-facing state.
+
+## Capture selection guidance
+
+Prefer `storybook_docs` when:
+
+- one screenshot can prove several states at once
+- the docs page already lays out the intended review surface cleanly
+- the task is about comparing multiple variants or visual consistency
+
+Prefer `storybook_canvas` when:
+
+- the evidence is one exact state
+- the screenshot should stay tightly cropped around one component or page state
+- the proof depends on a single story's isolated rendering
+- no qualified `ui_demo` exists, an existing explicit page-level exception authorizes the fallback, and a complete page/app-shell fallback story is the selected evidence surface
+
+It is valid to mix both source types in one PR if that is the clearest evidence set.
+
+## Source-managed component capture (must)
+
+- A component capture performs exactly one DOM preflight before capture. It reads the declared `surface_selector` and `target_selector`, their rectangles, containment, overflow, and computed styles; it does not inject DOM, change styles, add padding, infer an image background, or persist a measurement receipt.
+- The selected Story source must expose an outer `[data-visual-evidence-surface]` and a contained `[data-visual-evidence-target]`. The target includes the component's complete visible bounds; the surface owns all outer space.
+- The surface must have an opaque, uniform, solid background from the active Story theme and no border, border radius, box shadow, gradient, image background, evidence-only color, card boundary, or nested-card appearance. Its background must be a natural extension of the Story, not a capture frame.
+- Compute `required_margin=clamp(round(long_edge * 0.02), 16, 48)` from the target rectangle. Measure left, top, right, and bottom target-to-surface margins once. Every side must be at least `required_margin`; no side may exceed `48px` in the final capture.
+- When one or more sides exceed `48px`, tighten only the capture rectangle within the declared surface, using the known DOM geometry to retain `48px` on those sides. This is a lossless crop of the source-managed surface, never an image-analysis crop.
+- Block and return control to `$storybook-stories` when a selector is missing, the surface is transparent or visually framed, the target escapes the surface, a margin is below `required_margin`, or a natural theme surface cannot be established. Report the measured selectors, rectangles, computed style failure, and per-side margins as the reason.
+- For a valid component surface, capture it unchanged when no side exceeds `48px`; do not call `trim_whitespace.ts --margin-policy=require_margin`. That compatibility mode intentionally blocks component image processing.
+- For page/app-shell fallback only, pass the raw image through `trim_whitespace.ts --margin-policy=trim_only`: it detects a mostly-uniform border background, trims edge-connected excess whitespace, preserves `clamp(round(long_edge * 0.02), 16, 48)` px where available, and otherwise retains the original image.
+- Do not use any normalization to cut into docs content areas, internal white gaps, or component/page padding.
+
+## Asset placement
+
+- If the screenshot is spec-related, newly added/replaced images MUST be stored in:
+  - `docs/specs/<topic>/assets/`
+- If the screenshot is legacy plan-related, newly added/replaced images MUST be stored in:
+  - the associated plan directory's `assets/` so `PLAN.md` can reference them via `./assets/<file>`
+- For spec/plan-related evidence, update the corresponding source-of-truth file section:
+  - preferred `SPEC.md` `## Visual Evidence` for `Spec:` / `Specs:`
+  - preferred `PLAN.md` `## Visual Evidence` for legacy `Plan:` / `Plans:`
+- If a historical spec/plan still has retired PR selectors or `## Visual Evidence (PR)`, run `bun --no-install skills/bin/visual_evidence_document.ts migrate --path <touched-spec-or-plan>` before handoff. Ambiguous sections containing images remain unchanged and require a manual decision.
+- Use `![alt](./assets/<file>)` entries as the visual-evidence source of truth inside the relevant section.
+- PR transport selection is task-scoped and must be passed explicitly to `pr_body_image_gate.ts` Phase A with repeated `--evidence` paths or `--no-evidence`; the owner-facing section is not a PR selector database.
+- If an image already exists in another repo path, do not relocate it only for PR formatting.
+
+## Local chat return path (must)
+
+- Storybook asset placement and chat image paths are different concerns.
+- Keep the canonical review asset in its repo/spec/plan path as usual.
+- Before showing any local Storybook image in chat, create an immutable snapshot with:
+  - `bun --no-install "${LOOMHELM_TOOLKIT_ROOT:?set packaged toolkit root}/skills/bin/snapshot_local_image.ts" --source <image-path> --cwd <working-dir>`
+- Use only the returned `snapshot_path` in chat Markdown.
+- Never point chat Markdown directly at `docs/specs/.../assets/...`, temporary Storybook capture files, or other mutable working paths.
+
+## Commit and push strategy (must)
+
+- For local-review-only captures, do not require a dedicated screenshot commit or any push.
+- If PR later reuses image files that were already committed during local review, do not require a new screenshot-only commit or history rewrite; pass the selected paths to the task-scoped PR gate as needed.
+- Use a dedicated screenshot-only commit only when this phase adds or replaces image files specifically for PR evidence after PR flow has already started.
+- Commit message convention for PR-bound screenshot commits:
+  - `chore(pr-screenshots): add visual evidence`
+  - `chore(pr-screenshots): refresh visual evidence`
+- Push dedicated screenshot commits separately from implementation commits, and treat that push as a dedicated visual-evidence phase.
+- Before pushing PR-bound screenshot changes, show the same image asset set in chat and ask the owner for explicit submit approval.
+- If owner approval is missing, do not push screenshot commits.
+
+When the owner asks to update/replace screenshots:
+
+- prefer replacing the existing screenshot commit only when this PR already has a dedicated screenshot phase commit
+- if the PR is reusing screenshots from earlier implementation commits, update the task evidence declaration without rewriting history
+- before force-pushing a true screenshot refresh, confirm rewrite safety
+- if rewrite safety cannot be confirmed, fall back to a new dedicated screenshot commit
+
+## PR body snippet (with metadata)
+
+```md
+## Visual Evidence
+
+- source_type: storybook_docs
+  docs_entry_or_title: Components/Button/Docs
+  scenario: state matrix
+  evidence_note: verifies primary, secondary, disabled, and loading button states in one review surface
+  image:
+  ![Button state matrix](https://<host>/<owner>/<repo>/blob/<pr_head_branch>/docs/specs/<topic>/assets/button-state-matrix.png?raw=1)
+
+- source_type: storybook_canvas
+  story_id_or_title: Components/Button/Loading
+  state: loading
+  evidence_note: verifies exact loading spinner placement
+  image:
+  ![Button loading](https://<host>/<owner>/<repo>/blob/<pr_head_branch>/docs/specs/<topic>/assets/button-loading.png?raw=1)
+```
+
+Do not maintain this block manually when the PR is spec-associated:
+
+- use `pr_body_image_gate.ts` Phase A once during PR creation (`PR.head.ref`)
+- do not rerun Phase A for ordinary pushes to the same PR branch
+- use `pr_body_image_gate.ts` Phase B once after merge (`merge_commit_sha`)
+
+## Final reply contract
+
+- Always report:
+  - `视觉证据=存在/不存在/未检查`
+  - `视觉证据目标源=storybook_docs|storybook_canvas|未确定`
+  - `空白裁剪=已裁剪/无需裁剪/不适用/未检查`
+- Always report local review status:
+  - `聊天回图=已展示/未展示/未检查`
+- Always report:
+  - `PR截图=存在/不存在/未检查`
+- Always report screenshot commit status:
+  - `截图提交=存在/不存在/不适用/未检查`
+- Always report policy status:
+  - `截图策略合规=存在/不存在/未检查`
+  - `目标程序声明=存在/不存在/未检查`
+  - `提交授权=存在/不存在/不适用/未检查`
+- If `视觉证据=存在`, the final reply must include the same screenshot asset set that was actually returned for local review in chat, even when `PR截图=不存在`.
+- For local screenshots, those chat markdown images must use the immutable snapshot paths returned from `snapshot_local_image.ts`.
+- If `PR截图=存在`, include the same screenshot asset set in the final reply, but keep transport URLs separate: Chat uses snapshot paths and the PR body uses GitHub-normalized Markdown links.
+- For component/fragment/reusable-state evidence, report `视觉证据=不存在` and `空白裁剪=不适用` when preflight blocks; include the measured reason and return to `$storybook-stories`. Report `空白裁剪=无需裁剪` when the declared surface is captured unchanged, and `空白裁剪=已裁剪` only when the DOM geometry tightened excess space inside that surface.
+- If screenshot generation was applicable but skipped, explain why in one line.

package/toolkit/skills/storybook-screenshots/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Storybook screenshots"
+  short_description: "Capture Storybook docs or canvas evidence for review"
+  default_prompt: "Use $storybook-screenshots to capture Storybook docs or canvas screenshots with a viewport-safe, element-first strategy. For mobile evidence, preserve owner, project, spec, and story/docs viewport choices before falling back to 393x852 CSS px; bind and verify the stable Storybook surface before recording it, or return to story coverage when that is unavailable. Full-page fallback capture is valid only after ui-visual-evidence confirms no qualified ui_demo and an existing explicit page-level exception; otherwise report a blocker. Avoid browser-window resizing except as a documented last resort, and do not replace an owner-locked non-Storybook source."