visual-artifacts: contract doc audit cleanup#223
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Self-audit of
reference/visual-artifact-contract.mdagainst the shipped code. Doc-only; no behavior change. Closes 6 drift / gap items and improves 4 more.Closes
mktempfailures for HTML temp, manifest temp, and scratch dir (all exit 4 as unsafe-environment signal).--latestdocuments the 30-day max-age window and how to bypass it (pass an explicit<artifact-path>).nano_visual_safe_screenshot_pathdocumented as a reserved helper for a future QA-screenshot PR; explicitly NOT wired in v1. Addresses architect's hardening backlog item #1.navigator.clipboard.writeText).--manifest-onlyearly exit, matching the PR 3 pass 3 lock.Clarifies
custom/<phase>/subdir labeled as reserved plumbing (helper exists, no v1 caller passescustom=true)..phasefield records the CLI kind (plan/journal/stack), not the stack name. Stack name lives in the syntheticstack:<name>source entry.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.sh38/38ci/e2e-visual-artifacts.sh330/330visual-artifact-public-copylint: presence + framing both green