Align ways-of-working guidance with the issue model

[MariusStorhaug]

The new issue model changes assumptions currently repeated across workflow, readiness, branching, goal-setting, specification, pull-request, agent-workflow-stage, and orchestration guidance. Those pages must agree that aggregate issues plan and track while delivery leaves build and ship.

Request

Update every affected Ways of Working and agent-facing page to consume the canonical OKF issue guidance without restating it. Ensure phases, readiness, closure, pull-request linking, stacked-work dependencies, and indexes-first workflow discovery reflect native issue types and relationships.

Acceptance criteria

• Workflow sends only Task/Bug delivery leaves into Build; Epic/PBI decompose and aggregate
• Definition of Ready and Done defines level-appropriate gates for aggregate versus leaf issues
• Branching and Merging uses native issue dependencies rather than textual Blocked by conventions
• PR Format closes exactly one Task/Bug and references parent PBI/Epic without closing keywords
• Goal Setting clarifies the Mission → OKR → Initiative → Epic boundary and the issue-type strategy above Epic
• Spec-Driven Development uses the canonical Epic/PBI/Task/Bug terminology and links to the new pages
• Contribution Workflow, Documentation Model, Fleet Orchestration, and Agent Workflow stage pages use the new paths and semantics
• Workflow is the canonical process entry; the Workflow Stages index only routes to stage procedures
• Root AGENTS.md preserves repository-specific operational policy from the live base: continuous improvement/issue escalation, ecosystem setup topology, docs-versus-memory contribution modes, repository-local identity, README/CONTRIBUTING orientation, memory use, and micro-commit/push discipline
• The docs installation uses a bare backing repository with ~/.msx/docs as the readable clean main worktree; memory remains a simple main checkout, and unsafe legacy topology cannot be silently converted or discarded
• The bootstrap is pluggable for additional projects with their own docs and memory; every project uses bare docs plus a canonical default worktree and simple memory, with validated non-overlapping workspace paths
• Restored root instructions link to canonical Workflow stages rather than copying stage procedures
• Discovery refreshes the local ~/.msx/docs checkout before following AGENTS.md -> docs root -> Ways of Working -> Workflow -> inferred stage; explicit task keywords may shortcut to a stage without creating another process definition
• A failed local docs refresh stops discovery with an explicit error; it never silently continues through stale documentation
• Bootstrap synchronization has hermetic regression coverage for successful exact refresh and rejection of unsafe or unavailable context states
• Stage procedures live under Ways-of-Working/Workflow-Stages/; no src/docs/Agents/ compatibility stubs, duplicates, or stale paths remain
• No page redefines body structures, hierarchy, or relationship semantics owned by the Issues section
• Index check, links, lint, clean build, CI, and Copilot review are green

---

Technical decisions

Reference, do not restate: The Issues section owns the model. Other pages state only their local consequence and link to the canonical page.

Leaf pull requests: A pull request closes its Task/Bug delivery issue. PBI/Epic links are contextual and non-closing.

Native dependencies: Stacked pull requests mirror issue dependency edges; list order and prose do not create execution gates.

Agent workflow stages: src/docs/Ways-of-Working/Workflow-Stages/ contains the stage procedures and handoffs for one shared workflow, not standalone agent roles or personas. The obsolete src/docs/Agents/ path is removed atomically. Bootstrap and framework guidance use the same model.

Repository pointer scope: Thin means no copied canonical process; it does not mean deleting repository-specific setup, contribution, memory, identity, or delivery policy. Root AGENTS.md preserves those local obligations and links outward for Workflow stages.

Workspace topology: MSXOrg/docs uses a bare backing repository and worktrees, with the canonical clean main worktree readable at ~/.msx/docs; topic worktrees use concise folders and typed issue branches. MSXOrg/memory remains a simple checkout on main. Bootstrap must preserve or safely migrate supported existing states and fail explicitly rather than destructively converting an unsafe state.

Project plug-ins: Additional projects provide docs and memory coordinates to the same bootstrap. Project roots, checkouts, bare backing stores, and migration backups must be normalized and pairwise non-overlapping before any filesystem mutation.

Refresh-first, indexes-first discovery: Refresh the canonical local ~/.msx/docs checkout before traversing its indexes. If refresh fails, stop and surface the failure rather than silently using stale guidance. Workflow.md owns process progression and stage selection. Root and section indexes lead to it; Workflow-Stages/index.md, skills, instruction files, agent definitions, and repository pointers only route to stage procedures and never copy the workflow.

---

Implementation plan

Workflow alignment

• Update workflow, readiness/done, branching, PR, goal-setting, and spec-driven pages
• Update contribution, documentation-model, orchestration, and Agent Workflow stage consumers
• Make Workflow canonical and align indexes-first stage discovery without duplicate process definitions
• Atomically relocate stage procedures from src/docs/Agents/ to Ways-of-Working/Workflow-Stages/
• Refresh ~/.msx/docs before index traversal and fail explicitly when refresh cannot complete
• Align bootstrap, template, framework, and workflow-discovery wording with the refresh-first contract
• Add hermetic regression coverage for exact synchronization and fail-closed refresh states
• Restore the material repository-specific root AGENTS.md contract without copying Workflow stage definitions
• Align bootstrap, template, tests, and guidance with a bare docs backing repo plus canonical ~/.msx/docs main worktree and simple memory checkout
• Prove pluggable project topology and reject exact, ancestor, and descendant workspace-path collisions before mutation
• Remove duplicated legacy terminology and textual relationship conventions

Validation

• Search the full documentation tree for stale paths and semantics
• Run documentation checks, CI, and the Copilot review loop

[MariusStorhaug]

Baseline audit at live origin/main f156c3658969b03250c8af79a452649106aa5df3 (the merged Types/Process result from #94).

Native graph confirmed: #86 is a Task under #84, blocked by closed #87 and #88, and blocks open #90. No metadata migration is part of this task.

The canonical Ways-of-Working/Issues/ pages already own type hierarchy and bodies, planning/lifecycle, and native containment/dependency semantics. Consumer drift found before editing:

• Workflow.md routes generic simple tasks, sub-issues, and checklists directly into Build and cites obsolete numbered body sections.
• Definition-of-Ready-and-Done.md has one leaf-only readiness/done gate and does not cover Epic/PBI aggregation or the audited operational Task path.
• Branching-and-Merging.md records stack order with textual Blocked by: #N instead of native dependencies.
• PR-Format.md permits arbitrary closing links rather than exactly one Task/Bug; parent context is not distinguished from closure.
• Goal-Setting.md compresses the Initiative/Epic boundary into a one-to-one mapping.
• Spec-Driven-Development.md uses generic Tasks and the legacy epic -> item -> task ladder.
• Contribution-Workflow.md does not restrict repository delivery to Task/Bug leaves.
• Documentation-Model.md points generically at Issue Format rather than the canonical planning ownership boundary.
• Fleet-Orchestration.md treats a PR alone or optional tracking issue as a campaign work item and duplicates closure semantics.
• Agents/define.md, Agents/implement.md, and Agents/reviewer.md assume a universal three-section Task contract or generic issue delivery rather than routing by native type and altitude.

No stale pre-OKF file paths were found; current links already target Issues/Process/ and Issues/Types/. The implementation will change only local consumer consequences and link back to canonical owners rather than copy their definitions.

[MariusStorhaug]

Implementation and validation audit complete.

• Pull request: 📖 [Docs]: Ways of working now follows the canonical issue model #97
• Exact base: f156c3658969b03250c8af79a452649106aa5df3
• Exact head: eab23ca5a549b9f867e42bd5110fc6446a921c64
• Commits: 9010e39, a840def, 3f78fbd, 133ad22, eab23ca
• Scope: 20 documentation files across Workflow, readiness/done, branching, PR format, goal setting, spec-driven development, contribution, documentation model, fleet orchestration, worktrees, review guidance, agent roles, indexes, repository defaults, and downstream release propagation.
• Full-tree searches found no stale pre-OKF paths. Obsolete numbered body-section references, manual dependency conventions, generic work-item/tracking-issue exceptions, and PR-without-delivery-issue semantics were removed from affected consumers. Unrelated release Feature terminology and metadata migration were left unchanged.
• Local validation: documentation index update and check, full link validation, clean Zensical build, git diff --check, and all 14 Pester tests passed.
• PR CI at the exact head: Links, Build, Lint, and every reported linter context passed; Publish correctly skipped for the PR.
• Copilot review: two feedback rounds produced three valid comments, all fixed, replied to, and resolved. The fresh exact-head round at eab23ca reviewed all 20 files with zero new comments.
• PR state: ready for review, only NoRelease, assigned to MariusStorhaug, squash auto-merge enabled, still open and blocked on the required independent code-owner/last-push approval.

No live issue metadata was changed and no metadata-migration finding was discovered; #90 remains outside this pull request.

[MariusStorhaug]

Correction applied from review: agent guidance is now framed as one shared workflow rather than a catalog of standalone roles.

• Agents/index.md now defines the process and its transitions: Define -> Implement -> Review, with changes returning to Implement and Security Review as a specialized path.
• Each agent page now identifies its workflow stage, entry condition, boundary, and handoff.
• Workflow maintenance is explicitly outside delivery and owns the stage descriptions and thin repository pointers.
• Navigation, generated indexes, Agentic Development guidance, framework docs, memory-template terminology, and Fleet Orchestration now consume the same workflow-stage model.

Commit: a71bd38. The PR is draft again while exact-head CI and Copilot review rerun.

[MariusStorhaug]

Agent-workflow correction is fully revalidated at exact head a71bd387c0b36d3b9ec74b86855c87fce4b7da1f.

• Documentation index check and full link validation passed.
• Clean Zensical build passed.
• All 14 Pester tests passed.
• Exact-head PR Links, Build, Lint, and all reported linter contexts passed.
• Fresh exact-head Copilot review returned zero comments.

The PR can return to ready status with squash auto-merge; independent approval remains the only merge gate.

[MariusStorhaug]

Expanded exact-worktree audit follow-up completed in 9ae0d89.

Removed the final directly coupled stale role/persona framing from:

• Ways-of-Working/Principles/AI-First-Development.md (One workflow, not a swarm; shared stages and specialized review paths),
• bootstrap/README.md, and
• bootstrap/AGENTS.template.md.

A repository-wide boundary-aware search for agent role(s), roles agents play, specialized roles, persona, role descriptions, and per-agent-role returns no matches. Local index update/check, full links, clean build, and all 14 Pester tests pass. PR #97 remains draft with auto-merge disabled while exact-head CI and explicit Copilot review run.