sow-tools/WIKI_DEPLOYMENT_CONTRACT.md

Wiki Deployment Contract

Scope

This contract governs the next focused phase after wrappers, config refactor, logging, and topdata hardening:

• toolkit/ owns build-wiki and deploy-wiki
• module/ owns the consuming release workflow and operational configuration

This work is intentionally sequenced after topdata hardening because the wiki pipeline consumes native topdata outputs and metadata.

Current State

As of 2026-05-13:

• build-wiki exists
• deploy-wiki exists
• deployment targets NodeBB core /api/v3
• local deploy manifests and NodeBB topic mapping exist
• release automation in module/scripts/release-all.sh already runs wiki build and deploy steps after release publication
• toolkit tests already cover dry-run behavior, topic creation, and manifest writes

This means wiki deployment is no longer a greenfield feature. The next phase is hardening, integration clarity, and operator experience.

Deferred Until Current Priority Work Completes

Do not prioritize the following until wrappers/config/logging/topdata work is in better shape:

• new NodeBB release-announcement posting flows
• broad wiki feature expansion
• unrelated formatting changes to generated page content

Immediate Goals For The Wiki Phase

1. align wiki build/deploy logs with the structured logging contract
2. tighten config ownership for wiki defaults and category mappings
3. reduce residual hardcoded behavior that belongs in normalized config
4. improve release-flow clarity around dry-run, drift, create, and force modes
5. verify that topdata hardening does not silently change generated page identity

Current Findings

• deploy-wiki already reads managed namespaces from effective config when the caller does not specify them explicitly
• deploy manifest naming and edit-summary defaults still come from toolkit defaults in internal/project/effective.go
• release orchestration already guards publication order correctly, but the operator-facing logs are still more shell-oriented than the newer structured build-haks presentation
• wiki deployment should be treated as a first-class operational command family, not just a release-script tail step

Immediate Plan

Phase 1: Logging and UX parity

• add concise summaries for build-wiki and deploy-wiki
• surface counts for:
  • pages collected
  • creates
  • updates
  • skips
  • drifted pages
• keep raw debug output available when diagnosis is needed

Phase 2: Config clarity

• audit which wiki defaults should remain toolkit defaults versus explicit repo config
• keep namespace/category ownership visible in effective config
• ensure deploy-manifest path and edit summary remain discoverable and easy to override

Phase 3: Release-flow hardening

• verify module/scripts/release-all.sh remains the authoritative release entry point
• keep dry-run before live deploy
• ensure failure and drift messages are crisp and actionable
• make sure cache restore/save behavior is clearly documented and tested

Phase 4: Regression verification after topdata hardening

• confirm topdata de-hardcoding does not break page IDs or manifest mapping
• confirm generated-page identity remains stable across unchanged inputs

Testing Requirements

Add or expand tests for:

• app-layer output for build-wiki and deploy-wiki
• release-flow sequencing assumptions where wiki deploy must happen only after release assets are published
• stable page identity and manifest mapping across repeated runs
• config-driven namespace selection and manifest path overrides

Acceptance Criteria

• wiki build/deploy logs match the newer structured CLI standard
• wiki defaults and overrides are clearly represented in effective config
• release orchestration remains deterministic and easy to reason about
• topdata hardening does not regress page identity or deploy manifest behavior