📖 [Docs]: Ways of working now follows the canonical issue model

AGENTS.md

@@ -1,29 +1,72 @@
-# Agents
+# Agent Instructions
 
 ## Main directive
 
-Everything is a work in progress and can be updated and improved.
-If you find a problem, fix it if it's small; otherwise, register it as an issue in the respective repo.
+Everything is a work in progress and can be updated and improved. Fix a small problem when it is directly in scope; register a larger or unrelated problem as an issue in the repository that owns it.
 
-## Install the ecosystem
+This repository belongs to `github.com/MSXOrg`.
 
-1. Create a folder in the home directory called `.msx`:
-2. Clone the ecosystem locally:
-   1. <https://github.com/MSXOrg/docs> — requires PRs to be updated.
-      - Clone as bare and use worktrees.
-      - Create a worktree for every branch. Use a concise `<issue>-<slug>` worktree folder for a topic branch named `<type>/<issue>-<slug>`.
-   2. <https://github.com/MSXOrg/memory/> — work directly towards main.
-      - Simple clone, only main.
+## Install and synchronize the ecosystem
 
-To install:
-- Clone the repos in the users home folder under a sub-folder named `.msx`.
-- Set configs locally to each of these repos using the GitHub username and email.
+The agent workspace lives under `~/.msx`:
 
-## Working with the ecosystem
+| Repository | Local path | Purpose | Change model |
+| --- | --- | --- | --- |
+| `MSXOrg/docs` | `~/.msx/docs.git` + `~/.msx/docs` | Bare backing repository plus clean readable main worktree for reviewed organization context. | Pull requests through topic worktrees only. |
+| `MSXOrg/memory` | `~/.msx/memory` | Durable organization memory: prior decisions, gotchas, and reusable working knowledge. | Commit and push directly to `main`, per that repository's policy. |
 
-1. Get to know this repo first:
-   - [README](README.md) for what this repository is and how it builds.
-   - [CONTRIBUTING](CONTRIBUTING.md) for how to contribute and the review process.
-2. Read `~/.msx/docs` - start with the index to get an overview of what is here.
-3. Read `~/.msx/memory` - start with the index to get an overview of what is here. Use this while working - commit your memories here for work inside the PSModule organization.
-4. While working with the code, do small micro commits and push on every commit. This will make it easier to review and merge your changes.
+From this repository, install missing context repositories and synchronize every existing clone before use:
+
+```powershell
+pwsh bootstrap/Initialize-MsxWorkspace.ps1 `
+  -UserName '<github-user>' `
+  -UserEmail '<github-noreply-email>'
+```
+
+Projects that add their own docs and memory provide plug-in coordinates without changing the synchronization implementation:
+
+```powershell
+$projects = @(
+  @{
+    Name = 'MSXOrg'
+    Path = ''
+    DocsUrl = 'https://github.com/MSXOrg/docs.git'
+    MemoryUrl = 'https://github.com/MSXOrg/memory.git'
+  }
+  @{
+    Name = 'PSModule'
+    Path = 'projects/PSModule'
+    DocsUrl = 'https://github.com/PSModule/docs.git'
+    MemoryUrl = 'https://github.com/PSModule/memory.git'
+  }
+)
+& ./bootstrap/Initialize-MsxWorkspace.ps1 -Project $projects
+```
+
+The bootstrap writes identity only to each context repository's local git configuration. It must succeed before any context is read; do not continue with missing, dirty, diverged, wrong-branch, unreachable, or stale context.
+
+Use a dedicated worktree for every topic branch. Follow [Git Worktrees](src/docs/Ways-of-Working/Git-Worktrees.md) for the local layout and [Branching and Merging](src/docs/Ways-of-Working/Branching-and-Merging.md) for `<type>/<issue>-<slug>` branch names.
+
+## Canonical context
+
+- Docs root: [src/docs/index.md](src/docs/index.md)
+- Organization memory: `~/.msx/memory/index.md`
+
+## Before acting
+
+1. Segment the work by host, organization, repository, path, and task.
+2. Synchronize every canonical context repository to its remote default branch; stop if any context may be stale.
+3. Start at the docs root index and follow [Ways of Working](src/docs/Ways-of-Working/index.md) to the canonical [Workflow](src/docs/Ways-of-Working/Workflow.md).
+4. Infer the current stage from the task and its artifacts, then read the linked stage procedure.
+5. Read [README.md](README.md), [CONTRIBUTING.md](CONTRIBUTING.md), relevant standards, and organization memory.
+6. Apply path-specific local rules only when they match the files in scope.
+
+## Working in this repository
+
+1. Use [README.md](README.md) to understand what this repository is and how it builds.
+2. Use [CONTRIBUTING.md](CONTRIBUTING.md) for its contribution and review contract.
+3. Keep work reviewable with small, descriptive micro-commits.
+4. Push every commit so the remote branch, CI, and draft pull request reflect current work.
+5. Improve organization memory when a verified lesson is likely to matter again; commit and push MSXOrg memory directly to `main`.
+
+This file owns bootstrap and repository-specific operating instructions. The linked documentation owns reusable process knowledge; this file does not redefine a workflow stage, coding standard, or review convention.

bootstrap/AGENTS.template.md

@@ -2,28 +2,134 @@
 
 The single starting point for any agent, in any repository. Before doing anything else, make sure the central workspace exists locally, then read from it.
 
+## Main directive
+
+Everything is a work in progress and can be updated and improved. Fix a small problem when it is directly in scope; register a larger or unrelated problem as an issue in the repository that owns it.
+
 ## First — bootstrap the workspace
 
-The workspace is a git-isolated clone of the central repositories under `~/.msx`. Set it up (idempotent — clones what is missing, attempts to fast-forward the rest):
+The workspace is a git-isolated clone of the central repositories under `~/.msx`. Set it up before reading context. Existing context repositories must be clean, on their default branch, and exactly synchronized with the remote:
 
 ```powershell
-$docs = Join-Path $HOME '.msx/docs'
+$workspaceRoot = if ($env:MSX_WORKSPACE_ROOT) { $env:MSX_WORKSPACE_ROOT } else { Join-Path $HOME '.msx' }
+$docsUrl = if ($env:MSX_DOCS_URL) { $env:MSX_DOCS_URL } else { 'https://github.com/MSXOrg/docs.git' }
+$memoryUrl = if ($env:MSX_MEMORY_URL) { $env:MSX_MEMORY_URL } else { 'https://github.com/MSXOrg/memory.git' }
+$docs = Join-Path $workspaceRoot 'docs'
+$docsBacking = "$docs.git"
 if ((Test-Path $docs) -and -not (Test-Path (Join-Path $docs '.git'))) {
     throw "$docs exists but is not a git repository. Remove it and re-run."
 }
 if (-not (Test-Path (Join-Path $docs '.git'))) {
-    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $docs) | Out-Null
-    git clone https://github.com/MSXOrg/docs.git $docs
+    if (-not (Test-Path $docsBacking)) {
+        New-Item -ItemType Directory -Force -Path (Split-Path -Parent $docs) | Out-Null
+        git clone --bare $docsUrl $docsBacking
+        if ($LASTEXITCODE -ne 0) {
+            throw "Bare clone of MSXOrg/docs failed (exit $LASTEXITCODE). Check network access and credentials."
+        }
+    }
+    if ((git --git-dir=$docsBacking rev-parse --is-bare-repository) -ne 'true') {
+        throw "$docsBacking exists but is not a bare repository."
+    }
+    if ((git --git-dir=$docsBacking remote get-url origin) -ne $docsUrl) {
+        throw "$docsBacking origin does not match canonical $docsUrl."
+    }
+    $refspec = '+refs/heads/*:refs/remotes/origin/*'
+    if ($refspec -notin @(git --git-dir=$docsBacking config --get-all remote.origin.fetch)) {
+        git --git-dir=$docsBacking config --add remote.origin.fetch $refspec
+        if ($LASTEXITCODE -ne 0) { throw "Could not configure $docsBacking." }
+    }
+    git --git-dir=$docsBacking fetch origin --prune --quiet
+    if ($LASTEXITCODE -ne 0) { throw "Could not refresh $docsBacking. Do not use stale context." }
+    git --git-dir=$docsBacking remote set-head origin --auto | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw "Could not detect the MSXOrg/docs default branch." }
+    $defaultRef = (git --git-dir=$docsBacking symbolic-ref --short refs/remotes/origin/HEAD | Out-String).Trim()
+    if ($LASTEXITCODE -ne 0) { throw "Could not resolve origin/HEAD in $docsBacking." }
+    $defaultBranch = $defaultRef -replace '^origin/', ''
+    $remoteHead = (git --git-dir=$docsBacking rev-parse $defaultRef | Out-String).Trim()
+    if ($LASTEXITCODE -ne 0) { throw "Could not resolve $defaultRef in $docsBacking." }
+    $localRef = "refs/heads/$defaultBranch"
+    $localHead = (git --git-dir=$docsBacking rev-parse --verify $localRef 2>$null | Out-String).Trim()
+    if ($LASTEXITCODE -eq 128) {
+        git --git-dir=$docsBacking update-ref $localRef $remoteHead
+    } elseif ($LASTEXITCODE -ne 0) {
+        throw "Could not inspect $localRef in $docsBacking."
+    } elseif ($localHead -ne $remoteHead) {
+        git --git-dir=$docsBacking merge-base --is-ancestor $localHead $remoteHead
+        if ($LASTEXITCODE -ne 0) { throw "$localRef is ahead or diverged in $docsBacking." }
+        if ("branch $localRef" -in @(git --git-dir=$docsBacking worktree list --porcelain)) {
+            throw "$localRef is checked out elsewhere. Update that worktree first."
+        }
+        git --git-dir=$docsBacking update-ref $localRef $remoteHead $localHead
+    }
+    if ($LASTEXITCODE -ne 0 -or (git --git-dir=$docsBacking rev-parse $localRef) -ne $remoteHead) {
+        throw "$localRef is not exactly synchronized with $defaultRef."
+    }
+    git --git-dir=$docsBacking worktree add $docs $defaultBranch
+    if ($LASTEXITCODE -ne 0) {
+        throw "Could not create the canonical MSXOrg/docs worktree at $docs."
+    }
+} else {
+    if ((git -C $docs remote get-url origin) -ne $docsUrl) {
+        throw "$docs origin does not match canonical $docsUrl."
+    }
+    $refspec = '+refs/heads/*:refs/remotes/origin/*'
+    if ($refspec -notin @(git -C $docs config --get-all remote.origin.fetch)) {
+        git -C $docs config --add remote.origin.fetch $refspec
+        if ($LASTEXITCODE -ne 0) {
+            throw "Could not configure remote tracking branches for MSXOrg/docs (exit $LASTEXITCODE)."
+        }
+    }
+    git -C $docs fetch origin --prune --quiet
     if ($LASTEXITCODE -ne 0) {
-        throw "git clone of MSXOrg/docs failed (exit $LASTEXITCODE). Check network access and github.com credentials, then re-run."
+        throw "git fetch of MSXOrg/docs failed (exit $LASTEXITCODE). Do not use stale context."
+    }
+    git -C $docs remote set-head origin --auto | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw "Could not detect the MSXOrg/docs default branch." }
+    $defaultRef = (git -C $docs symbolic-ref --short refs/remotes/origin/HEAD | Out-String).Trim()
+    if ($LASTEXITCODE -ne 0) { throw "Could not resolve origin/HEAD in $docs." }
+    $defaultBranch = $defaultRef -replace '^origin/', ''
+    $branch = (git -C $docs branch --show-current | Out-String).Trim()
+    if ($branch -ne $defaultBranch) {
+        throw "$docs is on '$branch', not '$defaultBranch'. Switch branches before using this context."
+    }
+    if (@(git -C $docs status --porcelain).Count -gt 0) {
+        throw "$docs has uncommitted changes. Resolve them before using this context."
+    }
+    git -C $docs merge --ff-only --quiet $defaultRef
+    if ($LASTEXITCODE -ne 0) {
+        throw "MSXOrg/docs cannot fast-forward to $defaultRef. Do not use stale context."
+    }
+    if ((git -C $docs rev-parse HEAD) -ne (git -C $docs rev-parse $defaultRef)) {
+        throw "$docs is not exactly synchronized with $defaultRef. Reconcile local commits before using this context."
     }
 }
-pwsh (Join-Path $docs 'bootstrap/Initialize-MsxWorkspace.ps1')
+$projects = @(
+    @{
+        Name = 'MSXOrg'
+        Path = ''
+        DocsUrl = $docsUrl
+        MemoryUrl = $memoryUrl
+    }
+    # Add project-specific entries when this template is adopted there:
+    # @{
+    #     Name = 'PSModule'
+    #     Path = 'projects/PSModule'
+    #     DocsUrl = 'https://github.com/PSModule/docs.git'
+    #     MemoryUrl = 'https://github.com/PSModule/memory.git'
+    # }
+)
+& (Join-Path $docs 'bootstrap/Initialize-MsxWorkspace.ps1') -Root $workspaceRoot -Project $projects
+if ($LASTEXITCODE -ne 0) {
+    throw "Context synchronization failed. Do not read context until every project is current."
+}
 ```
 
+Keep the MSXOrg entry and add only the additional project coordinates required by repositories that inherit this template. Every project reuses the same synchronization and validation implementation.
+
 This produces:
 
-- `~/.msx/docs` — how work is done: ways of working, coding standards, and agent roles. The same content published at <https://msxorg.github.io/docs/>.
+- `~/.msx/docs.git` — bare backing repository for central docs.
+- `~/.msx/docs` — clean, readable main worktree containing ways of working, standards, and workflow guidance.
 - `~/.msx/memory` — what has been learned before: durable notes and prior session context.
 
 Each clone has repository-local git config only; it never modifies the global git config or the repository being worked in (git still reads them, but only repository-local config is written).
@@ -32,10 +138,22 @@ Each clone has repository-local git config only; it never modifies the global gi
 
 ## Then — read before acting
 
-1. Read the relevant pages under `~/.msx/docs` for the task at hand.
-2. Read `~/.msx/memory` for prior decisions, pitfalls, and context.
+1. Start at `~/.msx/docs/src/docs/index.md`.
+2. Follow the Ways of Working index to `Workflow.md`.
+3. Infer the current stage from the task and its artifacts, then read the linked stage procedure.
+4. Read the relevant standards, repository context, and `~/.msx/memory`.
+
+Clear task language may shortcut the index trail: `Review this PR <link>` enters Review, `Make this issue <description>` enters Define, and `Implement <issue>` enters Implement. The linked documentation owns each procedure; this file does not define a separate agent or skill.
+
+## Work in the selected repository
+
+1. Read its `README.md` to understand the repository and its build.
+2. Read its `CONTRIBUTING.md` for the contribution and review contract.
+3. Use a dedicated worktree and the branch naming defined by the canonical Ways of Working.
+4. Make small, descriptive micro-commits and push every commit so remote state, CI, and the draft pull request stay current.
+5. Capture verified reusable lessons in organization memory, following that repository's own instructions.
 
 ## Two write rules
 
-- **Docs change through pull requests.** Branch inside `~/.msx/docs` and open a pull request; never push its `main`.
-- **Memory pushes to main.** Commit and push notes directly inside `~/.msx/memory`; no pull request.
+- **Docs change through topic worktrees and pull requests.** Create a topic worktree from `~/.msx/docs.git`; never branch or work inside the canonical `~/.msx/docs` main worktree.
+- **Memory follows repository policy.** Read the selected memory repository's `AGENTS.md` and `CONTRIBUTING.md` before writing.