[CI/CD] Implement Documentation Completeness Gates

[ucguy4u]

Problem

Manual wiki documentation drifts as new feature updates are merged.

Scope

• Write a PR verification script (bash/python) to check if app/lib/features/ changes have matching updates in docs/wiki.
• Integrate script as a check step in GitHub Actions.

Acceptance Criteria

• PR checks fail if features change but wiki docs are not updated, unless a label or commit message bypass is used.

Estimate

4 hours

[ucguy4u]

Required Before Implementation: Use Cases + Automation Flow

Before coding this ticket, add a deterministic implementation note or child task covering:

• Primary user journey: actor, preconditions, trigger, happy path, success state.
• Alternate/failure paths: offline, missing model, permission denied, runtime/tool failure, cancel/retry, background/foreground.
• Automation flow: Given/When/Then steps, fixtures, mocks/stubs, UI assertions, state/database assertions, notification/tool-trace/memory assertions where relevant.
• Hardening checks: privacy redaction, accessibility, timeout/performance bounds, cleanup/reset.
• Delegation prompt: Ask a QA/test agent to write the automation flow before implementation begins.

Tracker: #323

[ucguy4u]

Critical Agent Gate

Problem: User-facing feature changes can merge without a matching docs/wiki update, so the public capability guide drifts from the shipped app.

User / actor: Maintainers, reviewers, and end users relying on the wiki as the current source of truth.

Framework or application layer: Framework / DevEx automation.

Owning agent: agent/ci-cd

Reviewing agents: agent/docs, agent/qa-testing

Impacted modules/files:

• scripts/check-docs-completeness.sh
• .github/workflows/pr-checks.yml
• optionally .github/workflows/ci.yml if the check should run there as well
• docs/wiki/**
• .github/PULL_REQUEST_TEMPLATE.md if bypass wording needs alignment

Open questions: None for the first pass. Use a lightweight bypass via PR label and commit-message marker so urgent infrastructure PRs are not blocked.

Decision: Ready

Cross-Agent Contract

Provider agent: agent/ci-cd
Consumer agent: agent/docs, reviewers, and PR authors
Interface/API: CI script exit status plus console output in pull-request checks
Input shape: Base/head refs and optional bypass metadata from GitHub Actions
Output shape: Exit 0 when docs coverage is satisfied or explicitly bypassed; non-zero with actionable guidance when a wiki update is required
State changes: No runtime/app state changes
Errors: Missing git history or malformed refs should fail with a clear message
Permissions: Read-only repository diff inspection in CI
Privacy/redaction: No secrets or private user data involved
Persistence: None
Versioning/migration: Backward compatible; only affects PR verification
Tests required: Dry-runs against representative changed-file sets and workflow invocation on pull requests

Deterministic Use Cases

UC-001: Feature PR updates wiki

Actor: PR author
Preconditions: PR changes files under app/lib/features/
Trigger: PR checks run
Happy path: docs/wiki/** is also changed, so the script passes
Failure path: no wiki files changed and no bypass marker/label is present, so the script fails with remediation instructions

UC-002: Non-user-visible PR skips wiki update

Actor: PR author
Preconditions: PR changes infra or internal files only, or intentionally carries a docs bypass marker
Trigger: PR checks run
Happy path: no relevant feature files changed, or bypass is explicitly declared, so the script passes

Automation Flow

AUTO-001: Enforce wiki update on PR

Given: a pull request diff between base and head
When: changed files include app/lib/features/**, app/lib/core/routing/**, or README.md
Then: the check requires at least one docs/wiki/** file change unless a docs bypass marker/label is set
Fixtures: git diff between base/head refs in CI
Assertions: failing message explains exactly which trigger files require a wiki update and how to bypass intentionally