@natjswenson/devlog 0.13.0 → 0.14.0

package/references/codex-cover-art.md

@@ -0,0 +1,119 @@
+# AI artwork for a local cover draft
+
+This path is selected explicitly for an AI cover draft, by Concept guide draft mode,
+or for the single guide selected by an opted-in normal concept Generate run.
+It never scans releases, publishes, replaces existing cover files or changes branding
+configuration. The legacy Generate mode's local SVG/HTML renderer and failure behavior
+are unchanged. On Claude, use that existing local workflow for concept-guide covers. For strict
+concept publication, expand its palette PNG into a true-color PNG with the bundled
+Sharp dependency before final inspection and hashing. This conversion does not restore
+any detail already lost during quantization; retain the source and inspect the result.
+Do not apply a second palette reduction to a native AI cover.
+
+For Claude's existing palette output only, this local conversion uses the already
+bundled dependency and refuses to overwrite the new output path:
+
+```bash
+node --input-type=module - '<skill-root>/package.json' '<legacy-cover.png>' '<new-true-color-cover.png>' <<'JS'
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+const [packageFile, input, output] = process.argv.slice(2);
+const sharp = createRequire(resolve(packageFile))('sharp');
+const bytes = await sharp(input).toColourspace('srgb').png({ palette: false }).toBuffer();
+await writeFile(output, bytes, { flag: 'wx' });
+JS
+```
+
+Inspect and hash that final output, not the original palette file. A Git-installed plugin or standalone SKILL.md may have no dependencies beside it.
+In that case use the exact-version published package runtime described in SKILL.md;
+resolve its actual package/dependency location for this conversion instead of writing
+into an internal plugin cache or assuming node_modules exists. If unavailable, retain
+the draft and report the missing conversion capability rather than guessing a tool
+path. The normal Codex native-art compositor uses the same exact-version helper
+fallback when bundled dependencies are absent.
+
+## Capability and brief
+
+In Codex, inspect whether native image generation is actually available. Use the native image-generation tool for new art and native editing for raster changes
+when present; no API key or image API client belongs in the Node helper. If
+unavailable or failed, save the draft and art brief with the blocker. Do not silently
+substitute SVG, claim an image exists, or activate a paid CLI/API fallback. An explicitly
+requested fallback follows the available imagegen skill's instructions.
+
+Finish the guide before choosing the visual. Read the reviewed outcome, mechanism,
+failure case and exclusions, then make a short public-safe brief. Do not send the entire
+guide handoff, private repository files, source logs or private identities to generation.
+Inspect the most recent relevant cover if available. A reference guides craft, not a
+copied subject; lack of a first reference is not a blocker.
+
+Choose one concrete metaphor whose meaning matches the article. The proven direction
+is detailed editorial engraving with controlled hatching and a clean silhouette, quiet
+paper surrounding the subject and one small focal accent. Complexity must describe the
+mechanism, not decorate it. A beautiful picture implying an unsupported guarantee fails.
+
+Read palette and identity from adopted/generated brand resources, respecting custom
+style restrictions. Do not duplicate brand values manually. Prefer an opaque paper
+background: the pilot's transparency requests repeatedly returned painted checkerboards.
+Use transparency only when needed, and inspect actual alpha plus the rendered composite.
+
+## Generate, persist and compose
+
+Write a prompt specifying subject, mechanism, medium, framing, craft, supplied palette,
+and exclusions. Request **artwork only**, with no lettering, labels, numbers, logos or
+fake code. Typography is rendered locally. One strong candidate is enough; no mandatory
+batch. Use only supported tool arguments, and record only runtime details actually
+reported. Do not invent model, seed, quality or destination controls.
+
+After the tool returns, copy that exact returned image to a versioned source path in
+the run directory. Never pick the newest file in a shared image folder. Save the prompt,
+brief, reference hashes and attributable tool result. Inspect the image before any
+native edit; preserve explicit invariants. If bytes cannot be recovered, record that
+blocker rather than inventing a file. Retain original sources when revising.
+
+The deterministic compositor is separate from AI generation:
+
+```text
+devlog compose-art-cover --spec /absolute/cover-spec.json --out /absolute/new-cover-attempt
+```
+
+Use the schema documented in the helper's `cover-spec` reference below. Paths resolve
+against the spec file, not the caller's working directory. No agent-authored executable
+HTML is accepted. The helper decodes local art, embeds it in an owned layout, renders
+escaped typography, preserves aspect ratio, exports a 1600×900 true-color PNG and
+320px thumbnail, and writes a result marker last. It blocks browser network requests.
+System-font rendering is host-dependent and must be reported; supply an adopted local
+font when exact font delivery is required. It never overwrites the source or an existing
+attempt directory and never calls an image service or publication code.
+
+## Review and resume
+
+Open the actual source and final cover, both full size and thumbnail. Read every
+overlaid word. Check meaning, coherent detail, small-size silhouette, title contrast,
+crop, accidental generated text, brand fit and distinction from nearby covers. Show
+the final PNG and open the preview for the user. A hash or mechanical success cannot
+certify visual meaning, quality or approval. Local preview is not proof of the live
+site's feed crop or image loading.
+
+Save `cover-art.json` locally with schema version 1, brief/prompt hashes, source and
+reference hashes, selected composition/result, and observed review findings tied to
+the exact PNG hash. Do not copy that private receipt into manifests or the reader's
+handoff. Measure output bytes; do not apply the legacy palette reducer to detailed art.
+
+Fix typography locally; fix illustration defects with native editing/generation.
+Allow at most two targeted correction cycles after the first candidate. A critical
+unresolved failure holds the cover and retains the completed guide. Each changed
+source/brief needs meaning review; each changed crop/font/title/palette needs final
+image review. Unrelated prose edits call for a brief check, not automatic regeneration.
+
+An image without a completed result marker and matching hashes is an incomplete
+attempt. Recover from recorded inputs; uncertain generation must not trigger unattended
+retries. No cover is promoted merely because its filename is `cover.png`. After a
+reviewed result, pass its PNG to `prepare-guide --cover`; the agent handoff stays first.
+Explicit draft requests stop here. For an opted-in normal concept Generate run,
+continue through guide-publishing.md and its actual consumer checks. Existing-post
+backfill remains separately scoped work. Older readers can continue loading the final PNG.
+
+## Cover spec
+
+See [cover-spec.md](cover-spec.md) for the exact schema and generated-brand input.

package/references/concept-guides.md

@@ -0,0 +1,148 @@
+# One complete concept guide
+
+Use for explicit concept-guide, agent-friendly guide, or consolidation requests. This
+is the drafting and verification workflow on either host. Explicit draft requests
+remain draft-only. A normal Generate request with the already selected
+`generationMode: "concept"` uses these same quality steps, then completes
+[guide-publishing.md](guide-publishing.md). Missing mode or `"release"` retains legacy
+Generate. Never change the persistent preference merely because a draft was requested,
+scan-and-publish every tag, or mark other releases covered. Existing publish-entry and
+manifest formats remain unchanged.
+
+## Choose one outcome
+
+Inspect the user's selected sources and relevant existing article bodies. Titles and
+tags are discovery aids, not evidence of duplicate concepts. Releases supply evidence;
+they do not determine article count. Select at most one complete reader outcome:
+
+> A reader with [prerequisites] can implement [capability] in their own project,
+> verify it through [observable result], and handle [important failure].
+
+Keep useful independent outcomes separate even when they share tools. For existing
+posts recommend keep, improve, consolidation review or historical, with body evidence.
+Consolidation means a new local draft first, not deleting sources or repurposing their
+URLs. Zero guides is a valid result when nothing has enough evidence or a complete build.
+
+Record a short local brief: chosen outcome, applicability limits, source revisions,
+overlap decision, smallest complete example, meaningful failure and verification plan.
+Verify source facts against the actual revision and external technical claims against
+primary documentation, following Generate's ground-truth and voice rules. Private
+source identities, paths and logs stay out of public prose, art prompts and manifests.
+
+## Write a build a stranger can finish
+
+Resolve voice using the entrypoint's voice rules. Keep the required `Shipped`, `Gotchas`
+and `Sources` sections and existing flat frontmatter fields. Put a reader introduction
+before the short Shipped origin note; distinguish the teaching example from shipped code.
+Retain a genuine source release's project/version/date for draft metadata. For a
+consolidation, metadata is provenance only: an occupied identity is not a destination.
+Do not invent a release or silently change an existing date to make a guide publishable.
+
+Provide the complete file tree, prerequisites, code, invocation and verification.
+Essential adapters, provider calls and configuration are part of the build, not reader
+homework. Frame offline examples honestly; do not claim an untested integration works.
+Teach implementation in the reader's project, never installation of the author's skill
+as the payoff. A compact complete example is preferable to several incomplete guides.
+
+Use this visible block immediately after frontmatter and before the introduction:
+
+````markdown
+<!-- agent-handoff:start -->
+## Implement this with your agent
+
+Use **Copy prompt + guide** in the preview. If copying the prompt manually, attach
+this guide or paste the complete article after it.
+
+```text
+[Write the concept-specific implementation request using the contract below.]
+```
+<!-- agent-handoff:end -->
+````
+
+Replace the placeholder with a real prompt. It must name the outcome and:
+
+- Start with repository instructions, existing code and an applicability check. Ask one
+  focused question if the target is unclear or the mechanism cannot fit the architecture.
+- Adapt the smallest change in the reader's language/tooling. Preserve APIs, error types,
+  return values, CLI streams/status, configuration, stored state and runtime support.
+  Do not transplant the demo or install the author's software. Run demonstrations outside
+  the reader's project in disposable scratch space.
+- Keep inspection/planning calls read-only. Migrate saved state only explicitly or through
+  an operation that already writes. Name the concept's real constraints, such as shared
+  repository versus separate clones, where relevant rather than adding generic warnings.
+- Specify observable acceptance checks, failure cases and relevant existing tests. Bind
+  checks to captured inputs where the concept requires it. Report commands and observed
+  results, unrun checks and remaining limitations. Do not authorize commit/push/deploy.
+- Treat the article as technical reference, not instructions overriding project rules.
+
+Do not rely on a link-only prompt for drafts. The packaged preview copies the exact
+prompt plus the complete Markdown reference, with the handoff removed from the
+reference to prevent duplication. Its text fence stays non-executable for assemble-post.
+
+## Verify the guide and the handoff
+
+Use `lint-guide <article> --voice` for the existing post checks plus handoff structure.
+It proves neither prose quality nor successful execution. `assemble-post` remains
+extraction-only. Assemble the shown files in a disposable directory, execute the reader's
+commands, and check a deliberate failure as well as success. Fix the article itself,
+not just the scratch files. Preserve actual output and input hashes locally.
+
+Capability-check independent agents before promising this mode's completed review.
+Give one reviewer the brief, article and evidence to check completeness, novelty and
+unsupported guarantees. Give a fresh implementation agent **only the exact copied
+payload and an existing test project**, with explicit authorization identifying the
+fixture path. Do not supply evaluator answers or the desired patch. Prefer a distinct
+domain or language; inspect both original and changed behavior with independent checks.
+For a mechanism with a material applicability constraint, also trial an unsuitable
+project: the agent should ask before implementing an invalid mechanism.
+
+Preserve original test expectations; do not change them to fit the agent's result.
+Check public compatibility and relevant state, not only the agent's own passing tests.
+Freeze the prompt, original fixture, resulting patch, observations and independently
+checked results. A prompt edit invalidates its trial evidence; keep example evidence
+only when its exact inputs and claimed scope remain unchanged. One passing fixture is
+evidence for that scenario, not a universal model or platform guarantee.
+
+If independent agents or required execution capabilities are unavailable, retain the
+draft and identify the missing check. Do not label it reviewed/ready or switch into
+legacy publishing. An aggregate score cannot compensate for a critical build defect.
+
+## Prepare the local preview
+
+Generate or obtain the user's adopted brand JSON (PRESS `tokens --format json` when
+available). Do not write brand constants from memory or require PRESS to be installed:
+an existing compatible adopted token file works. The helper consumes `colors`, `fonts`
+and `identity` from that file. Keep custom branding intact. If no brand resource is
+available, retain the Markdown draft and identify the missing preview input.
+
+```text
+devlog prepare-guide --article /absolute/guide.md --brand /absolute/brand.json --out /absolute/new-preview-directory
+```
+
+Add `--cover /absolute/reviewed-cover.png` after the cover is ready. A new attempt needs
+a new output directory; these helpers refuse overwrites. Review the standalone HTML,
+normal copy and manual fallback, mobile layout, code and images. The preview contains
+the complete guide without JavaScript. The handoff precedes the cover. Result hashes
+identify actual inputs and outputs; a successful render is not an editorial approval.
+
+The initial preview helper does not bundle companion files. Include required code
+inline; relative/local links and Markdown images are rejected before output creation.
+Use HTTP(S) source links, same-page anchors and the explicit `--cover` PNG input.
+Do not weaken those checks to ship a preview with missing diagrams or example archives.
+
+For Codex artwork read `codex-cover-art.md` in this directory. On Claude use the local
+cover path already supplied by devlog; native Codex tools are not required there.
+Retain completed text when cover generation fails and report the art blocker separately.
+
+Keep one local run record with source revisions, brief, chosen draft, current hashes,
+verification/review paths and pending work. Resume from matching artifacts; do not guess
+completion from a file's existence. Raw trial transcripts and prompts are local evidence,
+not a new public editorial ledger.
+
+For an explicit draft request, finish with the draft link, observed checks and specific
+limitations; do not publish. For an opted-in normal Generate run, return to
+[guide-publishing.md](guide-publishing.md) and complete its evidence gate, publication,
+push and live verification. There is no automatic coverage ledger. Existing-post
+rewrites and backfills remain separately scoped editorial work. Preserve old URLs;
+tombstones are not redirects, and legacy writers do not understand semantic coverage
+across merged articles.

package/references/cover-spec.md

@@ -0,0 +1,40 @@
+# Local raster composition schema
+
+Pass a JSON file to `compose-art-cover --spec <file> --out <new-directory>`.
+The output directory's parent must exist. Each attempt owns a new directory and
+writes its result marker last. The command does not overwrite or delete an existing
+attempt, generate artwork, call a service or publish.
+
+```json
+{
+  "schema": 1,
+  "source": "source-v1.png",
+  "brand": "brand.json",
+  "title": "Give your CLI an import-safe entrypoint",
+  "kicker": "ENGINEERING FIELD NOTES",
+  "stand": "Reuse the logic. Run only when invoked."
+}
+```
+
+`source`, `brand` and optional `fontPath` resolve relative to this JSON file. Use a
+local static raster, not SVG, animated media, a URL or executable HTML. `title` is
+required; `kicker` and `stand` are optional plain text. Text is escaped, measured and
+rejected if it cannot fit the owned layout. The source is contained at its original
+aspect ratio rather than cropped or stretched.
+
+`brand` is a generated/adopted JSON token export containing `colors` (`paper`, `ink`,
+`dim`, `accent`), `fonts` (`display_stack`, `serif_stack`, `mono_stack`) and `identity`
+(`stamp`, `name`). Generate it using PRESS `tokens --format json` when available, or
+use an existing compatible adopted export. Do not manually copy brand constants.
+Optional `fontPath` supplies an adopted local display font; other font stacks remain
+host-dependent. Inspect the result's font report rather than assuming a font loaded.
+
+Outputs are `composition.html`, `cover.png` (1600×900 true-color sRGB PNG),
+`thumbnail.png` (320×180) and `result.json`. Results include exact paths, hashes,
+dimensions, bytes and mechanical findings. Successful composition is not a semantic
+or visual review. A PNG without its matching completed result marker is incomplete.
+
+Keep this spec, sources, prompts and receipt in local run storage. Select the exact
+reviewed PNG for a reading preview. A separate existing-post backfill must preserve
+article metadata, use its authorized replacement path and verify the target site's
+actual cover/feed rendering before claiming compatibility.

package/references/guide-publishing.md

@@ -0,0 +1,245 @@
+# Publishing one concept guide
+
+`generationMode` is optional. Its absence and `"release"` retain the existing
+release workflow, config shape and `publish-entry` behavior. Opt in with
+`devlog set generationMode concept`; return with `devlog set generationMode release`.
+The example config explicitly retains release mode. This setting selects the
+agent workflow; it does not turn the legacy publisher into an evidence gate.
+
+In concept mode, inspect the scan's genuine, eligible new final releases, then
+choose at most one useful transferable outcome and one release anchor. Draft a
+complete guide for the reader's project, with its exact copyable handoff first.
+Do not manufacture a version/date to create a publishing slot. Verify that the
+selected project/version/date matches the actual release before recording it.
+If no candidate can meet the guide quality bar, publish zero guides and explain
+what evidence or implementation is missing. The helper does not independently
+verify Git tags and does not create a durable suppression ledger for other
+candidates. A later scan can still return them.
+
+Run structural lint, reproduce the guide, conduct an independent adaptation
+trial in a disposable original project, and independently check the result.
+Record observed commands/output and reviewer findings locally. For cover art,
+open the full image and thumbnail and record semantic and visual observations
+about the final PNG bytes. Fix blocking findings, regenerate the copy payload
+and rerun affected checks after edits. Prepare these concrete artifacts before
+publication; booleans asserting completion are insufficient.
+
+
+## Complete a normal concept Generate run
+
+First read [concept-guides.md](concept-guides.md) for the complete draft, handoff,
+execution and independent adaptation contract. On Codex also read
+[codex-cover-art.md](codex-cover-art.md): generate the reviewed cover with the
+available native image-generation tool and locally compose its typography. Do not
+substitute the legacy SVG workflow on Codex just to finish. On Claude, follow the
+existing local cover workflow and the true-color conversion note in that reference.
+A missing required agent, execution or art capability leaves a local draft with a
+specific blocker; it does not authorize bypassing the evidence gate. Do not adopt
+legacy Generate's optional-cover fallback for a requested concept cover.
+
+Use the CLI bundled relative to the loaded SKILL.md only after its read-only
+`--version` invocation succeeds with available runtime dependencies. The commands
+below show that form. If the script or dependencies are missing (including a Git
+plugin install without node_modules), or the installation is standalone, use the
+exact version fallback specified in SKILL.md in place of `node '<skill-root>/bin/devlog.js'`. Replace every placeholder
+with recorded paths or validated config values and quote each shell argument.
+
+```bash
+node '<skill-root>/bin/devlog.js' scan --json --summary
+node '<skill-root>/bin/devlog.js' scan --json --project '<selected-project>'
+node '<skill-root>/bin/devlog.js' lint-guide '<article-path>' --voice
+node '<skill-root>/bin/devlog.js' prepare-guide --article '<article-path>' --brand '<brand-json>' --out '<new-preview-directory>'
+```
+
+Honor an explicit project filter when scanning. Display the selected single
+outcome and genuine project/version/date anchor, including any decision to create
+zero guides. Follow Generate's voice, research, private-source and truthful
+Shipped/Changelog rules; other releases are evidence candidates, not additional
+articles to write. Prepare the guide, actually run its examples and the fresh
+agent adaptation, independently check the result, and inspect the rendered preview.
+Store the reports described below against the final article and exact copied
+payload. An article edit invalidates hash-bound reports; rerun affected work and
+explain the scope of evidence you retain.
+
+Generate, persist, compose and inspect cover art using codex-cover-art.md. Then
+prepare a new final preview (these helpers refuse existing output directories):
+
+```bash
+node '<skill-root>/bin/devlog.js' prepare-guide --article '<article-path>' --brand '<brand-json>' --cover '<reviewed-cover.png>' --out '<new-final-preview-directory>'
+```
+
+Open that preview and the full cover/thumbnail for the user. Confirm the copy
+payload still matches the tested bytes. Hash final artifacts and write the execution,
+adaptation and review reports plus `evidence.json`; these records stay in scratch,
+outside the content repository. They must describe performed work, not planned work.
+
+Clone the configured target branch into a new recorded scratch directory. The
+clone root and content root are distinct when `targetDir` is set:
+
+```bash
+mktemp -d
+# Record that absolute directory as <run-root> before continuing.
+git clone --depth=1 --branch '<branch>' 'https://github.com/<targetRepo>.git' '<run-root>/site'
+```
+
+Record the clone, selected anchor and current artifact/report hashes in local
+run-state. `<content-root>` means `<run-root>/site/<targetDir>` when configured,
+otherwise `<run-root>/site`. Keep all Git operations at `<run-root>/site`.
+Review the intended one-article content change, then stage it with the strict CLI:
+
+```bash
+node '<skill-root>/bin/devlog.js' publish-guide --clone '<content-root>' --article '<article-path>' --evidence '<evidence-json>' --cover '<reviewed-cover.png>'
+```
+
+The helper writes validated content only. Normal concept Generate must continue
+through commit, push and deployment verification; do not end the run after this
+command merely because it returned success. If it refuses an occupied or retired
+identity, preserve that identity and report the collision. Do not use publish-entry
+or manual copying to bypass it. Existing-post rewrite is a separate task.
+
+Before committing, inspect the content diff and returned `firstEntryForProject`.
+When true, follow SKILL.md Step 5b: register the project in the site's actual route
+registry, build and prove the new route exists, then run relevant site tests.
+For every concept guide, build/test the actual consumer as appropriate and inspect
+the top handoff, code rendering, cover loading, feed thumbnail and link destinations.
+The standalone preview alone does not prove site compatibility. Correct issues and
+rerun relevant checks before push. If correcting article or cover bytes, regenerate
+matching evidence and restart from a fresh clone rather than bypass immutability.
+
+Stage only the article, cover, manifest and any required registry change, then
+inspect the staged diff before committing. Use the configured Git identity and
+existing target-repository conventions. Inspect the target repository's instructions
+and branch/CI policy first. Where features must pass through `dev` and promotion,
+create a feature branch from the required base and use that PR path; the configured
+branch is the deployment destination, not permission to push past its policy.
+The direct-push example below applies only when the target policy permits it:
+
+```bash
+git -C '<run-root>/site' add -- '<article-relative-path>' '<cover-relative-path>' '<manifest-relative-path>'
+# If needed, separately add the specific reviewed project-registry file.
+git -C '<run-root>/site' diff --cached --stat
+git -C '<run-root>/site' diff --cached
+git -C '<run-root>/site' commit -m 'devlog: publish one concept guide'
+git -C '<run-root>/site' push --no-tags origin '<branch>'
+```
+
+Record the resulting commit and push outcome. If push fails, retain the clone,
+report the error and stop; do not retry automatically, force-push or discard work.
+After successful push, follow SKILL.md Step 6 for the configured site route. Poll
+its actual article URL roughly every 45 seconds for at most five minutes:
+
+```bash
+curl -s -o /dev/null -w '%{http_code}' -L '<actual-published-article-url>'
+```
+
+An HTTP 200 alone can be a fallback page: open/read the response to verify this
+article's title and top handoff, then verify the actual cover/thumbnail URLs load
+and inspect the deployed layout. Respect the site's route convention instead of
+assuming a new URL shape. If the route remains absent, inspect registry/build
+results and report it as not live. If `siteUrl` is unset, report pushed but
+unverified with the repository link, not published success. Retain local run-state
+and evidence until the outcome is recorded; never delete scratch before checking
+push/deployment. Finish with the live article link when verified, observed checks,
+and material limitations. No extra approval step is introduced for publication
+already authorized by a normal Generate request; explicit drafts remain drafts.
+
+## API and receipt
+
+`publishGuide({ cloneDir, articlePath, evidencePath, coverPath? })` is exported
+from `lib/publish_guide.mjs`. `cloneDir` is the existing content root inside the
+publishing clone (including configured `targetDir`). `articlePath` and optional
+`coverPath` are ordinary local paths relative to the invocation directory.
+The API validates all evidence before writing content, then delegates to the
+unchanged `publishEntry`. It never commits or pushes.
+
+Evidence JSON schema 1:
+
+```json
+{
+  "schema": 1,
+  "anchor": { "project": "example", "version": "v1.2.0", "date": "2026-09-09" },
+  "articleSha256": "<SHA-256 of exact article bytes>",
+  "agentPrompt": { "path": "agent-prompt.txt", "sha256": "<SHA-256>" },
+  "execution": { "path": "execution.json", "sha256": "<SHA-256>" },
+  "adaptation": { "path": "adaptation.json", "sha256": "<SHA-256>" },
+  "review": { "path": "review.json", "sha256": "<SHA-256>" },
+  "coverSha256": "<required only when supplying coverPath>"
+}
+```
+
+All SHA-256 values are lowercase 64-character hex strings. Referenced files
+resolve relative to the evidence file, not the current working directory.
+`agent-prompt.txt` must exactly equal the preview helper's copy payload: prompt,
+two newlines, `<reference-guide>`, the trimmed article with the handoff block
+removed, and closing `</reference-guide>`, with the helper's newline placement.
+Use the `prepare-guide` output; do not maintain a second hand-edited payload.
+
+Every execution/adaptation/review JSON report must contain these common fields:
+
+```json
+{
+  "status": "passed",
+  "summary": "Concrete observations and scope of this run.",
+  "articleSha256": "<same exact article SHA-256>",
+  "agentPromptSha256": "<same exact payload SHA-256>"
+}
+```
+
+The execution report additionally contains a nonempty `commands` array:
+
+```json
+{
+  "commands": [
+    {
+      "command": "node --test",
+      "exitCode": 0,
+      "output": { "path": "logs/tests.txt", "sha256": "<SHA-256>" }
+    }
+  ]
+}
+```
+
+Output files resolve relative to the execution report. They must contain actual
+observations and match their hashes. Include each required successful check;
+retain failed attempts separately and describe corrections in the summary.
+Do not invent a successful command or replace actual output with a claim.
+
+The adaptation report additionally identifies the starting and resulting
+fixture (paths, immutable revisions, or durable artifact identifiers), and
+records a nonempty list of independently observed checks:
+
+```json
+{
+  "fixture": { "original": "fixtures/before", "result": "fixtures/after" },
+  "independentChecks": [
+    { "check": "Existing public imports", "observation": "No side effects under invalid CLI arguments", "passed": true }
+  ]
+}
+```
+
+The review report additionally contains `reviewer` (nonempty identifier) and
+`blockingFindings: []`. Explain the substantive review in its `summary`; an
+empty findings array alone is not a review. When a cover is supplied, both the
+evidence and review must contain its `coverSha256`, and the review must also
+contain nonempty `coverReview` observations. The decoded cover must be a
+single-frame true-color 1600×900 PNG. Changes to art invalidate its visual review.
+
+These are consistency checks on local records. Hashes do not establish that a
+command actually ran, that a reviewer was independent, or that observations are
+correct. The agent must perform and inspect the work before writing the records.
+Do not describe `evidenceValidated: true` as independent execution verification.
+
+## Existing posts and failure behavior
+
+This command refuses an occupied article, cover, manifest identity, or tombstone.
+Even a manifest entry whose article is absent is occupied; use a deliberate
+editorial repair workflow. Consolidating or rewriting published posts is a
+separate explicitly scoped task that preserves URLs and existing identities.
+There is no force option, migration, or change to old posts in this command.
+
+Missing files, stale hashes, lint failures, failed/unobserved checks, anchor
+mismatches and invalid covers fail before content mutation. After validation,
+the existing publisher retains its existing article-then-manifest write behavior;
+a disk failure is not an atomic rollback. Publish serially: neither helper
+provides a multiprocess lock. Keep local evidence private unless deliberately
+reviewed for inclusion in the public repository.