Repository navigation
Restructure issue guidance as an OKF section #84
Description
MSX issue guidance currently spans overlapping format and hierarchy pages, while related workflow, readiness, branching, goal-setting, and pull-request pages make assumptions that apply only to delivery leaves. Agents must assemble the model across several documents, and the live organization configuration has not yet been fully reconciled with the intended Epic → PBI → Task/Bug hierarchy.
Request
Create one recursively navigable OKF issue-guidance section that explains how issues evolve through the existing workflow, how each native issue type is structured, and how containment differs from execution order. Align the surrounding ways-of-working guidance and migrate live issue metadata so the documented model and GitHub configuration agree.
Acceptance criteria
- Epic and PBI are native enabled organization issue types; Task and Bug remain delivery-leaf types
- Issue guidance is organized as small frontmatter-bearing pages under generated indexes
- Workflow remains authoritative for Capture, Refine, Plan, Build, Review, Ship, and Operate; issue pages map body and relationship evolution onto those phases
- Epic, PBI, Task, and Bug each have a distinct body, readiness, closure, and promotion/demotion model
- Native sub-issues are the source of truth for containment and progress
- Native blocked-by/blocking relationships are the source of truth for sequencing; ready siblings without dependency edges may execute in parallel
- Only Task/Bug delivery leaves receive closing pull requests; operational Tasks have a verified non-PR completion path
- Cross-cutting guidance no longer assumes every issue is a single PR-sized deliverable
- Applicable live Feature assignments and obsolete Bug/Feature hierarchy labels or conventions are migrated before Feature is retired
- Every child issue is complete, documentation checks are green, and no duplicated legacy guidance remains
Technical decisions
OKF structure: The issue model is a folder of small pages with title and description frontmatter. Generated indexes route humans and agents by phase, relationship question, and issue type.
Hierarchy: Epic and PBI aggregate scope. Task and Bug are delivery leaves. Nested PBIs are allowed when decomposition requires another aggregation level.
Relationships: Sub-issues express containment only. Blocked-by/blocking relationships express execution order. List position and body text do not imply sequence.
Workflow ownership: Workflow.md remains the only owner of phase definitions. Issue lifecycle guidance describes what happens to an issue during those phases without restating the workflow.
Delivery: Every executable unit has an issue. Repository implementation uses one session, branch, and pull request per Task/Bug. Parent PBIs coordinate and aggregate without owning implementation branches.
Migration: Feature remains enabled until the final migration verifies that no applicable live issue depends on it.
Delivery plan
Delivery is tracked through native sub-issues. Sub-issue relationships define scope; dependency relationships define the order in which child work may proceed. The parent closes only after all children and aggregate acceptance criteria are complete.
Activity
MariusStorhaug commentedon Jul 25, 2026
Created the native delivery graph. Sub-issues: bootstrap Task #82, OKF-section PBI #85, cross-document Task #86, and migration Task #90. Dependencies: #82 blocks relocation #89; #89 blocks the parallel Process #88 and Types #87 Tasks; #87 and #88 both block #86; #86 blocks #90. Containment and execution order are represented only through GitHub relationships.
MariusStorhaug commentedon Jul 25, 2026
Bootstrap Task #82 is complete via merged PR #83 (
d4c4a15). Relocation Task #89 is now unblocked and has started from liveorigin/main(92d25fc) in its own coordinated delivery session. Process #88 and Types #87 remain correctly blocked until #89 merges.MariusStorhaug commentedon Jul 25, 2026
Relocation Task #89 is implemented in PR #91 at commit
2215cae. The atomic path/navigation cutover, complete inbound-link update, local validations, CI, and explicit clean Copilot review are complete. The PR is ready with squash auto-merge enabled and waits only for independent approval; #87 and #88 remain blocked until it merges.MariusStorhaug commentedon Jul 25, 2026
Relocation Task #89 completed via merged PR #91 (
3e04c260). Parallel sibling Tasks #87 (Types) and #88 (Process) have now started from that live default-branch commit in separate coordinated sessions with strict subtree ownership. Cross-document Task #86 remains blocked until both merge.MariusStorhaug commentedon Jul 25, 2026
Parallel implementation exposed one genuine serialization edge: Process #88 links to the canonical type pages created by Types #87, so #88 link CI cannot pass before #87 lands. A native dependency now records that merge order. Development remains parallel; #86 still waits for both completed Tasks.
MariusStorhaug commentedon Jul 25, 2026
Parallel implementation exposed one genuine serialization edge: Process #88 links to the canonical type pages created by Types #87, so #88 link CI cannot pass before #87 lands. A native dependency now records that merge order. Development remains parallel; #86 still waits for both completed Tasks.
MariusStorhaug commentedon Jul 25, 2026
Types Task #87 is complete in PR #93 at head
6c48e9b: all local checks and CI pass, the valid first Copilot finding was fixed, a fresh Copilot round is clean, and squash auto-merge is enabled. Independent approval is the sole remaining gate. Process #88 stays draft and natively blocked until #87 merges.MariusStorhaug commentedon Jul 25, 2026
Baseline correction for the parallel Tasks:
3e04c260is the required merged #89 blocker ancestor, not their branch base. Both #87 and #88 fetched first and started exactly at then-liveorigin/main39411c555adfde1e357be44f63ccddc11e95fc73, which includes unrelated PR #92 and has no overlap with either issue subtree or their Zensical subsections. The earlier execution-order statement remains correct; this comment corrects only the exact starting SHA.5 remaining items
MariusStorhaug commentedon Jul 26, 2026
Independent exact-worktree audit found three stale role references directly coupled to the user correction: AI-First still described many specialized roles, and both bootstrap guidance files still advertised agent roles. PR #97 is back in draft with auto-merge cleared; issue #86 now explicitly defines Agents as shared workflow stages. The focused fixes and full gates are rerunning; #90 remains blocked.
MariusStorhaug commentedon Jul 26, 2026
Task #86 is finalized at
9ae0d89after the user correction and independent residual search. Agents are consistently framed as one shared workflow with stages and specialized review paths across canonical pages, framework consumers, AI-First guidance, and bootstrap files. Full local/CI/review gates are green; PR #97 is ready with squash auto-merge and waits only for independent approval. #90 remains blocked.MariusStorhaug commentedon Jul 26, 2026
Task #86 reopened for a second direct user correction.
Workflow.mdmust be the canonical process entry;Agents/index.mdis only a stage-procedure index. Discovery is indexes-first from AGENTS.md through docs root and Ways of Working to Workflow, then an inferred stage; explicit keywords may shortcut to a stage without creating copied skill/instruction/agent definitions. PR #97 is draft with auto-merge cleared and gates reopened; #90 remains blocked.MariusStorhaug commentedon Jul 26, 2026
Task #86 is finalized at
59770e5after the indexes-first discovery correction and coordinator audit. Workflow is the canonical process entry; root/Ways indexes and thin AGENTS/bootstrap pointers lead to it; stage pages are procedure-only; clear task language may shortcut through Workflow; no skill, command, named agent, or instruction file copies process behavior. All issue checklist items, local gates, exact-head CI, and fresh 36/36-file Copilot review are complete. PR #97 is ready with squash auto-merge and awaits only independent approval; #90 remains blocked.MariusStorhaug commentedon Jul 26, 2026
Task #86 reopened for another direct IA correction: stage procedures must move atomically from obsolete
src/docs/Agents/intosrc/docs/Ways-of-Working/Workflow-Stages/, with semantic filenames, updated navigation/inbound links, and no compatibility stubs or duplicates. PR #97 is draft with gates reopened; Workflow remains canonical and #90 remains blocked.MariusStorhaug commentedon Jul 26, 2026
Task #86's information-architecture correction is complete at
d75e44accfc329d77de91516ee5a4b2f96b7bc3f. Stage procedures now live underWays-of-Working/Workflow-Stages/; the oldAgents/tree is absent from the Git tree, navigation/indexes and inbound links are aligned, and Workflow remains canonical. Coordinator audit caught three still-open issue checklist items, returned PR #97 to draft, independently reran the full gate, completed the checklist, then restored ready state and squash auto-merge. PR #97 is OPEN/BLOCKED only on independent approval. Task #90 remains untouched and blocked on #86 landing.MariusStorhaug commentedon Jul 26, 2026
Task #86 reopened for a direct discovery correction: canonical local
~/.msx/docsmust be refreshed before any index traversal. Refresh failure must stop with an explicit error; stale documentation is never a silent fallback. Bootstrap behavior, template/README/framework/workflow wording, stale-search, and all validation/review gates are reopened. PR #97 is draft with auto-merge disabled; Task #90 remains blocked and untouched.MariusStorhaug commentedon Jul 26, 2026
Task #86's refresh-first correction is independently accepted at
a40ef22adee824d3bafe1585ffb1b0eddb7e7909. Canonical docs and memory must synchronize exactly before index traversal; all stale/unavailable states fail closed. Hermetic tests now cover exact docs+memory fast-forward and dirty, ahead, diverged, wrong-branch, and unreachable failures (20/20 suite). Real~/.msxsynchronization, docs gates, exact-head CI, 43/43-file clean Copilot review, and 9/9 resolved threads are verified. Issue #86 has no unchecked items; PR #97 is ready with squash auto-merge and remains OPEN/BLOCKED only on independent approval. Task #90 remains untouched and blocked.MariusStorhaug commentedon Jul 26, 2026
Task #86 remains draft for a root-instructions regression correction. The user selected the original docs installation model: a bare
MSXOrg/docsbacking repository with~/.msx/docsas the readable cleanmainworktree; topic worktrees keep concise folders and typed issue branches. Memory remains a simplemaincheckout. Root AGENTS policy must be restored without copying Workflow stages, and bootstrap/template/tests/guidance must align safely with no destructive legacy conversion or stale fallback. #90 remains blocked and untouched.MariusStorhaug commentedon Aug 9, 2026
#90 has completed the final live-metadata migration. The organization now enables only Task, Bug, Feature, Epic, PBI, and Feature is disabled after a verified empty assignment inventory. All 4 native children are closed; the PBI's aggregate acceptance criteria are complete.
MariusStorhaug commentedon Aug 9, 2026
#90 has been reopened because retiring the legacy
Featureissue type requires an organization permission unavailable to the current authenticated account. The documentation, native types, issue classification, and relationship migration are complete; the parent remains open until an authorized organization owner disablesFeatureand closes #90.MariusStorhaug commentedon Aug 9, 2026
#90 has completed the final metadata migration. Feature is retired, the enabled organization issue types are Task, Bug, Epic, and PBI, and all four native sub-issues are complete. The PBI's aggregate acceptance criteria are complete.