| name | infocard-publish-sop |
| description | Use when creating or publishing an infocard through the mandatory .docs-to-promotion workflow. |
| version | 4.2.0 |
Infocard Publish SOP: .docs → Promotion → Main Checkout
Non-negotiable workspace boundary
All information-card work uses the primary infocard-pub checkout. The only valid lifecycle is:
Read-only research
→ .docs/<run-id>/<slug>/ authoring candidate, facts, evidence, assets, promotion-manifest.json
→ Publisher validates and promotes declared files into docs/ and assets/
→ local visual gate
→ build / verify / taxonomy / leak checks in primary checkout
→ narrow stage / commit / non-force push from primary checkout
→ cache-busted public HTTP, index, and visual recheck
Forbidden for every infocard run:
git worktree add/remove/prune, any worktree reuse, detached HEAD, branch handoff, or temporary clone;- any temporary information-card repository root;
- force-pushing main;
- Author writes to
docs/, assets/, generated indexes, or Git state;
- ordinary publishing triggering inventory, removal, cleanup, reset, stash, or clean of historical worktrees.
Existing worktrees and /tmp artifacts are a separate inventory/cleanup concern and require separate explicit authorization. A dirty primary checkout is ambient state to record and exclude, not a reason to create an alternate checkout.
Route
Use the light route only when there is one card, one complete primary source/user brief, no sensitive claim/risk trigger, no multi-source reconciliation requirement, and no shared batch. Otherwise use the full route with bounded Research A and, only when needed, Research B.
Creation-and-publication authorization authorizes this whole release chain unless the user explicitly requests draft-only or preview-only work. It does not authorize installing or configuring the subject tool.
Roles
Research
Research produces first-party facts, source boundaries, time-sensitive snapshots, claim verdicts, and evidence gaps. It does not write formal card files, create workspaces, build, commit, push, or publish.
Author
Author writes only under .docs/<run-id>/<slug>/:
card.html
card.html.meta.yaml
facts.json or research.md
theme-decision.json
promotion-manifest.json
visual/
assets/ (only declared assets)
The Author must not directly write formal docs/ or assets/, generated indexes, Git state, or /tmp files. It does not build, commit, push, or start Wiki sync.
Publisher
Publisher owns manifest validation, exact promotion, visual gate, build, static gates, narrow Git staging, commit/push, public verification, and closeout. It operates only in the primary checkout.
Bundle, sidecar, and manifest
Before authoring, create .docs/<run-id>/<slug>/publish-bundle.json and promotion-manifest.json.
Manifest requirements:
- every source is relative to the authoring directory;
- every target is repository-relative and only under
docs/ or assets/;
- reject absolute paths,
.., duplicate targets, missing sources, undeclared assets, screenshots, bundles, process files, secrets, and generated indexes;
- never promote
_index.yaml or index.html from .docs.
Every formal sidecar is one YAML mapping containing at least:
slug, path, category, title, desc, date, updated, tags,
author, source, source_url, style
path must exactly equal the manifest HTML target. date and updated use quoted YYYY-MM-DD HH:MM:SS; Publisher sets final promotion time. Theme evidence must be the validated .docs/<run-id>/<slug>/theme-decision.json produced by infocard-theme-assignment before candidate HTML is written. This SOP validates its selected theme against the sidecar, HTML, and visual evidence; it never generates candidates, ranks themes, or makes a second theme decision. Author delegation is blocked unless that decision exists; delegation context must not hard-code or preselect a concrete theme.
Promotion
- Record
git status --short in the primary checkout and preserve all ambient changes.
- Validate bundle, manifest, source paths, target paths, sidecars, theme agreement, and artifact allowlist.
- Copy only manifest-declared HTML, sidecars, and assets into formal
docs/ and assets/ targets.
- Inspect the exact promotion diff and record source/target hashes in the bundle.
- Do not promote a whole authoring directory or undeclared files.
For a batch, validate all manifests first, promote all declared artifacts, then build once in the same primary checkout.
Required visual gate before build / commit / push
After promotion, before build:
- render exact formal
docs/<slug>.html locally;
- capture desktop and 390px mobile evidence by delegating to
web-capture (which uses agent-browser --cdp 9222), including all relevant hero/body/table/code/risk/footer regions;
- Call
web-capture with the target tab / URL and the pc or mobile preset
web-capture returns screenshot paths and geometry checks- Do NOT embed
browser_exec built-in cdp() screenshot logic here — route all web screenshots through web-capture
- record explicit
critical / major / minor findings and bind screenshot manifest to current HTML SHA-256;
- run
npm run verify:visual-gate -- docs/<slug>.html;
- repair and recapture after every HTML/CSS/content/structure change;
- block commit/push on any critical or major defect.
Infrastructure-only capture or visual-review failure must be recorded as a visual failure attempt with an explicit evidence_gap, error category, and outcome. It is never visual pass, and must not fabricate screenshots or dispositions.
Visual exception policy (VISUAL_EXCEPTION_AFTER_MAX_REPAIRS)
The exception is eligible after at least 3 recorded visual failure attempts; 4 or more remain eligible. Attempts include real visual defects and screenshot/capture/visual-review infrastructure failures. This is not an automatic retry loop.
Each completed repair round still requires all of: change_made: true, fresh desktop and mobile screenshot evidence, and a fresh review disposition. Infrastructure failures are attempts, but are not completed repair rounds and may have no screenshot/review evidence. Every attempt must have a deterministic name, type (visual_defect or infrastructure_failure), and outcome.
The manifest must declare review_status: "VISUAL_EXCEPTION_AFTER_MAX_REPAIRS", visual_failure_attempts with at least three valid records, and valid completed repair_rounds records. Fewer than three attempts, missing/malformed/unrecorded attempts, stale evidence, or VISUAL_PENDING fail the gate. Do not infer the exception from prose or missing records.
The exception may pass only the visual gate and must disclose the attempt count, defect/infrastructure classification, unresolved findings, and evidence gap. Non-visual gates (theme, manifest/hash, build, verify, taxonomy, leak, Git, and public verification) remain blocking.
Final report wording:
视觉门禁：视觉失败尝试达到 N 次后例外放行（含基础设施失败 M 次）。仍遗留 critical=N、major=N、minor=N；基础设施证据缺口：……。该放行仅适用于视觉门禁，非视觉门禁均已独立通过。
A clean VISUAL_PASSED must not be reported as an exception.
Main-checkout gates and release
Terminal output truncation workaround: each command's stdout is truncated to ~1 line. Use OUT-OF-BAND verification after each step — do NOT rely on the command's own output as the exit condition.
Run, in the primary checkout:
npm run build
npm run verify
npm run fix-taxonomy
npm run check-leak
Then inspect every mutation. Stage only promoted artifacts, declared assets, current visual evidence, _index.yaml, and index.html; never use git add -A.
If remote main advances, reconcile once in the same primary checkout, regenerate affected indexes and visual evidence, then retry non-force push. A second integration failure is BLOCKED_AT_INTEGRATION.
Public verification requires cache-busted checks for:
https://ccwq.github.io/infocard-pub/docs/<slug>.html
/_index.yaml
/index.html
Verify expected identity and release-specific fingerprint, then capture fresh public desktop/mobile evidence. HTTP 200 alone is not release proof.
Update, rebuild, and timeout recovery
- New card vs update is decided before authoring through
infocard-update-vs-new-pattern.
- Theme changes rebuild a
.docs candidate around the selected theme skeleton, preserve required content, then promote through the same gate.
- Author timeout means inspect the declared
.docs/<run-id>/<slug>/ handoff. Continue valid artifacts or complete that directory; never search for or create a worktree.
- Build/sidecar failure gets one targeted repair and full gate rerun. Second failure is
BLOCKED_AT_LOCAL_GATE.
Closeout
Retain .docs/<run-id>/<slug>/. Report route, authoring path, manifest mappings, local build/static state, local visual state, content commit, public HTTP/index state, public visual state, and only terminal exceptions.
Do not start Wiki automatically. Do not list, prune, remove, or otherwise operate historical worktrees in ordinary closeout.
Acceptance checklist
Historical references
Historical worktree incident notes may be retained only for a separately authorized migration/cleanup investigation. They are not active publication instructions and must never be loaded to create, recover, publish, or clean a new information card.
