Skip to content

visual-artifacts: contract doc audit cleanup#223

Merged
garagon merged 1 commit into
mainfrom
visual-artifacts-contract-audit-cleanup
May 12, 2026
Merged

visual-artifacts: contract doc audit cleanup#223
garagon merged 1 commit into
mainfrom
visual-artifacts-contract-audit-cleanup

Conversation

@garagon
Copy link
Copy Markdown
Owner

@garagon garagon commented May 12, 2026

Summary

Self-audit of reference/visual-artifact-contract.md against the shipped code. Doc-only; no behavior change. Closes 6 drift / gap items and improves 4 more.

Closes

ID Severity Fix
C-1 / C-7 P3 Exit-code table now covers mktemp failures for HTML temp, manifest temp, and scratch dir (all exit 4 as unsafe-environment signal).
C-3 P3 --latest documents the 30-day max-age window and how to bypass it (pass an explicit <artifact-path>).
C-4 P3 nano_visual_safe_screenshot_path documented as a reserved helper for a future QA-screenshot PR; explicitly NOT wired in v1. Addresses architect's hardening backlog item #1.
C-5 P3 Interactive script body lint contract spelled out (CI greps for absence of each forbidden API + presence of navigator.clipboard.writeText).
C-8 P3 Exit 3 row states aggregate strict mode runs BEFORE --manifest-only early exit, matching the PR 3 pass 3 lock.
C-9 P3 Stack cycle error names every unresolved node in the "Stack invalid" notice.

Clarifies

ID Topic
C-2 custom/<phase>/ subdir labeled as reserved plumbing (helper exists, no v1 caller passes custom=true).
C-6 Manifest .phase field records the CLI kind (plan/journal/stack), not the stack name. Stack name lives in the synthetic stack:<name> source entry.
C-10 Filename stems are NOT stable across renders (PID + new timestamp every time); consumers needing a "latest" handle should re-render or read the most recent manifest by created_at.

Codex review trail (1 pass, clean)

Pass 1: clean. "The change only updates the visual artifact contract documentation, and the added statements align with the current renderer behavior closely enough that no actionable correctness issues were found."

Test plan

  • ci/check-visual-artifact-templates.sh 38/38
  • ci/e2e-visual-artifacts.sh 330/330
  • visual-artifact-public-copy lint: presence + framing both green
  • Codex pass 1 returned clean

Self-audit of reference/visual-artifact-contract.md against the
shipped code. No code change; doc-only clarifications that close
6 small drift / gap items and improve 4 more.

Closes:
- C-1 / C-7: exit-code table now covers mktemp failures for HTML
  temp, manifest temp, and scratch dir (all return exit 4 as an
  unsafe-environment signal).
- C-3: --latest documents the 30-day max-age window and how to
  bypass it by passing an explicit artifact path.
- C-4: nano_visual_safe_screenshot_path documented as a reserved
  helper for a future QA-screenshot PR; explicitly NOT wired in
  v1. Architect's hardening backlog item #1.
- C-5: interactive script body lint contract spelled out (CI greps
  for absence of each forbidden API plus presence of
  navigator.clipboard.writeText).
- C-8: exit 3 row now states aggregate strict mode runs BEFORE
  --manifest-only early exit, matching PR 3 pass 3 lock.
- C-9: stack cycle error names every unresolved node in the
  invalid notice.

Clarifies:
- C-2: custom/<phase>/ subdir labeled as reserved plumbing (helper
  exists, no v1 caller passes the custom=true flag).
- C-6: manifest .phase field semantics: records the CLI kind
  (plan / journal / stack), not the stack name. Stack name lives
  in the synthetic stack:<name> source entry.
- C-10: filename stems are NOT stable across renders (PID + new
  timestamp every time); consumers needing a "latest" handle
  should re-render or read the most recent manifest by created_at.

Verification:
- ci/check-visual-artifact-templates.sh 38/38
- ci/e2e-visual-artifacts.sh 330/330
- visual-artifact-public-copy lint: presence + framing both green
@garagon garagon merged commit 33b49e8 into main May 12, 2026
63 checks passed
@garagon garagon deleted the visual-artifacts-contract-audit-cleanup branch May 12, 2026 00:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant