docs: keep internal implementation plans out of the published site

[codeforester]

Goal

Keep internal agent implementation plans out of the public documentation tree and make documentation validation catch accidental unnaved pages.

Background

Current main commits these files under docs/:

• docs/superpowers/plans/2026-08-19-json-retention-precedence.md
• docs/superpowers/specs/2026-08-19-json-retention-design.md

The first addresses “agentic workers,” names required private workflow skills, and contains unchecked implementation steps. Neither file is in mkdocs.yml navigation. mkdocs build --strict reports both as pages that exist but are not included in nav, yet succeeds; because they live under docs/, they are still copied into/publishable from the generated site.

Reproduction and evidence

Framework reference: 263d893 on main.

$ python -m mkdocs build --strict
INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - superpowers/plans/2026-08-19-json-retention-precedence.md
  - superpowers/specs/2026-08-19-json-retention-design.md

The build exits successfully, and scripts/validate_docs.py does not flag the files.

Scope

• Move or remove internal implementation artifacts from the published documentation source, or explicitly exclude an approved internal path.
• Add a validation rule that fails on accidental unnaved/internal pages while allowing deliberate assets.
• Keep user-facing design rationale in an appropriately edited public page if it has lasting consumer value.
• Ensure source distributions and the deployed site expose only intended documentation.

Acceptance criteria

• The public site contains no agent workflow instructions or unchecked internal implementation plan.
• Documentation validation fails when an unexpected Markdown page is added outside the declared navigation/exclusion policy.
• mkdocs build --strict, scripts/validate_docs.py, package validation, and link checks pass cleanly.

Project fields

• Status: Backlog
• Priority: P2
• Area: Docs
• Initiative: Adoption Polish
• Size: S

Ownership

• Assignee: @codeforester