docs: repository - Add agent and contributor guidance #2

Documentation Update Summary

Complete and validate repository-specific agent and contributor guidance for lightspeedwp/ThisOneTimeOnAcidCom.

PR #17 merged guidance and package-manager cleanup into develop. Subsequent changes mean its documentation and validation cannot automatically certify today’s repository.

Assessment baseline: 19 October 2026, develop 4ecdb26, main cb53d2c.

Linked Stories/Tasks/PRs/Epic

• Merged contribution: docs: reconcile repository guidance and fix Netlify routing configuration.
• Production routing acceptance remains with bug: netlify - Fix unreadable redirects output and validate routing #3.
• Existing guidance-reconciliation child: docs: repository - Reconcile guidance with current tooling #408. Its creation does not establish scope approval, implementation or completion.
• Coordinate with existing structure/naming, Lefthook and Spec Kit routing work rather than duplicating their deliverables.
• No related epic identified.

Milestones & Timeline

No new deadline, estimate, milestone or release commitment.

What documentation is needed?

Reconcile the agent guidance and contributor guidance with current executable configuration:

• Node 24 configuration versus the unverified production runtime.
• Current npm/pnpm configuration and conflicting setup instructions.
• Available Jest, Bats, Playwright and branch-validation commands.
• Updated journal-tooling paths versus remaining reader-loader mismatches.
• Develop/main redirect differences and unverified deployment settings.
• Existing branch policy, inherited templates and conflicting reading orders.
• Actual Spec Kit integration versus advertised Claude commands.

Why is this documentation important?

Contributors need instructions matching current behaviour, without treating historical validation, proposed policy or a develop merge as production certification.

Acceptance Criteria

• Runtime, package-manager and command guidance matches current configuration.
• Editorial locations, loaders and integration limitations are distinguished.
• Deployment uncertainty and competing guidance remain explicit.
• Links and anchors pass at the final documentation revision.
• Examples and changelog applicability are recorded.
• Scope, governance exceptions and review evidence are reconciled.
• No unrelated runtime, configuration or publication changes are introduced.

Additional Context

PR #17’s final head was 971a62f, merged as a10c10d. Its four-file diff contained guidance changes, package metadata changes and workspace-file deletion—not redirect restoration, manuscript migration, accordion changes or hook removal.

Earlier independent installation/build/link checks apply to that revision only. Current develop includes later tooling and configuration changes.

Definition of Ready

• Repository, contribution history and current contradictions identified.
• Bounded reconciliation scope and review coverage approved.
• Policy questions identified without silently choosing answers.

Definition of Done

• Applicable acceptance criteria evidenced at the final revision.
• PR docs: reconcile repository guidance and fix Netlify routing configuration #17 merge recorded.
• Follow-up guidance reviewed and merged.
• Validation failures, skips and accepted limitations recorded honestly.
• Release applicability resolved; routing acceptance remains with bug: netlify - Fix unreadable redirects output and validate routing #3.
• Parent completion assessed against its whole outcome.

Next action: approve and deliver the bounded documentation child.

Unanswered clarification questions

These questions clarify documentation coordination; they do not authorise implementation or production changes.

1. Which reconciliation outcomes should docs: repository - Reconcile guidance with current tooling #408 deliver, and which remain with other existing workstreams?
2. Who approves the bounded reconciliation scope and reviews the resulting guidance?
3. Which runtime, package-manager and reading-order decisions require explicit approval rather than editorial correction?
4. What final-revision evidence should establish that documented commands, links and limitations are accurate?
5. What changelog and release-applicability decisions are required before assessing this parent’s whole outcome?