Run a documentation-only goal

A documentation-only goal is the simplest kind of bounded goal: it adds content and tooling without modifying production code.

When to use

• You are writing or extending the docs portal.
• You are adding a new docs section.
• You are fixing a typo or broken link.
• You are updating diagrams.

Steps

1. Create a new branch: git checkout -b feature/docs-<bounded-scope>.
2. Copy goals/ASF50_DOCS_PORTAL_001/GOAL_RECORD.yaml as a template.
3. Update the contract: goal_id, goal_type: DOCUMENTATION_PORTAL, phase_id, current_state: READY_FOR_PLAN, required_role: PLANNER, tasks, allowed_paths, forbidden_paths, acceptance_gates, evidence_requirements, owner_gates.
4. Write the CONTEXT.yaml and PROMPT.md.
5. Commit the goal contract (no other changes in this commit).
6. Run goal-run.ps1 -GoalId <NEW_GOAL_ID> -RuntimeRoot … -DryRun -StopAtOwnerGate.
7. Inspect the JSON. The orchestrator should report current_state: READY_FOR_PLAN, next_state: READY_FOR_PLAN, next_role: PLANNER, next_task_ids: [<T01-PLAN>].
8. Edit the docs files in docs-site/.
9. Run npm install (or skip if node_modules is already present).
10. Run npm run build to validate.
11. Run npm run start to spot-check locally (optional).
12. Run a broken-link checker (e.g., linkinator).
13. Run the docs security audit (scripts/check-docs-build.ps1).
14. Commit the docs changes in the same branch.
15. Push the branch.
16. Open the PR.
17. STOP at the GitHub review boundary.

What the orchestrator emits

After the bounded commit, goal-run.ps1 re-runs without -DryRun. The orchestrator may emit:

• MERGE_APPROVAL at the PR head → owner submits an approving review.
• PRODUCTION_PROMOTION after the merge → owner signs a production ticket.

What this playbook is NOT

• It is not for production code changes.
• It is not for governance changes.
• It is not for repository-wide refactors.