Maintenance Documentation

Read shared/orchestrator-contract.md. Own the run directory, global manifest, joins, contradiction handling, index, freshness, and final status. Leaves own only their isolated outputs.

Inputs

Require repo_root, scope, audience, visibility, requested modes. Accept module inventory, tech audit, use-case/API/data/command artifacts, project/database/collection identity, output root, limits, incremental baseline, render preference, review_required (default true), clarification answers, review comments.

Read pipeline-contract.md, evidence-contract.md, readability-and-security.md, and hi-document-lifecycle/references/lifecycle-contract.md.

Stage Dependencies

Order	Stage	Skill	Prerequisites	Skippable?
1	recon/audit	hi-repo-recon + hi-tech-build-audit	inputs	Yes, if validated inputs provided
2	module summary	hi-module-summary-report	recon + audit	No
3	use cases	hi-usecase-discovery	module roots	No
4	API/data/command	hi-api-contract-discovery + hi-data-model-discovery + hi-command-spec-discovery	requested modes only	Yes, if not requested
5	behavior	hi-behavior-modeling	use-case/entry-point anchor	Yes, if no anchor
6	cross-validation	hi-cross-artifact-validation	all leaf manifests	Optional
7	synthesis	internal	all local manifests	No
8	refinement	hi-document-refinement	r001	No
9	review	hi-document-review-resolution	r002 + comments	If no comments + not required

Workflow

1. Create unique maintenance-docs/<run-id>/ with normalized inputs, checkpoint, and empty manifest.
2. Run hi-repo-recon + hi-tech-build-audit only when validated inputs absent. Allow concurrency for disjoint stage roots.
3. Join required manifests, run hi-module-summary-report for system/module views.
4. Run hi-usecase-discovery across independent module roots.
5. Run hi-api-contract-discovery, hi-data-model-discovery, hi-command-spec-discovery only for requested, supported modes.
6. Run hi-behavior-modeling only after a use-case/entry-point anchor exists.
7. Optionally run hi-cross-artifact-validation for cross-domain consistency checks.
8. Validate and join local manifests; copy every leaf artifact into its canonical domain subtree (system/, behavior/, api/, data/, command/). Rewrite links to stay inside run root; reconcile stable IDs; retain contradictions; classify gaps; compute freshness. Persist as immutable r001.
9. Run hi-document-refinement analyze against r001. If blocking questions unanswered → persist, stop in waiting_for_input. Otherwise run apply with validated answers → immutable r002.
10. If comments anchored to r002 exist → invoke hi-document-review-resolution → r003 + disposition ledger. If absent and review_required=true → wait. If absent and review_required=false → skip.
11. Build final index from index-template.md, materialize current/ from latest validated revision, validate pack, persist status with resume state.

Resume: Revalidate input, artifact, and parent hashes before skipping completed work. Retry counts never reset.

Completion

Require all requested artifacts navigable, governance/evidence-index.json valid, governance/documentation-gaps.md, governance/freshness-report.md, manifest valid, legal lifecycle transitions, revision lineage, artifact hashes, clarification/review coverage. Block on redaction failure. Missing evidence, stale inputs, skipped review, omitted optional modes must remain visible.