Skip to content

refactor: repo-governance - Relocate Spec Kit specification output #250

Open

Description

@ashleyshaw

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 canonical creation, compatible dual-location numbering and collision handling without moving existing features.
  • Recorded status: In Progress. Accepted whole-child completion is not established.
  • Verified implementation position: Bash creates under .github/specs. Gemini instructions and plan/tasks templates are now canonical, superseding this issue’s root-default/legacy-template claims. Both inspected numbering descriptions remain canonical-root-focused; approved dual-location/ambiguity behaviour still requires verification. Preserve the newer path-containment and branch gates.
  • Outstanding acceptance: Verify dual-location allocation, collision/ambiguity handling, legacy contexts and real authored Gemini flow; obtain matched-tooling base/head evidence. 103/104 accepted historical baseline and 93/104 missing-PyYAML run are not current results.

Branch instructions

  • Repository: lightspeedwp/ThisOneTimeOnAcidCom
  • Implementing issue(s): this existing child; GitHub sync counterpart refactor: repo-governance - Relocate Spec Kit specification output #250 in the same repository. Independently read GitHub issue and matched Linear sync mapping.
  • 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: refactor 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: shared pr_refactor.md — explicitly read/use its sections; do not add a repository-local copy
  • 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: Inspect newer changes in c3ca303 and integration manifests before final scope; explicit-number semantics, dual-root approval vs containment contract, actual Gemini availability and association effects unresolved. Old proposed refactor/refactor: repo-governance - Relocate Spec Kit specification output #250-speckit-output-path is not re-endorsed. Template behaviour-neutrality language conflicts with intentional routing/numbering changes.

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 .specify/scripts/bash/create-new-feature.sh Implement only remaining approved combined-numbering/collision behaviour; preserve canonical output and branch/path safeguards. Creator line 202 and canonical-only numbering inspected; 3f583002482d80ffd1910676bcf7c63e13989b20 Separate code approval; do not weaken newer safeguards
Edit .gemini/commands/speckit.specify.toml Align remaining numbering/ambiguity rules, not reapply already-delivered canonical defaults. Current canonical root and containment contract read; 3f583002482d80ffd1910676bcf7c63e13989b20 Managed integration customisation and actual Gemini verification
Edit tests/speckit.test.mjs Extend approved compatibility/ambiguity fixtures under matched tooling. Existing canonical/context suite path and blob verified; 3f583002482d80ffd1910676bcf7c63e13989b20 No unrun success claims; Python/PyYAML parity
Edit CONTRIBUTING.md Document retained legacy compatibility and deliberate upgrade handling. Existing Spec Kit section read; 3f583002482d80ffd1910676bcf7c63e13989b20 Separate implementation approval
  • Out of scope: Feature migrations/renumbering, new integration installs, resolver rewrite, workflow/validator implementation, package changes and fingerprint refresh to conceal drift.
  • Remaining discovery: Inspect newer changes in c3ca303 and integration manifests before final scope; explicit-number semantics, dual-root approval vs containment contract, actual Gemini availability and association effects unresolved. Old proposed refactor/refactor: repo-governance - Relocate Spec Kit specification output #250-speckit-output-path is not re-endorsed. Template behaviour-neutrality language conflicts with intentional routing/numbering changes.
  • 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 canonical creation, compatible dual-location numbering and collision handling without moving existing features. Outstanding gates: Verify dual-location allocation, collision/ambiguity handling, legacy contexts and real authored Gemini flow; obtain matched-tooling base/head evidence. 103/104 accepted historical baseline and 93/104 missing-PyYAML run are not current results.
  • 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. No native linked PR was returned for this child; descriptive/historical references are not native associations.
  • Association and closing rationale: Independently read GitHub issue and matched Linear sync mapping. 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: Inspect newer changes in c3ca303 and integration manifests before final scope; explicit-number semantics, dual-root approval vs containment contract, actual Gemini availability and association effects unresolved. Old proposed refactor/refactor: repo-governance - Relocate Spec Kit specification output #250-speckit-output-path is not re-endorsed. Template behaviour-neutrality language conflicts with intentional routing/numbering changes. Feature migrations/renumbering, new integration installs, resolver rewrite, workflow/validator implementation, package changes and fingerprint refresh to conceal drift.
  • 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.

Outcome

Make .github/specs/ the default specification location across the installed Spec Kit integration without relocating or breaking existing features.

Current implementation position — 22 October 2026

Partially implemented; not ready to close.

Reviewed develop revision:
c9dd145

  • Bash already creates new features under .github/specs/.
  • Bash numbering and collision checks still inspect only the canonical location.
  • Gemini instructions still default to root specs/ and root-only numbering.
  • Downstream explicit-directory → persisted-context resolution already works.
  • Existing canonical-output fixtures must be preserved and extended.
  • Templates retain legacy default-path examples.

Current validation: node --test tests/speckit.test.mjs returned
93/104 passing. Ten failures reported missing PyYAML; one concerns the
known preset-path edge case. This is not evidence of 11 code regressions.
A matched-tooling base/head comparison remains required.

Approved implementation defaults

  • Scan legacy and canonical locations; allocate above the highest recognised feature number.
  • Create new features only in the canonical location.
  • Reject ambiguous duplicate identifiers clearly.
  • Do not move or renumber existing features.
  • Preserve Bash’s existing interface; defer adding full-directory override support.
  • Preserve Gemini overrides, downstream precedence, JSON/flags and persistence contracts.
  • Maintain local integration customisations through deliberate upgrade review; do not refresh fingerprints merely to hide drift.

Implementation approach

  1. Preserve delivered Bash canonical output and existing interfaces.
  2. Scan canonical and legacy locations together; allocate above their
    combined highest recognised feature number.
  3. Reject ambiguous identifiers and explicit-number collisions without
    moving, renumbering or overwriting existing features.
  4. Align Gemini defaults and numbering while preserving overrides,
    persistence/non-persistence and authored-task behaviour.
  5. Correct default-path examples without removing legacy compatibility.
  6. Extend collision, legacy-context, spaced-path, JSON/flags,
    non-persistence and separate-process create → plan → tasks coverage.
  7. Document customised integration files and deliberate upgrade handling.
    Do not refresh fingerprints merely to conceal drift.
  8. Assess specification-validation requirements and implementation
    ownership separately; routing tests do not deliver that broader scope.

Branch instructions

  • Repository: lightspeedwp/ThisOneTimeOnAcidCom
  • Implementing issue: this issue; verified GitHub counterpart refactor: repo-governance - Relocate Spec Kit specification output #250.
  • Parent: coordination context only; never a development or closing target.
  • Allowed closing targets: none until whole-outcome verification.
  • Branch state: unresolved.
  • Previously proposed branch: refactor/toa-254-speckit-output-path.
    It is absent locally/remotely and passes naming validation.
    Creation/reuse is not authorised; association effects remain unverified.
  • Base: fresh develop; last checked at
    c9dd145.
  • Naming: repository CONTRIBUTING.md, scripts/validate-branch-name.js and
    organisation BRANCHING_STRATEGY.md permit refactor/.
  • PR template: shared pr_refactor.md, selected explicitly.
    Disclose intentional default-path/numbering changes rather than
    asserting behaviour neutrality.
  • Constraints: preserve unrelated work; no force-push, merge or deployment.
  • Unresolved: association effects, template wording conflict, executable
    Gemini verification and supported integration-manifest handling.

Expected file changes

Plan status: bounded proposal; existing paths verified at the revision
above. No repository edits authorised by this description update.

Operation Path Intended change Evidence Dependency
Edit .specify/scripts/bash/create-new-feature.sh Combined numbering and collision checks; preserve canonical output/interfaces Existing canonical creator Separate implementation authorisation
Edit .gemini/commands/speckit.specify.toml Canonical defaults and compatible numbering/context instructions Existing root-default instructions Actual Gemini-flow verification
Edit .specify/templates/plan-template.md Correct default-path examples Existing legacy examples Preserve local customisations
Edit .specify/templates/tasks-template.md Correct input-path example Existing legacy example Preserve unrelated content
Edit tests/speckit.test.mjs Extend compatibility and collision fixtures Existing canonical/context tests Identical tooling on base/head
Edit CONTRIBUTING.md Targeted integration, verification and upgrade guidance Existing Spec Kit section No wholesale rewrite
  • Out of scope: feature migrations, new integrations, workflow/validator
    implementation, package changes, task-marker changes and resolver rewrite.
  • Remaining discovery: duplicate semantics, Gemini execution availability
    and supported manifest-preservation mechanism.
  • Protected planning dependency: draft the separate validation assessment;
    do not edit the specification plan without required approval.
  • Scope-change gate: stop before adding files or materially different work.

Evidence and handoff packet

  • Recipient: issue-management; description refinement only.
  • Selected record: this implementing issue; no other descriptions changed.
  • Criteria: preserve existing approved acceptance criteria.
  • Sources: current issue/sync, repository instructions, six listed paths,
    working resolver and organisation branch/template policy.
  • Branch/PR evidence: proposed branch absent; no matching open PR verified.
  • Association rationale: GitHub counterpart verified; automatic status
    effects unresolved. No closing directives or parent association.
  • Approval state: description preview only; no code execution authorised.

Acceptance criteria

  • Both creation flows default to the canonical location.
  • Dual-location numbering and collision behaviour match approved defaults.
  • Explicit overrides and persisted legacy paths remain supported.
  • Relative, absolute and spaced paths retain their supported behaviour.
  • Existing artefacts are not overwritten.
  • Paths-only/non-persistence modes create no unintended state.
  • Missing context produces a clear failure.
  • Separate-process creation → plan → task prerequisites retains one directory.
  • Gemini’s actual authored-task flow is verified separately from Bash template preparation.
  • Templates, documentation and fixtures agree.
  • Upgrade preservation is documented; manifest changes use a verified supported mechanism.

Verification

Run node --test tests/speckit.test.mjs on base and final head under identical tooling. Record exact revisions, environment, named failures and accepted exceptions.

Historical baseline acceptance remains valid context, not proof of current results.

Risk and rollback

Primary risks are numbering collisions, broken legacy context and upgrade overwrite of customisations. Revert the implementation change if necessary; do not delete or relocate user specifications as rollback.

Definition of Ready

  • Outcome, scope and defaults approved.
  • Repository consumers and compatibility boundaries identified.
  • Branch/base/template direction checked.
  • Execution environment and fresh baseline recorded before implementation validation.

Definition of Done

  • Acceptance criteria demonstrated at final head.
  • Compatibility regressions covered.
  • Documentation and upgrade handling accepted.
  • Maintainer review recorded.
  • Remaining specification-validation CI assessment explicitly accounted for.

Scope boundary

No unrelated migrations, new agent integrations or workflow/protected-file edits. Preserve the existing specification-validation evaluation reference and coordination with its owning workstream; routing regression alone does not complete that broader assessment.

Retained decisions and source references

Owner approved all nine governance decisions. Governance decisions document.

  • SPEC-001: DECIDED — Keep .github/specs/ as the canonical specification location.
  • TEST-002: DECIDED — Accept the 103/104 baseline as production-ready with a known edge case.

Both decisions unblock this workstream; implementation and regression verification remain outstanding.

This is not a wholesale replacement with the shared repository’s different Spec Kit version.

Target: book repository. Reference: shared .github directory.

Evaluation reference: validate-specifications.yml.

Planning destination: .github/specs/001-repo-governance-layout-and-agentic-workflows/.

Preserve the existing implementation scope for canonical paths and create → plan → tasks regression. Separately assess CI validation of specification structure, applicable metadata/catalogue requirements and invalid fixtures. Record the decision and implementation task ownership in the plan; do not assume path regression alone delivers specification-validation CI. Coordinate workflow syntax checks with #240.

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