# Generated Wiki Stale Purge Design

## Goal

Add an explicit bulk purge path for generated NodeBB wiki pages that have become
stale after generator output changes, such as topdata visibility rules hiding
previously generated pages.

## Context

The topdata wiki deployer already owns generated page state through
`.cache/wiki/.wiki_deploy_manifest.json`. It currently recognizes stale
generated pages that remain in the deploy manifest but no longer exist in the
current generated wiki output. Existing stale policies can either report those
pages or archive them by rewriting their managed content.

That is not sufficient when the stale generated wiki topics should be removed
from NodeBB entirely. The Westgate Wiki plugin already treats a normal wiki topic
delete as an irreversible purge, so the deployer should use NodeBB's explicit
topic purge API when the operator asks for destructive generated-page cleanup.

## Scope

### In Scope

- Add `purge` as an explicit stale policy for topdata wiki deployment.
- Plan purge candidates only from generated page entries already tracked in the
  wiki deploy manifest.
- Purge the exact tracked NodeBB topic for each stale generated page.
- Report purge counts in dry-run and live deploy output.
- Remove successfully purged page entries from the deploy manifest so later
  deploys do not repeatedly target removed topics.
- Allow release automation to opt into purge through the existing stale-policy
  environment variable path.
- Update toolkit and module documentation for the destructive cleanup mode.

### Out Of Scope

- Purging manually-authored NodeBB wiki pages.
- Discovering purge candidates by namespace browsing, title, slug, or wiki
  search.
- Adding a soft-delete or restore workflow for stale generated wiki pages.
- Changing the Westgate Wiki plugin delete behavior.
- Adding a separate stale cleanup command outside `deploy-wiki`.

## Operator Interface

The existing `deploy-wiki` stale-policy surface gains a third explicit policy:

```bash
./deploy-wiki.sh --dry-run --stale-policy purge
./deploy-wiki.sh --stale-policy purge
```

Release automation may use the same policy through:

```bash
SOW_MODULE_WIKI_DEPLOY_STALE_POLICY=purge
```

`purge` remains opt-in. Existing `report` and `archive` behavior remain
unchanged.

## Purge Eligibility

A page may be purged only when all of these are true:

1. The page exists in `.cache/wiki/.wiki_deploy_manifest.json`.
2. The page is absent from the current generated wiki page set in the deploy
   scope.
3. The deploy manifest entry has the tracked NodeBB topic id required to call
   the topic purge API.

The deployer must not search NodeBB for candidate pages when purging stale
generated output. It must not purge pages that are currently generated. It must
not purge pages that only exist as manually-authored NodeBB wiki content.

If a stale manifest entry has no topic id, purge planning fails clearly instead
of guessing a remote target.

## Deploy Flow

Stale planning stays inside the existing `deploy-wiki` deploy plan:

- `report` increments the stale count only.
- `archive` produces the existing archive post-update action.
- `purge` produces a destructive topic-purge action for the manifest entry's
  tracked topic id.

Dry runs calculate the same stale and purge counts as live runs but do not call
NodeBB and do not mutate the deploy manifest.

Live purge execution calls NodeBB's topic purge API for each planned stale
generated page. NodeBB auth, permission, missing-topic, or transport failures
abort the deploy with the failing generated page id and remote topic context.

## Manifest State

Archive retains stale entries in the manifest because the archived post remains
managed remotely.

Purge removes each successfully purged page entry from the next deploy manifest.
This records that the generated page no longer has a managed remote NodeBB topic
and prevents later deploys from attempting to purge an already removed topic.

If a purge deployment fails partway through, only state written after the
existing deploy execution succeeds should reach the manifest. A later rerun may
retry the stale manifest entries still present, matching the deployer's current
all-or-error manifest persistence behavior.

## Reporting And Validation

Toolkit deploy output gains a `purged` count alongside the existing `stale` and
`archived` counts. Dry-run summaries must make the destructive plan visible
before a live purge run.

`purge` must be accepted wherever stale policy is validated:

- project config stale-page settings
- `deploy-wiki --stale-policy`
- module release wrapper validation for
  `SOW_MODULE_WIKI_DEPLOY_STALE_POLICY`

Unsupported stale policy values must keep failing early with clear error text.

## Testing

Toolkit tests should cover:

- stale policy validation accepts `purge`
- unsupported stale policy values still fail
- dry-run purge reports stale and purged counts without calling NodeBB or
  changing the manifest
- live purge calls the NodeBB topic purge endpoint for a stale tracked generated
  topic
- live purge removes the manifest entry after success
- purge refuses a stale manifest entry without a tracked topic id
- current generated pages are never purge candidates
- archive/report behavior remains unchanged

Module wrapper/docs coverage should verify:

- release stale-policy validation accepts `purge`
- docs describe purge as destructive, generated-manifest-scoped cleanup

## Compatibility

Default behavior remains `report`. Existing archive cleanup remains available and
unchanged. The destructive purge path activates only when the operator selects
`purge`.

The purge boundary is intentionally stricter than normal page adoption logic:
generated manifest state authorizes the target; NodeBB discovery never does.