Skip to content

Relocate issue guidance into the OKF section #89

Closed
Task
#91
Closed
Relocate issue guidance into the OKF section#89
Task
#91
Assignees
MariusStorhaug
Labels
NoReleaseNo release required

Description

@MariusStorhaug
Marius Storhaug (MariusStorhaug)
opened on Jul 25, 2026

Issue Format and Issue Hierarchy currently live as large top-level Ways of Working pages with inbound links and navigation entries throughout the repository. They must move into the new OKF subtree without creating a broken intermediate state.

Request

Atomically relocate the existing guidance to Issues/Process/Format.md and Issues/Types/Hierarchy.md, create the Issues, Process, and Types indexes, and update navigation plus every inbound path and anchor in the same pull request. Preserve existing semantics; later Tasks own the new process and type content.

Acceptance criteria

  • src/docs/Ways-of-Working/Issues/index.md, Process/index.md, and Types/index.md exist with complete frontmatter and generated navigation tables
  • Issue Format is moved to Issues/Process/Format.md
  • Issue Hierarchy is moved to Issues/Types/Hierarchy.md
  • src/zensical.toml points to the new locations
  • Every inbound repository link and heading anchor resolves to the new paths
  • No compatibility stub, duplicate legacy page, or unindexed issue-guidance page remains
  • Page content changes only where required for paths, titles, or navigation
  • Index check, link validation, lint, clean Zensical build, CI, and Copilot review are green

Technical decisions

Atomic cutover: File moves, indexes, navigation, and all inbound references land together because deferring references would make the first pull request fail its own link and index checks.

Stable concepts: Format remains the universal body-format owner; Hierarchy remains the type and containment overview. Later Tasks split detailed process and type rules into nearby pages.

No redirect stubs: OKF indexes provide discovery. Old filenames are removed rather than preserved as duplicate routing pages.

Implementation plan

Relocation

  • Inventory all inbound links and anchors to Issue Format and Issue Hierarchy
  • Create the indexed Issues/Process and Issues/Types structure
  • Move the two pages without semantic expansion
  • Update Zensical navigation and every inbound reference

Validation

  • Regenerate and verify documentation indexes
  • Validate links, lint, and clean site build
  • Complete CI and the Copilot review loop

Activity

  1. Marius Storhaug (MariusStorhaug)
    self-assigned this
    on Jul 25, 2026
  2. Marius Storhaug (MariusStorhaug)
    added
    NoReleaseNo release required
    on Jul 25, 2026
  3. Marius Storhaug (MariusStorhaug)
    marked this as blocked on Jul 25, 2026
  4. Marius Storhaug (MariusStorhaug)
    added the
    Task
    issue type on Jul 25, 2026
  5. Marius Storhaug (MariusStorhaug)
    added a parent issue on Jul 25, 2026
  6. Marius Storhaug (MariusStorhaug)
    marked this as blocking 2 issues on Jul 25, 2026

  7. MariusStorhaug commented on Jul 25, 2026

    @MariusStorhaug
    Marius Storhaug (MariusStorhaug)
    on Jul 25, 2026
    MemberAuthor

    Implementation started from live origin/main at 92d25fc after confirming bootstrap squash d4c4a15 is an ancestor.

  8. MariusStorhaug commented on Jul 25, 2026

    @MariusStorhaug
    Marius Storhaug (MariusStorhaug)
    on Jul 25, 2026
    MemberAuthor

    Atomic relocation is published in draft PR #91 from commit 2215cae.

    • Created the indexed Issues, Issue Process, and Issue Types structure
    • Moved Issue Format and Issue Hierarchy with 98% similarity; only required relative paths changed inside the pages
    • Updated Zensical navigation and all 25 inventoried inbound legacy path occurrences
    • Removed both legacy paths with no redirect stubs or duplicate pages
    • Index and full-link checks pass; complete local validation is in progress

  9. MariusStorhaug commented on Jul 25, 2026

    @MariusStorhaug
    Marius Storhaug (MariusStorhaug)
    on Jul 25, 2026
    MemberAuthor

    Local validation is complete for draft PR #91.

    • pwsh -NoProfile .github/scripts/Update-DocumentationIndex.ps1 -Check passed
    • pwsh -NoProfile .github/scripts/Test-DocumentationLink.ps1 passed: all documentation links resolve
    • Super-Linter v8.7.0 passed the documentation/config scope, including Markdown, natural-language, and codespell validators
    • zensical build --clean passed with no issues

  10. MariusStorhaug commented on Jul 25, 2026

    @MariusStorhaug
    Marius Storhaug (MariusStorhaug)
    on Jul 25, 2026
    MemberAuthor

    PR #91 has completed its automated gates.

    • Build, Links, and Lint jobs passed; every reported Super-Linter validator is green
    • Explicit Copilot review completed with COMMENTED, zero inline comments, and a clean-round result
    • All issue implementation and validation checklist items are complete
    • The pull request is ready for the independent human approval gate

  11. MariusStorhaug commented on Jul 25, 2026

    @MariusStorhaug
    Marius Storhaug (MariusStorhaug)
    on Jul 25, 2026
    MemberAuthor

    PR #91 is ready for human review and squash auto-merge is enabled.

    • The PR remains open and BLOCKED; it has not merged
    • Organization rules require independent approval of the last reviewable push and code-owner review where applicable
    • Auto-merge will wait for that independent human gate while preserving the green checks
  12. Marius Storhaug (MariusStorhaug)
    closed this as completedin #91on Jul 25, 2026
  13. Marius Storhaug (MariusStorhaug)
    added a commit that references this issue on Jul 25, 2026

    📖 [Docs]: Issue guidance now follows the OKF structure (#91)

    3e04c26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

NoReleaseNo release required

Type

Task

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions