Skip to content

build: repo-governance - Tailor repository root configuration #258

Open

Description

@ashleyshaw

Approved bounded SCSS pilot — 28 October 2026

Approval and relationship to existing scope

Ash approved the incremental SCSS direction and the exact isolated local theme-toggle pilot in the originating conversation, then confirmed association with this issue. The existing native epic relationship remains unchanged.

This is a bounded exception to the existing exclusion of styling refactoring—not approval of a broader migration. Existing root-configuration scope, acceptance criteria and historical evidence remain intact. Pilot success does not establish whole-issue completion.

The proposed local branch is build/styles-sass-theme-toggle-pilot, subject to a fresh baseline and applicable repository-policy check. This approval does not resolve the broader branch/PR questions recorded below.

Evidence baseline and execution state

Repository: lightspeedwp/ThisOneTimeOnAcidCom, develop.

Research baseline: b383eaaac04d16cc49bb5ef340db2a29e79e33b2. Refresh before implementation; material changes require review.

Read-only research enumerated 148 tracked guideline files and 127 CSS files, searched current guideline content, and mapped literal stylesheet references. This is inventory and lexical-analysis coverage—not runtime, dynamic-consumer or bundler verification.

Execution is not established. The attempted start was blocked by unavailable coding credits. A manual checklist and unsaved results worksheet were subsequently supplied, but no completed worksheet, implementation diff, build output or browser evidence was returned. No pilot pass, Make compatibility or completion is claimed.

Exact approved source scope

  1. Rename src/styles/blocks/theme-toggle.css to src/styles/blocks/theme-toggle.scss, preserving all 4,241 source bytes.

  2. Update only the stylesheet extension in both importers:

    • src/app/components/common/ThemeToggle.tsx
    • src/app/components/common/ThemeToggleES5.tsx

    Replace:

    ../../../styles/blocks/theme-toggle.css
    

    with:

    ../../../styles/blocks/theme-toggle.scss
    
  3. Add exact development dependency "sass": "1.106.1" to package.json.

  4. Generate the matching package-lock.json through npm. Stop for review on unrelated upgrades or unexplained lockfile churn; do not fabricate lockfile entries.

Expected unchanged stylesheet SHA-256:

f49801e267c1826ef3a902ec89c57e67abdaa13211fac8df434a4f640fa3c62e

No class renaming, nesting, declaration changes, token substitutions, theme-logic changes or import-order changes are included. Retain existing React/Tailwind integration.

Verification safeguards and authorised temporary effects

Use a disposable, no-secrets checkout. Permit network access only during approved package acquisition; block external requests during builds and browser checks. Require .env.sentry-build-plugin to be absent without printing secrets.

Create temporary, uncommitted root vite.style-verify.config.ts by copying the current root Vite configuration and making only these changes:

  • Replace dsn: config.env.VITE_SENTRY_DSN with dsn: ''.
  • Add disable: true and telemetry: false to sentryVitePlugin options.

Leave production configuration untouched. Root placement preserves relative configuration imports and alias resolution.

Ordinary builds are excluded: inspected Sentry behaviour can include telemetry, release/upload operations and source-map deletion. Removing an auth token alone is not a sufficient safeguard. Existing test chains may reload production configuration.

Approved temporary effects comprise local dependency acquisition/installations, generated lockfile, temporary verification configuration, private build output and loopback preview services. Do not overwrite existing output or remove unrelated files. Lifecycle-disabled installation does not satisfy the issue’s separate lifecycle-enabled installation acceptance gate.

Verification sequence

Record exact commit, Node/npm versions, commands, exit codes, warnings and evidence locations.

  • A — baseline: original manifest/lockfile and CSS.
  • B — dependency-only: exact Sass dependency and reviewed lockfile; original CSS retained.
  • C — pilot: dependency changes plus byte-identical rename and both importer edits.

Use npm ci --ignore-scripts --no-audit --no-fund for isolated installation. Generate the dependency change with:

npm install --save-dev --save-exact --package-lock-only \
  --ignore-scripts --no-audit --no-fund sass@1.106.1

Review the manifest/lockfile before proceeding. Stop if required initialisation fails; do not automatically enable lifecycle scripts.

For each stage, use the temporary configuration:

npm run build -- --config vite.style-verify.config.ts \
  --outDir .cache/style-verification/baseline

Use corresponding output directories dependency-only and pilot for B and C. Keep hidden source maps and output private.

Compare baseline and pilot through loopback-only preview servers using the same temporary configuration, separate ports and blocked external requests. Use equivalent saved-theme states on both origins.

Pilot acceptance criteria

  • Fresh baseline, applicable instructions, clean working tree and approved file scope recorded.
  • Source rename matches the expected byte count/hash; both importers updated; no stale references in verified scope.
  • Exact compiler pin and generated lockfile reviewed; no unexplained unrelated dependency changes.
  • A/B/C compilation results and warnings recorded separately.
  • No unexplained selector, declaration, media-query order, asset-resolution or cascade changes.
  • Default, saved-light and saved-dark states—including reload persistence—match.
  • Icons, accessible name, hover/active states, keyboard focus and Enter/Space behaviour match.
  • Reduced motion, mobile-menu context, 768/769px boundary and representative narrow/wide viewports checked.
  • Direct route loads and client navigation checked.
  • External-network blocking and Sentry safeguards verified; remote-font/asset limitations disclosed.
  • Results worksheet, relevant diffs and browser evidence reviewed; unchecked items explicitly marked not run.
  • Make compatibility separately verified before recommending merge or rollout.

Generated CSS formatting and filenames may differ; source-byte identity does not require generated-byte identity.

Outstanding gates and exclusions

Make compatibility remains unverified. Vite success does not demonstrate Make compiler/import support. No Make synchronisation, upload or publication is authorised.

Preserve the no-Sass scope of #395; do not silently revise its validation contract. Coordinate any future guidelines work through #416. Neither issue is changed by this pilot.

Stop on baseline drift, unrelated changes, secrets, failed isolation, unexpected dependency churn, compilation failure, missing assets, unexplained warnings or styling/interaction regressions. Additional source/configuration requirements need a revised exact proposal.

No guidelines adoption, broader stylesheet conversion, BEM cleanup, production configuration, CI changes, commits, pushes, PRs, deployment, publication or issue closure is authorised.

Rollback and handover

Stop preview services. Restore the original stylesheet filename, both imports and matching manifest/lockfile together. Remove only approved temporary configuration/output after preserving useful evidence; do not discard unrelated work.

Record the local outcome as passed locally, failed or inconclusive, with evidence and unresolved gates. A local pass does not establish Make acceptance, deployment, publication or completion of this issue’s wider root-configuration work.

Current delivery and branch audit — 24 October 2026

This current snapshot supersedes conflicting earlier branch instructions and implementation-status claims below. Earlier dated notes remain historical evidence, not current acceptance. No status, hierarchy, native PR association or repository change is proposed by this description patch.

  • Outcome: Complete approved 15-file root-configuration assessment and remaining package/runtime validation.
  • Recorded status: In Progress. Accepted whole-child completion is not established.
  • Verified implementation position: Node 24 and npm lockfile exist. Current package declares Vite ^8.3.4, tailwindcss ^4.1.12 and @tailwindcss/vite ^4.3.3; vite.config.ts loads the Tailwind plugin. Earlier “Tailwind tooling removed” claims are not current-head truth. Preserve the approved BEM direction while reconciling Make/plugin consumers explicitly, not through automatic removal. Root netlify.toml now exists and sets Node 24/npm 10; src/app/netlify.toml is absent. CONTRIBUTING/AGENTS claims about missing root config or nested npm 11 activation are stale. No lint command exists. Requested .cjs config names must not duplicate active jest.config.js; .markdownlint.json exists.
  • Outstanding acceptance: Approve per-file add/adapt/defer manifest and version/lint authority; reconcile npm/dependencies/hooks/documentation; demonstrate lifecycle-enabled install, native modules, build/journal/browser and effective deployment.

Branch instructions

  • Repository: lightspeedwp/ThisOneTimeOnAcidCom
  • Implementing issue(s): this existing child; GitHub sync counterpart build: repo-governance - Tailor repository root configuration #258 in the same repository. Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified.
  • Parent epic context: native parent verified; coordination only. No implementation branch/file plan belongs to the epic itself.
  • Allowed closing target(s): none now. Whole-child acceptance and independent GitHub/Linear mapping/association review are required before proposing a closing target; never the parent.
  • Branch state: unresolved
  • Branch: unresolved — exact recommendation withheld
  • Base: develop, verified at 3f583002482d80ffd1910676bcf7c63e13989b20; refresh before separately authorised implementation
  • Naming policy: target instructions, contributor guide, validator, local branch guide, organisation strategy. Classification rationale: build is the candidate code/documentation class; authorised prefix is checked independently of the Linear title. No exact new name is recommended; no branch mutation or reuse is approved.
  • Pull request template: UNRESOLVED: local build/→chore/default vs shared build/→pr_ci.md
  • PR association safeguard: No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
  • Constraints: preserve unrelated work; do not create/switch/rename/delete branches, force-push, merge, deploy, change settings or close records under this draft. Shared locked configuration/templates require human review. Residual protected-file declarations remain relevant despite absent guard workflow; do not equate absent automated enforcement with permission. Workflow ownership conflicts require controller/owner resolution, not local edits to managed dependency workflows.
  • Conflicts or missing evidence: All 15 requested dispositions remain unresolved: VERSION, jest.config.cjs, eslint.config.cjs, babel.config.cjs, .distignore, .editorconfig, .gitattributes, .gitignore, .npmrc, .nvmrc, .prettierignore, .prettierrc, .markdownlint.config.cjs, .markdownlint-cli2.cjs, .coderabbit.yml. Existing alternatives must be assessed; do not create each requested name blindly. Root active config does not independently verify Netlify UI/runtime.

Expected file changes

Plan status: provisional bounded proposal, not an approved or exhaustive implementation manifest; conditional rows are not permission to act.

Operation Path(s) Intended change Path evidence/revision Approval or dependency
Edit package.json Only approved command/dependency-policy reconciliation, no unrelated upgrades. Current scripts/engines read; 3f583002482d80ffd1910676bcf7c63e13989b20 Approved manifest/tooling decisions
Edit package-lock.json Align only approved manifest changes. Current authoritative npm lockfile; 3f583002482d80ffd1910676bcf7c63e13989b20 Conditional; no unrelated upgrades
Edit CONTRIBUTING.md Correct current package commands and obsolete nested-deployment assertions. Current stale statements read; 3f583002482d80ffd1910676bcf7c63e13989b20 Scope coordination with #453
Edit AGENTS.md Correct obsolete runtime/commands/deployment assertions without weakening safeguards. Current contradictions read; 3f583002482d80ffd1910676bcf7c63e13989b20 Protected file; exact human approval
Edit netlify.toml Only owner-approved change proven necessary by effective deployment evidence. Read root Node24/npm10 config; 3f583002482d80ffd1910676bcf7c63e13989b20 Conditional; no setting/deployment change authorised
  • Out of scope: Unrelated dependency upgrades, packaging without consumer, VERSION invention, second lockfile, bulk formatting and styling refactor.
  • Remaining discovery: All 15 requested dispositions remain unresolved: VERSION, jest.config.cjs, eslint.config.cjs, babel.config.cjs, .distignore, .editorconfig, .gitattributes, .gitignore, .npmrc, .nvmrc, .prettierignore, .prettierrc, .markdownlint.config.cjs, .markdownlint-cli2.cjs, .coderabbit.yml. Existing alternatives must be assessed; do not create each requested name blindly. Root active config does not independently verify Netlify UI/runtime.
  • Scope-change gate: stop for revised exact scope and approval before adding materially different paths or operations. No unbounded “other files as needed”. Protected-file approval never overrides a prohibition on routine agent edits.

Evidence and handoff packet

  • Recipient and request: originating issue-management audit; read-only exact existing-record preview for approval, not a new intake or implicit specialist invocation.
  • Selected record: this existing child description, separate from the coordination parent; no writes performed.
  • Implementing targets and criteria: this child’s existing outcome and acceptance criteria remain in force. Complete approved 15-file root-configuration assessment and remaining package/runtime validation. Outstanding gates: Approve per-file add/adapt/defer manifest and version/lint authority; reconcile npm/dependencies/hooks/documentation; demonstrate lifecycle-enabled install, native modules, build/journal/browser and effective deployment.
  • Sources checked: current Linear description/status/native parent/relations/explicit pullRequests and GitHub sync metadata; target instructions, contributor guide, validator, local branch guide, organisation strategy; the exact source paths/revisions above and current repository inventory. Shared template config checked at 47aee0722033f65d4d9d57429b410b518646b817. Some path evidence is inventory-only and is labelled as such; it is not full content/behaviour validation.
  • Branch/PR evidence: Current remote inventory includes historical epic/repo-governance-lightspeedwp/ThisOneTimeOnAcidCom#237 and broad governance/testing branches; scope/base/diff fit was not verified, so none is recommended for reuse. An open application-instrumentation pull request overlaps shared configuration; refresh its head, changed paths and scope before choosing a branch or editing shared files. No reuse is approved. Native PR list: automation: repo-governance - Add governance automation and validation #346 merged.
  • Association and closing rationale: Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified. No complete-child acceptance or closing target established. Linear GitHub documentation lookup identified the integration article but did not expose its detailed association content; current workspace linking/status rules remain unverified. No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
  • Unresolved points and exclusions: All 15 requested dispositions remain unresolved: VERSION, jest.config.cjs, eslint.config.cjs, babel.config.cjs, .distignore, .editorconfig, .gitattributes, .gitignore, .npmrc, .nvmrc, .prettierignore, .prettierrc, .markdownlint.config.cjs, .markdownlint-cli2.cjs, .coderabbit.yml. Existing alternatives must be assessed; do not create each requested name blindly. Root active config does not independently verify Netlify UI/runtime. Unrelated dependency upgrades, packaging without consumer, VERSION invention, second lockfile, bulk formatting and styling refactor.
  • Approval state: draft only. Exact description-preview approval is still required; repository edits/branch actions/PRs/settings/native associations retain separate boundaries. Existing GitHub issue sync is active, so approved description changes may propagate externally; no duplicate GitHub body write is proposed.

Review and implement the approved configuration across all requested root files:

Approved governance decisions — 17 October 2026

Owner approved all nine governance decisions. Governance decisions document.

  • PKG-001: DECIDED — npm-only. PR ci: netlify - Standardise package manager and runtime configuration #341 merged removal of pnpm artefacts/settings; installation and effective deployment verification remain outstanding.
  • NODE-001: DECIDED — Node 24 configuration is present on develop. Verify the effective deployment runtime rather than reintroducing completed configuration.
  • STYLE-001: DECIDED — BEM-only direction retained; Tailwind tooling removal has merged. Validate remaining consumers and browser behaviour before claiming complete styling acceptance.

Reported branch migration: invalid claude/keen-davinci-90r05v replaced by epic/repo-governance-toa-241 in ThisOneTimeOnAcidCom and epic/governance-decisions-update in .github. All CodeRabbit findings reported addressed; PR #268 reported ready for merge with minimal risk. PR #268 is merged; its former readiness wording is historical and does not establish completion of this issue. Link implementation PRs to their respective decision issues.

Root configuration scope

npm-only reconciliation plan

PKG-001 is decided: npm is the sole supported package manager for local development, CI and deployment. package-lock.json is the authoritative lockfile; use npm ci for clean installations. Node 24 and Jest/SWC changes are recorded as merged in the existing progress notes; verify the current implementation rather than reintroducing completed setup work. This plan does not claim cleanup or validation is complete.

Remaining implementation

  • Inspect the current branch and implementation PRs before editing; distinguish completed changes from outstanding work.
  • Verify the merged removal of pnpm artefacts/settings and preserve any required dependency policy; do not re-delete files absent from the implementation baseline.
  • Verify that the removed pnpm Vite override is not reintroduced; review intended dependency versions and npm lockfile without automatic override translation.
  • Reconcile the approved manifest and npm lockfile without unrelated upgrades. Review React runtime/type declarations and native dependency installation requirements.
  • Align Git hooks, package commands, README and contributor guidance so no supported path requires pnpm.
  • Verify Node/npm selection across local configuration, CI and the configuration actually used by Netlify. Confirm installation behaviour separately from the build command; resolve conflicting nested configuration where applicable.
  • Confirm dependency-update tooling maintains the npm lockfile. Route any centrally managed workflow changes through its controller rather than local edits.

Verification checklist

  • One supported package manager and authoritative lockfile remain
  • Clean npm ci succeeds without modifying tracked manifest or lockfile
  • Hooks and documented commands require no pnpm installation
  • Expected dependency versions and native modules are verified
  • Build and relevant unit, integration and browser checks run; failures are recorded explicitly
  • An approved Netlify preview confirms actual Node/npm installation and build configuration
  • Implementation PR and validation evidence are linked before closure

Safeguards

No repository-wide formatting, folder migration or unrelated dependency upgrade is included. Handle the separately approved Tailwind decision outside this package-manager change; preserve the recorded implementation history. Software, site and guideline version authority remains a separate decision. No new merge, deployment or successful-validation claims are implied.

VERSION, jest.config.cjs, eslint.config.cjs, babel.config.cjs, .distignore, .editorconfig, .gitattributes, .gitignore, .npmrc, .nvmrc, .prettierignore, .prettierrc, .markdownlint.config.cjs, .markdownlint-cli2.cjs, .coderabbit.yml.

Acceptance criteria

  • Each file is classified as add, adapt existing or defer with rationale
  • Runtime, package-manager and version-authority decisions are resolved
  • Test transformation, linting and formatting fit React/TypeScript/Vite
  • Existing ignore rules and repository-specific CodeRabbit guidance are preserved
  • .distignore is added only for an identified packaging consumer
  • Configuration entry points do not duplicate or conflict
  • Build and relevant validation commands pass

Target: book repository. Reference: shared repository root.

Current implementation and remaining acceptance — 19 October 2026

Reviewed against develop revision 4ecdb26d9655a48bf000a7c89da2f70383edce87. No tests, interface submissions, settings changes or metadata mutations were performed during this review. Merged changes are partial evidence, not automatic completion.

Delivered: Node 24, npm, Jest/SWC and Tailwind tooling changes are merged. #341 removed pnpm artefacts/override and aligned nested Netlify configuration. Removal is confirmed at the inspected revision; package-manager choice is not open.

Remaining acceptance: classify all 15 files; reconcile lockfile/dependency policy, lifecycle hooks and stale guidance; resolve lint/format/version authority; verify lifecycle-enabled installation, native dependencies, build/journal/browser behaviour and effective Netlify settings.

Validation gap: lifecycle-disabled install/Jest results do not satisfy those gates. Verify remaining animation-package consumers rather than claiming all styling dependencies are absent. Draft PR #346 overlaps delivered cleanup and is not additional delivery.

Metadata

Metadata

Assignees

Type

No type

Fields

Priority

None yet

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions