docs: repository - Reconcile guidance with current tooling #408

Documentation Update Summary

Reconcile current root guidance with executable runtime, package, testing, content-source, deployment and contribution configuration. Documentation only.

Linked Stories/Tasks/PRs/Epic

Child of #2. Coordinate with existing structure, Lefthook and Spec Kit routing work. Production acceptance remains outside this child.

Milestones & Timeline

Backlog; estimate unset. No release commitment.

What documentation is needed?

Correct current contradictions identified in the parent’s acceptance criteria, including actual Spec Kit integration and unresolved Claude command availability.

Why is this documentation important?

Prevent contributors and agents following stale or unsupported instructions.

Acceptance Criteria

• Clear, accurate, discoverable guidance.
• Relevant examples and changelog applicability recorded.
• Compliant branch, PR description, template and type treatment.
• Claims cite current evidence; historical results remain revision-labelled.
• Loader/deployment/policy limitations stay explicit.
• Changed-document links and anchors verified.
• No unrelated implementation or protected-file changes.

Additional Context — Claude/Spec Kit prompt

Prepare a documentation-only correction proposal for
lightspeedwp/ThisOneTimeOnAcidCom and this child issue.

Read current repository instructions and executable configuration.
Record the revision; preserve unrelated work.

Inspect Spec Kit version, integration, commands, feature state,
templates, overrides and hooks by reading files only.
Do not run state-persisting prerequisite helpers.

Earlier evidence records Spec Kit 1.0.13 with Gemini integration,
not verified native Claude commands. Do not invent slash commands,
install integrations or infer a feature from the branch.

If Claude commands or feature selection cannot be verified, report
the missing prerequisites and return ordinary read-only findings.
Do not execute Spec Kit commands.

Return:
1. Evidence-backed contradictions and overlapping existing work.
2. Exact proposed root-guidance patches.
3. The smallest conditional Spec Kit planning sequence.
4. Validation plan, unresolved decisions and permitted next steps.

Stop before edits, artefact creation, branches, installs, commands,
commits, PRs, issue updates, merge or deployment.
Do not silently choose package-manager or reading-order policy.
Use UK English.

Definition of Ready

• Need, references and criteria confirmed.
• Policy questions documented or resolved.
• Estimate and milestone non-applicability recorded.

Definition of Done

• Standards, clarity, accessibility and applicable examples satisfied.
• Changelog, branch and PR-template treatment confirmed.
• Final evidence recorded; review and authorised merge completed.
• Branch cleanup and child completion reconciled.
• Parent not automatically closed.

Branch instructions

Proposed branch: docs/repository-guidance-reconciliation, from current develop. Recheck policy before implementation. Template taxonomy conflicts remain unresolved; no automatic governance edits or parent-closing references.

The Backlog/triage-label conflict and changelog applicability remain explicitly flagged.

Unanswered clarification questions

These questions clarify the existing documentation-only scope without choosing repository policy.

1. Which root guidance files and sections are included in the bounded correction?
2. Which runtime, package-manager and reading-order policies are approved, and which remain proposals?
3. What evidence should distinguish verified Spec Kit integration and commands from unsupported Claude workflow claims?
4. Who reviews the proposed guidance patches and accepts their final-revision validation evidence?
5. What changelog treatment and PR-template requirements apply, and which recorded conflicts remain unresolved?