visual-artifacts v1: PR 1 static renderer and trust contract (#217)

* visual-artifacts: PR 1 static renderer and trust contract

Introduce bin/render-artifact.sh and the supporting libraries that
turn a Nanostack JSON artifact into a local, static HTML view under
$NANOSTACK_STORE/visual/. JSON remains canonical; the renderer is
strictly downstream and writes only to the visual root.

PR 1 wires the /plan renderer end to end. think, review, security,
qa, ship are reserved for PR 2 and exit 1 with a clear message;
journal and stack are reserved for PR 3 and exit 2; --interactive is
reserved for PR 4 and exits 2.

Key files:
- reference/visual-artifact-contract.md: normative contract.
- bin/lib/html-escape.sh: nano_html_escape, nano_attr_escape,
  nano_json_string. Every JSON-derived scalar passes through one of
  these before reaching HTML.
- bin/lib/visual-render.sh: shared page shell, CSP, locked trust
  badge wording (verified / unverified / tampered), output path
  safety, symlinked visual root rejection.
- bin/render-artifact.sh: argument parsing, source resolution via
  bin/find-artifact.sh, trust verification via
  bin/lib/artifact-trust.sh, schema validation via
  bin/lib/artifact-schemas.sh, manifest writer, /plan body renderer.
  Atomic write with $path.tmp.$$ rename.
- ci/e2e-visual-artifacts.sh: 49 checks across 9 cells (happy path,
  XSS, --strict integrity_missing, integrity_mismatch always fails,
  --out path safety, reserved features, --manifest-only, phase
  mismatch, symlinked visual root).
- ci/check-visual-artifact-templates.sh: 20 static checks for
  forbidden patterns (http://, https://, fetch, XMLHttpRequest,
  localStorage, document.cookie, eval) plus required markers (CSP,
  data-nanostack-visual, locked badge wording).
- .github/workflows/lint.yml: new visual-artifact-contract job that
  runs both checks on every push.

Trust contract:
- integrity_mismatch always fails with exit 3.
- integrity_missing fails under --strict (exit 3); without --strict
  the render proceeds and the badge shows 'unverified'.
- --out outside the visual root fails with exit 4.
- A symlinked visual root fails with exit 4.

Total: 69 contract checks locked in CI.

* visual-artifacts: fix legacy plan render and fresh-store --out

Two PR 1 pass 1 codex findings.

1. Legacy --from-session plan artifacts store .summary as a string,
   so jq -r '.summary.goal' aborted the body renderer under set -e.
   The schema warning was already emitted in the page head, but the
   body never reached the user. Normalize .summary and
   .context_checkpoint into objects at the top of render_plan_body
   (defaulting missing arrays to empty arrays), then read every
   field from the normalized JSON. Adds two regression cells:
   --from-session legacy plan + an artifact with both summary and
   context_checkpoint as strings.

2. --out under $NANOSTACK_STORE/visual was rejected on fresh stores
   because the visual root did not yet exist; the canonical
   walk-up landed on $NANOSTACK_STORE, which is outside the visual
   root. Pre-create the visual root before the safety check so
   realpath has a stable target. Adds a regression cell that
   confirms --out works when visual/ does not pre-exist.

Test count: 49 -> 59 (cells 9a, 9b cover the regressions).

* visual-artifacts: reject --out paths that escape visual/ via ".."

Codex PR 1 pass 2 caught a path-safety gap. A path like
$NANOSTACK_STORE/visual/new/../../outside.html passed the previous
"walk up to nearest existing ancestor" check because the 'new'
segment was missing on disk; the walk landed on visual/, the prefix
matched, and the final mv wrote to $NANOSTACK_STORE/outside.html
outside the visual root.

Replace the realpath walk-up with lexical normalization. The new
nano_visual_normalize_path resolves "." and ".." string-wise so
non-existent intermediate segments do not anchor the comparison.
Both the candidate path and the visual root are normalized
lexically; symlink protection on the visual root itself is still
provided by nano_visual_assert_safe_root.

Adds a regression cell that exercises the documented escape and a
check that no file is left behind outside visual/ after the
rejection.

Test count: 59 -> 61.

* visual-artifacts: canonicalize manifest paths under relative store

Codex PR 1 pass 3 finding. A relative NANOSTACK_STORE override
(e.g. NANOSTACK_STORE=.nano-rel) propagated into the renderer's
output_path, source path, and stdout. The visual artifact contract
requires output_path to be absolute, so the manifest emitted under
a relative store violated the contract.

After mkdir -p of the parent directories (so $(cd .. && pwd) has a
real target), resolve HTML_PATH, MANIFEST_PATH, and ART_PATH to
absolute via a small nano_resolve_abs helper. The fix runs late
enough that the path-safety check still operates on the caller's
literal --out string, and the manifest writer sees only absolutes.

Adds cell 9d: chdir to a fresh project, set NANOSTACK_STORE to a
relative ".nano-rel", render, and assert the stdout, manifest
output_path, and manifest source path are all absolute.

Test count: 61 -> 64.

* visual-artifacts: reject symlinked subdirectories under visual/

Codex PR 1 pass 4 finding. A pre-existing symlink under visual/
(for example visual/plan -> /tmp/outside) was accepted by mkdir -p
and the renderer's atomic mv then wrote the HTML or manifest into
the symlink target. nano_visual_assert_safe_root only guarded the
root itself, so the new path-safety contract was incomplete.

Add nano_visual_assert_safe_descend: walk from the visual root down
to (but not including) the leaf file, asserting -L is false at every
intermediate. render-artifact.sh calls it for both the HTML path and
the manifest path before mkdir -p runs.

Adds two regression cells: a symlinked visual/plan and a symlinked
visual/manifests, each confirming exit 4 and no file written
through the symlink target.

Test count: 64 -> 68.

* visual-artifacts: reject symlinked or directory leaves at output

Codex PR 1 pass 5 finding. The descend check walked every
directory component but stopped before the leaf, so an --out whose
final segment was a pre-existing symlink to a directory escaped
the path-safety contract: the atomic mv moved the temp file INTO
the symlink target instead of overwriting the link.

Extend nano_visual_assert_safe_descend to refuse leaves that are
symlinks (return 4) or directories (return 4). The renderer writes
a regular file at that path; symlinks and directories at the leaf
were never part of the contract.

Adds cell 9g: a symlinked leaf at --out and a directory at the
--out path. Both must exit 4 and leave no file in the symlink
target.

Test count: 68 -> 71.

* visual-artifacts: write to normalized path and lock other contracts

Three findings from codex PR 1 pass 6.

P1 — write to the normalized path
A path like --out $NANOSTACK_STORE/visual/link/../evil.html with
link a symlink to /tmp/outside collapsed lexically to visual/
evil.html and passed the safety check. The kernel still resolved
the original path at write time: it followed link to /tmp/outside,
took .. back to /tmp/, and wrote evil.html outside the visual root.
Reassign HTML_PATH and MANIFEST_PATH to their normalized form
before mkdir -p / mv so the kernel never traverses a `..` after a
symlinked component.

P2 — unique manifest stem per render
Two same-second renders shared a manifest stem, so the second
render overwrote the first manifest while the first HTML kept
pointing at the now-stale path. Append the renderer's PID to the
timestamp stem; each render-artifact.sh invocation is its own
process so the stem is unique across same-second invocations.

P3 — non-object JSON exits 1
A top-level array, string, or number artifact crashed jq -r
'.phase // ""' with exit 5 under set -e, violating the CLI
contract (exit 1 for input errors). Switch to `.phase?` so the
path error is suppressed and the existing phase-mismatch branch
returns exit 1 cleanly.

Adds three regression cells covering the symlink+.. bypass, the
same-second manifest uniqueness, and the three non-object JSON
shapes (array, string, number).

Test count: 71 -> 79.

* visual-artifacts: render does not mutate sprint session state

Codex PR 1 pass 7 finding. find-artifact.sh registers the producing
phase via session.sh phase-start as a convenience for downstream
skills; render-artifact.sh hitting that code path through --latest
made a strictly-downstream viewer mutate session.json. A user who
opened the latest plan as HTML would silently start a plan phase.

Add --no-session-sync to find-artifact.sh. The flag bypasses the
phase-start side effect while preserving every other behavior
(integrity checks, max-age filter, project matching).
render-artifact.sh now uses --no-session-sync on its --latest
lookup, restoring the read-only contract documented in
reference/visual-artifact-contract.md.

Adds cell 9l: start a session, snapshot phase_log, run a render,
assert phase_log is unchanged and plan is not flagged in_progress.

Test count: 79 -> 81.

* visual-artifacts: secure temp files and glob-safe path normalization

Codex PR 1 pass 8. Two findings.

P2 — predictable temp file
Temp filenames followed a guessable pattern ($HTML_PATH.tmp.<pid>).
An attacker with write access to a parent directory could
pre-create a symlink at that path, and bash's > redirect would
follow the symlink and write outside visual/.

Replace the manual temp naming with mktemp("$path.tmp.XXXXXX").
mktemp opens with O_EXCL so a pre-existing symlink races into a
clear failure (exit 4) instead of silent follow. The cleanup trap
keeps unlinking on early exit. Cell 9n verifies no .tmp.* leftover
after a successful render.

P3 — glob expansion during normalization
The IFS split inside nano_visual_normalize_path and
nano_visual_assert_safe_descend used an unquoted `set -- $raw`,
which performs pathname expansion against the current working
directory. An --out like "star*.html" could be silently rewritten
to a matching real filename, so the renderer wrote to a different
path than the caller asked for and the manifest recorded the wrong
output_path.

Save the current `set -f` state, disable globbing for the split,
and restore the previous state when the helpers return. Cell 9m
locks the contract: a literal glob path stays literal.

Test count: 81 -> 85.

* visual-artifacts: clean HTML temp under --manifest-only

Codex PR 1 pass 9. After the PR 1 pass 8 switch to mktemp for the
temp files, the --manifest-only branch moved the manifest into
place and disabled the cleanup trap, leaving the HTML temp file
behind. The intent of --manifest-only is "write no HTML artifacts",
so the leftover violated the contract and would accumulate stale
*.html.tmp.* files under visual/plan/ on every CI trust-check run.

Remove TMP_HTML explicitly in the --manifest-only branch before
disabling the trap. Cell 7 now also asserts zero *.tmp.* files
remain after a --manifest-only render.

Test count: 85 -> 86.

Author: garagon

.github/workflows/lint.yml

@@ -3766,3 +3766,19 @@ jobs:
             exit 1
           fi
           echo "OK: save-artifact.sh wires the per-phase validator."
+
+  visual-artifact-contract:
+    # Locks the Visual Artifacts v1 PR 1 contract: bin/render-artifact.sh
+    # writes static HTML under $NANOSTACK_STORE/visual/, escapes every
+    # JSON-derived string, ships a CSP, refuses unsafe output paths, and
+    # records source trust in a companion manifest. See
+    # reference/visual-artifact-contract.md.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Static template safety lint
+        run: ci/check-visual-artifact-templates.sh
+      - name: End-to-end render contract
+        run: ci/e2e-visual-artifacts.sh

bin/find-artifact.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # find-artifact.sh — Find the most recent artifact for a phase and project
-# Usage: find-artifact.sh <phase> [max-age-days] [--verify] [--require-integrity]
+# Usage: find-artifact.sh <phase> [max-age-days] [--verify] [--require-integrity] [--no-session-sync]
 # Example: find-artifact.sh plan 2 --require-integrity
 # Returns: path to most recent artifact, or empty + exit 1 if none found
 #
@@ -15,6 +15,15 @@
 #                         evidence. Added in the 2026-05-10 architecture audit
 #                         PR 2 so callers stop reimplementing the check.
 #
+# Read-only flag:
+#   --no-session-sync     skip the phase-start session registration that
+#                         find-artifact.sh otherwise performs as a
+#                         convenience for downstream skills. Used by the
+#                         visual renderer (render-artifact.sh), which is a
+#                         strictly downstream consumer and must not mutate
+#                         sprint state. Added in the Visual Artifacts v1
+#                         PR 1 round (codex pass 7).
+#
 # On failure, the reason goes to stderr in a stable format so callers can
 # categorize: "INTEGRITY FAILED: <path>" (mismatch) or
 # "INTEGRITY MISSING: <path>" (no .integrity field).
@@ -32,6 +41,7 @@ shift
 MAX_AGE=30
 VERIFY=false
 REQUIRE_INTEGRITY=false
+NO_SESSION_SYNC=false
 # The max-age argument is optional; detect it by shape so callers can
 # skip it and pass a flag in $2 (e.g. find-artifact.sh plan
 # --require-integrity). A leading dash means flag, not age. Codex
@@ -46,6 +56,7 @@ for arg in "$@"; do
   case "$arg" in
     --verify) VERIFY=true ;;
     --require-integrity) REQUIRE_INTEGRITY=true; VERIFY=true ;;
+    --no-session-sync) NO_SESSION_SYNC=true ;;
   esac
 done
 
@@ -73,7 +84,7 @@ done | sort -r | head -1)
 # recurse back to find-artifact.sh and hang). The phase stays
 # "in_progress" until save-artifact.sh completes it.
 SESSION_FILE="$NANOSTACK_STORE/session.json"
-if [ -f "$SESSION_FILE" ]; then
+if [ "$NO_SESSION_SYNC" = false ] && [ -f "$SESSION_FILE" ]; then
   # Cache the phase list extracted from session.json. Multiple find-artifact.sh
   # calls in one resolve.sh run reuse the same list; session.sh writes bump
   # session.json's mtime which invalidates the cache automatically.

bin/lib/html-escape.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# html-escape.sh — Shared HTML escape primitives for the visual artifact
+# layer. Used by bin/render-artifact.sh. Centralizing the escape rules
+# here makes the security contract testable: ci/check-visual-artifact-
+# templates.sh greps for direct printf of JSON values and fails if the
+# escape helpers are bypassed.
+#
+# Public functions (stdin -> stdout):
+#   nano_html_escape   text content. & < > " ' -> entities. Preserves newlines.
+#   nano_attr_escape   attribute content. Same set; stricter quoting.
+#   nano_json_string   string -> JSON-encoded literal (without surrounding quotes).
+#                       Used by the manifest writer when piping shell
+#                       strings into JSON without a jq round-trip.
+
+if [ "${_NANO_HTML_ESCAPE_LOADED:-0}" = "1" ]; then
+  return 0 2>/dev/null || true
+fi
+_NANO_HTML_ESCAPE_LOADED=1
+
+# Escape & < > " ' via awk. Replaces ampersand FIRST so later
+# replacements do not double-encode the entity prefix. Reads stdin and
+# writes to stdout. Newlines pass through untouched.
+nano_html_escape() {
+  awk '
+    BEGIN { OFS = "" }
+    {
+      gsub(/&/, "\\&amp;")
+      gsub(/</, "\\&lt;")
+      gsub(/>/, "\\&gt;")
+      gsub(/"/, "\\&quot;")
+      gsub(/\047/, "\\&#39;")
+      print
+    }
+  '
+}
+
+# Attribute content uses the same character set. Kept as a separate
+# function so future hardening (for example, encoding the equals sign
+# or backtick inside attribute context) lands in one place. Reads
+# stdin and writes to stdout.
+nano_attr_escape() {
+  awk '
+    BEGIN { OFS = "" }
+    {
+      gsub(/&/, "\\&amp;")
+      gsub(/</, "\\&lt;")
+      gsub(/>/, "\\&gt;")
+      gsub(/"/, "\\&quot;")
+      gsub(/\047/, "\\&#39;")
+      print
+    }
+  '
+}
+
+# JSON-string escape. We delegate to jq when available because jq
+# already implements the full RFC 8259 escape set (control characters,
+# \uXXXX for non-ASCII). The output includes surrounding double
+# quotes; callers strip them with `${var:1:-1}` when embedding inside
+# a larger jq filter, or use the quoted form for raw concatenation.
+nano_json_string() {
+  if command -v jq >/dev/null 2>&1; then
+    jq -Rs '.'
+  else
+    # Minimal fallback. Escapes the characters that break JSON strings.
+    # Loses control-character handling beyond newline; that is
+    # acceptable because the visual layer pipes everything through jq
+    # when jq is on PATH, which is a Nanostack requirement enforced
+    # elsewhere.
+    awk '
+      BEGIN { ORS = ""; printf "\"" }
+      {
+        s = $0
+        gsub(/\\/, "\\\\", s)
+        gsub(/"/, "\\\"", s)
+        gsub(/\t/, "\\t", s)
+        printf "%s", s
+        printf "\\n"
+      }
+      END { printf "\"\n" }
+    '
+  fi
+}