# Standalone output contract

This contract follows CodeWiki 0.6.0's persisted shapes. The plugin's producer is
`codewiki-plugin/0.6.0`.
The plugin does not implement the native resumable queue, sparse MCP submission,
automatic evidence relocation, or source-fingerprint algorithm.

## Layout

- `codewiki/quickstart.md`: entrypoint and links to useful pages.
- `codewiki/<domain>/<page>.md`: factual pages.
- `codewiki/INSTRUCTIONS.md`: repository-specific wiki authoring scope.
- `codewiki/index.md` and populated subdirectory indexes: generated navigation.
- `codewiki/.claims/<domain>/<page>.json`: one full Claims sidecar per factual page.
- `codewiki/.page-manifest.json`: durable page coverage.
- `codewiki/.last-update.json`: run outcome.
- `codewiki/.codewiki-run.json`: plugin-only unfinished plan and source snapshot;
  retain on interruption and remove on successful completion.

Never create or overwrite the engine's `.run.json`. Do not mix concurrent
standalone and engine generation.

## Finalization order

1. Reconcile prose, diagrams, and the complete Claim set against inspected source.
2. Validate frontmatter with an available YAML parser; follow the OKF skill.
   If no parser is available, report structural review rather than claiming
   automated YAML validation. Preserve unknown producer fields.
3. Validate Mermaid with an available parser or rendered preview. If unavailable,
   apply the syntax guidance and report that parsing was not checked. Fix actual
   failures; if a failure cannot be fixed, use a text fence and an explanatory
   `<!-- codewiki: mermaid parse failed ... -->` comment, and report degradation.
   Sanitize comment text so it contains no `--` delimiter.
4. Regenerate indexes from current page metadata. Verify internal page links and
   heading anchors, including quickstart. Check repository citations via the helper.
5. Project each page's final Claims into `sources`: canonical whole-file resources,
   deduplicated, sorted with JavaScript `localeCompare`, IDs
   `codewiki-source-<sha256(resource)[0:24]>`. Preserve independently authored
   source mappings; only replace the `codewiki-source-` projection, and do not
   duplicate resources already supplied by a retained mapping.
6. Stamp changed pages' `generated` and inspected pages' `verified` with the real
   producer and run timestamp. Drop legacy `timestamp` when replacing provenance.
   Changed Markdown ends with exactly one LF. Preserve untouched page bytes.
7. After all Markdown changes, hash the exact saved bytes with `hash-page`.
   Put that hash in both sidecar `pageVersion` and manifest `pageVersion`.
   Write JSON as `JSON.stringify(value, null, 2) + "\n"` using temporary siblings
   and rename where possible. Keep unfinished run state until every write succeeds.
8. Run the helper's `verify` command for factual pages. This checks evidence
   versions, page binding, and manifest agreement; it does not validate YAML,
   semantic truth, links, or Mermaid. Complete those checks separately.
9. Compare start/end source snapshots. Only after stable-source checks and durable
   page verification may the run be marked complete.

## Index renderer

Exclude dot entries, `index.md`, `log.md`, `INSTRUCTIONS.md`, and non-Markdown
files from factual page lists. List visible child directories separately.
Use frontmatter title (fallback: basename), with description when present.
Encode filenames using `encodeURIComponent`; escape backslashes and square
brackets in labels. Sort each group by encoded href with `localeCompare`.

A root index begins with:

```yaml
---
okf_version: "0.2"
---
```

Then emit `# Files` and `# Directories` sections, separated by a blank line.
Omit empty sections; if both are empty emit `# Files`. Subdirectory indexes
have the same sections without frontmatter. File items are
`- [Title](page.md) - Description`; omit the description suffix when empty.
Directory items are `- [domain](domain/)`. Localize headings for the wiki language.
End indexes in exactly one LF and write only when bytes differ.

## Manifest

```json
{
  "schemaVersion": 1,
  "pages": {
    "/codewiki/architecture/overview.md": {
      "pageVersion": "sha256:<exact-final-page-hash>",
      "completedBy": "codewiki-plugin/0.6.0",
      "completedRunId": "<real-run-UUID>",
      "gitHead": "<commit-actually-covered>"
    }
  }
}
```

Sort page keys lexically. Exclude navigation indexes, instructions, and logs.
Remove entries for deleted pages and their sidecars. Only advance coverage for
pages actually verified; untouched pages keep their prior entries.
Omit `gitHead` in an unborn repository. Omit `sourceFingerprint` on entries
completed by this plugin: it does not compute the engine's fingerprint.
Do not copy an old fingerprint onto newly verified content or substitute a Git
SHA or the plugin snapshot digest. The engine accepts absent fingerprints and
must conservatively recheck coverage on a later engine run.

## Run metadata

Use actual values, never example dates or a guessed model identity:

```json
{
  "updatedAt": "<ISO-8601-time>",
  "command": "init",
  "gitHead": "<covered-commit>",
  "model": "<actual-host-model-if-known>",
  "status": "complete",
  "language": "en"
}
```

Use `command: "update"` for maintenance and `status: "interrupted"` when
validation or source drift prevents completion. Omit unavailable model/HEAD
values rather than inventing them. DeepSWE's existing cache requires a real model
and Git commit; missing values do not qualify as a compatible cache.
Do not advance the prior source checkpoint on an interrupted run.

The existing DeepSWE adapter generates wikis with CodeWiki and does not load this
plugin. Compatible output shape is not evidence that the plugin has been benchmarked.