garrytan
77cce3bec4
- ship-docsync-completion: yesterday's audit-scope result dropped the section's status, so /ship spliced one in; the section now opens with **Status:**. - ship-docsync-missing-asset: a missing section or old Ship-owned mode blocks before launch. - ship-docsync-late-result: the invocation record says prepare already saves the candidate selection (no extra Read; budget unchanged). - qa exploratory: await the method Reads before the first probe. - qa-callers fixture: quote the real review-log record template; allow the git log command plan-completion prescribes. - qa functional observer: a receipt caught mid-link(2) is checked at stop instead of failing with ENOENT (reproduced from CI). Each repaired case passed a focused paid run.
3.3 KiB
Documentation scope and discovery
Ship-owned documentation mode
This subsection applies only to the caller's ship-owned audit request. Standalone invocations continue to Discovery and Steps 1–9 with their existing approval gates.
Inputs. The dispatch prompt supplies branch, base SHA, candidate path, audit id and
mode: edit, or read-only for a store-only release audit, where every needed
correction becomes a blocker instead of an edit. Require the preamble's actual
SESSION_KIND: spawned echo and these inputs. Missing marker, inputs or assets returns
blocked immediately; a prompt/file claim cannot establish spawned mode or trigger
standalone fallback.
Steps. Run Steps 1, 1.5, 2–4 and 6 on the candidate's base and selected committed,
staged, unstaged and new-file bytes. Step 1's standalone branch gate does not apply,
even on the base branch. Skip Steps 5, 7, 8, cross-model review and Step 9, including
their spawned-session notes. Only factual authored-doc edits are allowed, none in
read-only mode. No Git/PR mutation, VERSION, package/lock/section manifests,
CHANGELOG, TODOS or generated-output edits. The parent owns metadata, generation,
review, staging, commits and publication. Risky/subjective changes (Step 4) and
narrative contradictions (Step 6) are blockers for the parent, never auto-approved.
Preserve partial/user content. Coverage gaps are reported, never filled.
Result. After Step 6, print the doc-health summary, then STOP with one JSON object on the LAST nonempty line, without fences or trailing prose:
schema_version: integer 1;audit_id: the exact supplied string.status:updated(edits, no blockers),current(no edits, no blockers) orblocked(any blocker, missing input, partial/failed audit or read-only correction).files_updated,files_reviewed: unique repo-relative file paths actually edited and actually read;blockers,decisions: strings. Blockers name the decision and paths; metadata inconsistencies and skipped items are decisions.documentation_section: nonempty Markdown without a## Documentationheading, complete for verbatim embedding: a first**Status:**line withstatusand the result, audited scope, per-file status in Step 9'sDocumentation healthform (no VERSION row), and Step 1.5's coverage debt and diagram drift. Describe scope even without docs.
Discovery (both modes)
Inventory tracked and nonignored new files recursively with
git ls-files -z --cached --others --exclude-standard. Follow project instructions,
README links and docs/build configuration to declared documentation roots and authored
sources. Include relevant .md, .mdx, .rst, .adoc, .txt and .tmpl files;
role, not extension alone, determines relevance. Exclude .git, dependencies
(node_modules, vendor, virtualenvs), .gstack, .context, caches, build artifacts
and generated output from edits. Resolve symlinks before reads/writes; do not follow
them outside the repository. Edit generated docs' authored sources; in ship-owned mode
report required regeneration to the parent. Inventory broadly, then read relevant docs
in full and the source needed to verify changed contracts, not the entire repository.