Viewing Artifacts
One self-contained page answers "what is the state of my SDLC work, and what
needs attention?" from the .sdlc-skills/ artifact trail. Every value on it
is derived from a real marker; where no marker exists the page says unknown.
The page carries state, not documents.
When to use
- The user asks for the state, progress, or drift of their SDLC work — what needs attention, how far each initiative is, what changed after a downstream artifact consumed it — or asks to see the trail as a page.
- Skip when a specific artifact must be read, created, or edited: that is the owning skill's work, and this skill never mutates the trail.
- Skip when there is no trail and nobody asked for its state.
Available scripts
scripts/start-server.shandscripts/stop-server.sh— start and stop the governed localhost preview (per-session key, owner watchdog, idle timeout). They wrapscripts/serve.py; never run another server.
Step 1: Read the trail
Resolve the project root: the main checkout, even from a linked task worktree. When the common git directory is not a checkout's
.git(a submodule, a separate git directory, a bare repository's worktree), the root is the current checkout's top.if common="$(git rev-parse --git-common-dir 2>/dev/null)" && common="$(cd "$common" && pwd -P)"; then case "$common:$(unset GIT_DIR GIT_WORK_TREE; git -C "${common%/.git}" rev-parse --is-bare-repository 2>/dev/null)" in */.git:false) root="${common%/.git}" ;; *) root="$(git rev-parse --show-toplevel 2>/dev/null)" || root="$PWD" ;; esac else root="$PWD" fiRead
$root/.sdlc-skills/:briefs/,specs/,designs/,plans/,verification/,audits/,post-mortems/. A folder that is absent means that phase was never reached.If there is no
.sdlc-skills/, render the template's empty state, which names what produces artifacts. Read an artifact kept at a user-set path only where a recorded pointer names it: a pointer field, theLocationof a row in a ledger, or a plan's bound inputs. If a recorded path cannot be read, that artifact's values are unknown, and Step 3.3 names the cause class. Never search the filesystem for look-alikes.Read
references/state-derivation.mdbefore deriving a value, and derive every value by its rules. Where no value can be derived, say unknown.
Step 2: Render
- Open
assets/page-template.htmlbefore filling anything. Follow its top-of-file and region comments: region order, repeats, omissions, allowed values. Fill every region it marks. - Entity-encode every artifact-derived value before inserting:
&first, then<,>,". Derived values go in as text, except two attribute values the template needs: a topic anchorhref,#topic-plus an allowlisted slug; and an open-filehrefor visualsrc, the path of a file read in Step 1, relative toviews/index.htmland starting with../. Never write a URL or a scheme intohreforsrc. - Before writing, run
git check-ignore -qon the view path. If the path is not ignored, and a verification or review is bound to this checkout's state, ask whether to write it there and stop until the user answers: the write is content, and it changes the hash of that state. A status question is not consent to that. - Write exactly one file:
$root/.sdlc-skills/views/index.html, never one inside a linked task worktree unless Step 1.1 resolved the root there. Createviews/if missing. No external URLs, no JavaScript, no scratch or backup files. Regeneration recomputes from the trail and rewrites in place; never merge a previous render.
Step 3: Deliver
Deliver the file path and offer to serve the page, root
.sdlc-skills/, entryviews/index.html; when the invoking skill holds an open decision, deliver the path only and leave the offer to it. Start the server from$root, only after the user accepts:bash scripts/start-server.sh --root .sdlc-skills --entry views/index.htmlHand over the printed URL. If serving fails or the user declined, the file path stands. If the script reports
needs python3, say so, name the platform's install route, and deliver the file path. Install a runtime only on explicit request.Reply in one short message: path or URL, as-of UTC, every place the page says unknown or omitted a block, whether a drift flag came from file modification times, and the cause class of any ledger pointer that could not be honored.
When the preview is no longer needed, run
bash scripts/stop-server.sh {{pid}}with thepidfrom the startup record.
Gotchas
- Run without
--root,bash scripts/start-server.shexits 1 withneeds --root DIR, and the file-path fallback in Step 3.2 hides that no preview started. - A status request is not consent to a background listener: a preview started unasked opens a local port the user never agreed to.
- From a linked task worktree, the
.sdlc-skills/beside the worktree's files is absent or an older committed copy: reading it shows a false empty trail, and a view written there changes the hash of the state that a pending verification or review is bound to. - In a checkout whose own state is the one under verification or review, a view written under a trail the project does not ignore still changes that checkout's hash.