Repository navigation
Align ways-of-working guidance with the issue model #86
Description
Activity
Baseline audit at live
origin/mainf156c3658969b03250c8af79a452649106aa5df3(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.mdroutes generic simple tasks, sub-issues, and checklists directly into Build and cites obsolete numbered body sections.Definition-of-Ready-and-Done.mdhas one leaf-only readiness/done gate and does not cover Epic/PBI aggregation or the audited operational Task path.Branching-and-Merging.mdrecords stack order with textualBlocked by: #Ninstead of native dependencies.PR-Format.mdpermits arbitrary closing links rather than exactly one Task/Bug; parent context is not distinguished from closure.Goal-Setting.mdcompresses the Initiative/Epic boundary into a one-to-one mapping.Spec-Driven-Development.mduses generic Tasks and the legacyepic -> item -> taskladder.Contribution-Workflow.mddoes not restrict repository delivery to Task/Bug leaves.Documentation-Model.mdpoints generically at Issue Format rather than the canonical planning ownership boundary.Fleet-Orchestration.mdtreats a PR alone or optional tracking issue as a campaign work item and duplicates closure semantics.Agents/define.md,Agents/implement.md, andAgents/reviewer.mdassume 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/andIssues/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
Featureterminology 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
eab23careviewed all 20 files with zero new comments. - PR state: ready for review, only
NoRelease, assigned toMariusStorhaug, 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.mdnow 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, andbootstrap/AGENTS.template.md.
A repository-wide boundary-aware search for
agent role(s),roles agents play,specialized roles,persona,role descriptions, andper-agent-rolereturns 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.mdnow owns stage routing and keyword shortcuts;Agents/index.mdis 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 asReview this PR <link>,Make this issue <description>, andImplement <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.13 remaining items
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-backupretained; - 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
~/.msxlayout 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/docsand 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.
- docs use a sibling bare backing repository (
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 insidedocsordocs.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
docsanddocs.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.
- Pre-bootstrap AGENTS/README seed now fetches/prunes an existing
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
docsanddocs.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
$repovariable; - 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
b3c9255evidence 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
b3c9255a3d63bea4acf9c68c95be4a38e33eaa0dafter 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 plusPath = '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.gitfiles/worktrees, returns an uncheckedrev-parseresult, and leavesMove-Itemoutside 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
.gitfiles/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.
- memory
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 liveorigin/main(65591bd0c1c477984f6b04fedb21406fee00f62e; merge-basef156c3658969b03250c8af79a452649106aa5df3). 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.- added a commit that references this issue
on Jul 26, 2026 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/docsmain worktree + simple memory checkout — confirmed inbootstrap/Initialize-MsxWorkspace.ps1and exercised live via bootstrap. - Pluggable project topology with exact/ancestor/descendant collision rejection — confirmed via
-Projectsupport and the corresponding Pester cases intests/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
Docsworkflow run on7df16fd.
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.
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
Blocked byconventionsAGENTS.mdpreserves 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~/.msx/docsas the readable cleanmainworktree; memory remains a simplemaincheckout, and unsafe legacy topology cannot be silently converted or discarded~/.msx/docscheckout before following AGENTS.md -> docs root -> Ways of Working -> Workflow -> inferred stage; explicit task keywords may shortcut to a stage without creating another process definitionWays-of-Working/Workflow-Stages/; nosrc/docs/Agents/compatibility stubs, duplicates, or stale paths remainTechnical 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 obsoletesrc/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.mdpreserves those local obligations and links outward for Workflow stages.Workspace topology:
MSXOrg/docsuses a bare backing repository and worktrees, with the canonical cleanmainworktree readable at~/.msx/docs; topic worktrees use concise folders and typed issue branches.MSXOrg/memoryremains a simple checkout onmain. 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/docscheckout before traversing its indexes. If refresh fails, stop and surface the failure rather than silently using stale guidance.Workflow.mdowns 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
src/docs/Agents/toWays-of-Working/Workflow-Stages/~/.msx/docsbefore index traversal and fail explicitly when refresh cannot completeAGENTS.mdcontract without copying Workflow stage definitions~/.msx/docsmain worktree and simple memory checkoutValidation