Align ways-of-working guidance with the issue model

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

Validation

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

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.

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.

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.

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.

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.

Final expanded-audit gates passed at exact head 9ae0d89c5cf4ae5aec8b3290777ce6d700438509.

Repository-wide exact stale-framing search: no matches.
Index update/check: passed.
Full documentation links: passed.
Clean Zensical build: passed.
Pester: 14 passed, 0 failed.
Exact-head PR CI: Build, Links, Lint, and all reported linter contexts passed.
Fresh explicit Copilot review: zero comments.

PR #97 can return to ready with squash auto-merge enabled; it remains dependent on independent approval.

Independent final audit verified exact head 9ae0d89: the three residual AI-First/bootstrap role references are removed, the actual #86 worktree has no boundary-aware stale role/persona matches, local index/links/clean build/14 Pester tests pass, exact-head CI is green, and the fresh 31/31-file Copilot round has zero comments. The issue contract and checklist now consistently say Agent Workflow stages.

Workflow-discovery correction implemented in two focused commits:

a5ba29c — Workflow.md now owns stage routing and keyword shortcuts; Agents/index.md is only the stage-procedure index; navigation nests stage docs beneath Workflow.
965df09 — AGENTS.md, bootstrap guidance, Agentic Development, and its framework spec/design now require index-first discovery from docs root to Workflow and the inferred stage.

The default trail is AGENTS.md -> docs/index.md -> Ways of Working -> Workflow -> stage procedure. Prompts such as Review this PR <link>, Make this issue <description>, and Implement <issue> may shortcut stage selection, but skills, commands, named agents, and instruction files cannot own copied workflow behavior.

Repository-wide searches find no stale agent-definition/role/central-description terminology. Local index update/check, full links, clean Zensical build, git diff --check, and all 14 Pester tests pass. PR #97 remains draft with auto-merge disabled while exact-head CI and explicit Copilot review run.

Bare docs topology and full AGENTS policy restoration implemented in c4f4adb.

Final topology:

~/.msx/docs.git — bare MSXOrg/docs backing repository;
~/.msx/docs — clean readable default-branch worktree at the exact remote head;
~/.msx/<issue>-<slug> — concise topic worktrees using <type>/<issue>-<slug> branches;
~/.msx/memory — simple main checkout;
optional projects use ~/.msx/projects/<project>/{docs.git,docs,memory}.

Bootstrap behavior:

missing docs install directly as bare+main worktree;
clean exact simple clones migrate with all refs preserved and docs.simple-clone-backup retained;
canonical and legacy bare-backed worktrees are reused;
dirty, ahead, diverged, wrong-branch, unreachable, conflicting, or unsupported states fail explicitly before unsafe conversion;
memory remains a simple checkout;
project plug-ins reuse identical synchronization logic.

Root AGENTS retains all material base policy: continuous improvement/issue escalation, install/setup, docs via PRs, MSXOrg memory direct main, local identity, README/CONTRIBUTING, index use, durable memory, micro-commits, and push every commit. Workflow stages remain linked, not copied.

Validation: live ~/.msx topology passes; local PSScriptAnalyzer, index, links, clean build, and diff pass; full suite 23/23. PR #97 remains draft/auto-merge off; coordinator checklist/readiness untouched. Exact-head CI and review pending.

Bare+worktree topology restoration is exact-head clean at c4f4adb8fd0277e84c8e5e01d82cad70b895bed1.

Final implementation:

docs use a sibling bare backing repository (docs.git) plus a clean canonical readable default-branch worktree (docs);
topic worktrees retain concise <issue>-<slug> folders and <type>/<issue>-<slug> branches;
memory remains a simple checkout;
missing docs install directly into the canonical topology;
clean exact simple clones migrate with all refs preserved and a retained docs.simple-clone-backup;
canonical and legacy bare-backed worktrees are reused;
unsafe or conflicting conversions fail before data mutation;
project plug-ins use the same topology under collision-free relative paths.

Root AGENTS preserves every material base policy while linking Workflow stages rather than copying them. Git Worktrees, bootstrap README/template, framework design, and the live ~/.msx layout now describe the same topology.

Validation:

bootstrap topology/freshness/project suite: 9 passed;
full Pester suite: 23 passed, 0 failed;
live ~/.msx/docs.git + ~/.msx/docs and simple memory verification: passed;
local PSScriptAnalyzer, index check, links, clean build, and diff check: passed;
exact-head Build, Links, Lint, PowerShell lint, and every linter context: passed;
fresh explicit Copilot review: zero comments;
all review threads: resolved.

PR #97 remains draft with auto-merge disabled. Coordinator-owned checklist/readiness were not changed. No #90 scope.

Coordinator audit rejected c4f4adb8fd0277e84c8e5e01d82cad70b895bed1. Remaining blockers: an existing bare docs store with no worktree is not fetched/proven exact before the user template creates and executes a potentially stale bootstrap; tests always begin with a simple docs clone and therefore do not prove direct missing-install topology; bootstrap README tells users to branch inside the canonical clean main worktree; and the unrequested generic project-path API permits ancestor collisions inside docs or docs.git. Migration preservation/rollback also needs focused proof. The four recovery gates remain open.

Coordinator topology blockers fixed at 973eea0.

Pre-bootstrap AGENTS/README seed now fetches/prunes an existing docs.git, resolves remote default, proves/fast-forwards the local default ref to the exact remote head, rejects ahead/diverged/checked-out default refs, and only then creates/loads ~/.msx/docs.
Main bootstrap models docs and memory separately; direct missing install creates docs.git + docs worktree and simple memory.
Migration inventories and verifies every local branch/tag before moving the simple clone; preparation failure removes partial backing and leaves the original checkout usable; post-move failure restores the backup.
Project path validation rejects exact and ancestor/descendant overlap including docs and docs.git.
Bootstrap template no longer instructs work in canonical docs; topic worktrees come from docs.git.

Hermetic topology/freshness/seed suite now has 17 passing cases, including exact execution of both Markdown seed blocks, stale backing/no-worktree refresh, direct missing install, simple migration with branch/tag preservation and backup, idempotence, legacy backing reuse, rollback, project install, and unsafe path/state rejection. Full suite: 31/31. Local PSScriptAnalyzer, index, links, clean build, diff, and live ~/.msx topology pass.

PR #97 remains draft with auto-merge off; coordinator gates untouched. Exact-head CI/Copilot pending.

Final coordinator topology fixes are exact-head clean at b3c9255a3d63bea4acf9c68c95be4a38e33eaa0d.

Additional fixes after c4f4adb:

copied AGENTS/README seeds now refresh/prune existing bare backing, resolve remote default, safely fast-forward its local default ref, prove exact remote equality, and only then create/load the canonical docs worktree;
path validation rejects exact and ancestor/descendant collisions including docs and docs.git;
simple migration verifies every local branch/tag exists at the same object in the new backing;
preparation failure removes partial backing and leaves the original clone untouched;
injected post-move failure restores the original clone and removes both backup marker and partial backing;
Git Worktrees cleanup examples use the defined $repo variable;
copied seed snippets pass the selected workspace root into the full bootstrap.

Persistent hermetic coverage now has 17 topology/freshness/seed cases: both executable Markdown seeds, direct missing install, stale bare/no-worktree refresh, exact docs+memory sync, simple migration refs+backup+idempotence, canonical/legacy worktree reuse, post-move rollback, project install, overlap rejection, and unsafe states. Full suite: 31/31.

Local PSScriptAnalyzer, index, links, clean build, diff, and live ~/.msx topology pass. Exact-head Build/Links/Lint/PowerShell and every linter context pass. Fresh Copilot review returned zero comments; all threads resolved.

PR #97 remains draft with auto-merge disabled. Coordinator checklist/readiness untouched. No #90 scope.

Audit correction: the prior b3c9255 evidence comment was posted before two already-fixed Copilot threads were replied to and resolved. Both threads now have fix references, and all 14/14 review threads are resolved. PR #97 remains draft with auto-merge disabled for coordinator review.

Coordinator audit rejected b3c9255a3d63bea4acf9c68c95be4a38e33eaa0d after exact-head executable probes. The bootstrap accepts a memory worktree despite the required simple-checkout contract, and same-name project definitions bypass overlap validation: a root project plus Path = 'docs' both completed and dirtied canonical docs with nested repositories. Missing-install and overlap tests also omit required memory/identity/no-mutation assertions. Adjacent fail-closed gaps remain for configured-origin verification, unchecked remote-head resolution, and move-failure rollback. All five coordinator gates remain open; PR #97 stays draft with auto-merge disabled.

Final coordinator audit hardening is exact-head clean at fec49c67c4cd25ed61584089fd01557e4eed7e00.

Beyond c4f4adb, the branch now includes:

executable tests for the exact PowerShell seed blocks copied from AGENTS.template.md and README.md;
stale existing docs.git refresh/exact-head proof before canonical worktree creation/script loading;
canonical origin URL equality before any fetch in full bootstrap and both seeds;
direct missing install assertions for docs bare store + .git-file main worktree + simple memory + identity + idempotence;
simple migration branch/tag preservation, retained backup, and post-move rollback that removes partial backing;
overlap rejection for docs, docs.git, memory, migration backup, descendants, and nested project roots before mutation;
copy/paste-safe Git Worktrees cleanup commands and canonical-main no-work rule.

Hermetic topology/freshness/seed suite: 25/25. Full suite: 39/39. Local PSScriptAnalyzer, index, links, clean build, diff, and live ~/.msx topology passed. Exact-head Build, Links, Lint, PowerShell lint, and all contexts passed. Fresh Copilot review returned zero comments; all review threads are resolved.

PR #97 remains draft with auto-merge disabled. Coordinator checklist/readiness untouched. No #90 scope.

Coordinator audit rejected exact commit fec49c67c4cd25ed61584089fd01557e4eed7e00. Origin verification and broader different-name path checks landed, but exact committed source still skips overlap checks whenever two definitions share the same user-supplied project name, accepts memory .git files/worktrees, returns an unchecked rev-parse result, and leaves Move-Item outside rollback protection. The direct-install test still omits memory exactness and full docs/memory identity assertions. Existing green tests do not exercise these residual cases. All five gates remain open; PR #97 stays draft with auto-merge disabled.

Final current-head safety audit is exact-head clean at a8b9ee147a302586e112e8ae64b09a4c5a53b2dd.

Fixes beyond fec49c6:

memory .git files/worktrees and unsupported memory forms are rejected during preflight before docs mutation;
project names are unique case-insensitive definition identities;
overlap validation reserves non-empty project roots, docs worktrees, docs.git backings, memory checkouts, and migration backups, rejecting exact/ancestor/descendant collisions before mutation;
existing simple/bare/worktree docs and memory origins are validated against configured canonical URLs before any fetch;
remote-head resolution checks exit status and empty values;
move is inside migration activation; pre-move and post-move failures both restore usable original state and remove partial backing/backup, with rollback failures surfaced explicitly;
missing-install assertions now cover docs+memory branch, clean state, exact heads, local identity, and idempotence.

Focused topology/freshness/seed suite: 31/31. Full suite: 45/45. Local PSScriptAnalyzer, index, links, clean build, diff, and live ~/.msx topology passed. Exact-head Build, Links, Lint, PowerShell lint, and all contexts passed. Fresh Copilot review returned zero comments; all review threads are resolved.

PR #97 remains draft with auto-merge disabled. Coordinator checklist/readiness untouched. No #90 scope.

Coordinator audit accepted the residual bootstrap fixes at a8b9ee147a302586e112e8ae64b09a4c5a53b2dd; independent local gates passed, including 45/45 tests, zero PSScriptAnalyzer findings, index/link/build/diff checks, live exact topology, exploit probes, and stale-path/semantic searches. Readiness remains blocked because the branch is two commits behind fetched live origin/main (65591bd0c1c477984f6b04fedb21406fee00f62e; merge-base f156c3658969b03250c8af79a452649106aa5df3). The branch must merge live default, preserve both navigation changes, rerun every gate and exact-head CI, and receive a fresh zero-comment Copilot review. All coordinator gates remain open; PR #97 stays draft with auto-merge disabled.

Final live-default-integrated head: b854996692cf77418b581cd73457650f8de6526c. Normal merge from current origin/main preserved Workflow Stages navigation and added PowerShell Testing navigation. Merged-head local gates: 45/45 Pester, PSScriptAnalyzer, indexes, links, clean Zensical, diff check, live topology, and stale semantic searches passed. Exact-head Build/Links/Lint/PowerShell/all contexts passed. Fresh Copilot review returned zero comments; all review threads are resolved. PR #97 remains draft with auto-merge disabled for coordinator readiness. No #90 scope.

📖 [Docs]: Ways of working now follows the canonical issue model (#97)

Post-merge administrative audit: the implementation-plan checklist was stale relative to the merged result. Checked off the five remaining boxes to match the delivered and verified state at merge commit 7df16fd (PR #97):

Restore the material root AGENTS.md contract — confirmed present in the merged AGENTS.md.
Bare docs backing repo + canonical ~/.msx/docs main worktree + simple memory checkout — confirmed in bootstrap/Initialize-MsxWorkspace.ps1 and exercised live via bootstrap.
Pluggable project topology with exact/ancestor/descendant collision rejection — confirmed via -Project support and the corresponding Pester cases in tests/Initialize-MsxWorkspace.Tests.ps1.
Full-tree stale-path/semantics search and documentation checks/CI/Copilot review loop — confirmed clean per the merge audit trail and the green post-merge Docs workflow run on 7df16fd.

No implementation scope reopened; this only reconciles the checklist with already-shipped, already-audited work. Verified separately: origin/main HEAD is 7df16fd... (contains the merge), post-merge Docs/Build/Links/Lint/Publish checks are all green, and native relationships are intact (#86 blocked by #87/#88, blocks #90; parent #84). Task #90 remains correctly blocked-by-closed (unblocked for execution) with no changes to its own metadata-migration scope.

Navigation Menu

Repository navigation

Align ways-of-working guidance with the issue model #86

Request

Acceptance criteria

Technical decisions

Implementation plan

Workflow alignment

Validation

13 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Align ways-of-working guidance with the issue model #86

Description

Request

Acceptance criteria

Technical decisions

Implementation plan

Workflow alignment

Validation

Activity

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

13 remaining items

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

MariusStorhaug commented on Jul 26, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions