Capture lingering guidance edits

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

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 all branches - worktree = name of the branch.
-   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.

src/docs/Ways-of-Working/Branching-and-Merging.md

@@ -1,6 +1,6 @@
 ---
 title: Branching and Merging
-description: Topic branches, pull-request-only integration, and merge models.
+description: Delivery-leaf topic branches, pull-request-only integration, and merge models.
 ---
 
 # Branching and Merging
@@ -9,7 +9,7 @@ How changes move from a working branch into a protected branch. The model is sma
 
 ## Topic branches
 
-- Work happens on short-lived branches — one per issue, each in its own [worktree](Git-Worktrees.md). A branch is cut from the default branch unless a different base is explicitly given; an agent follows the same default.
+- Repository delivery happens on short-lived branches — one per Task or Bug, each in its own [worktree](Git-Worktrees.md). Epic and PBI aggregates do not own branches, and an operational Task has no branch. A branch is cut from the default branch unless a different base is explicitly given; an agent follows the same default.
 - Name branches `<type>/<issue>-<short-slug>`, e.g. `feat/42-pagination` or `fix/99-null-context`. The type matches the change type.
 - Branches stay short-lived. The longer a branch lives, the further it diverges and the harder it is to merge.
 
@@ -22,7 +22,7 @@ How changes move from a working branch into a protected branch. The model is sma
 
 ## Stacked pull requests
 
-Use a stack when several reviewable changes depend on one another and cannot land independently. Each layer remains one Task issue, one branch, and one pull request; the stack only records their dependency and order. Independent changes use separate branches from the default branch instead.
+Use a stack when several reviewable changes depend on one another and cannot land independently. Each layer remains one Task or Bug, one branch, and one pull request; the stack only records their dependency and order. Independent changes use separate branches from the default branch instead.
 
 Build the stack from its destination upward:
 
@@ -33,9 +33,9 @@ Build the stack from its destination upward:
 
 Every layer follows the ordinary [Contribution Workflow](Contribution-Workflow.md):
 
-1. **Plan the dependency.** Give each layer its own Task issue. Record `Blocked by: #N` on dependent issues as described in [Issue Hierarchy](Issue-Hierarchy.md#how-to-express-the-hierarchy), and order the implementation so the shared foundation is the first layer.
+1. **Plan the dependency.** Give each layer its own Task or Bug issue. Add a native blocked-by edge from every dependent leaf to its prerequisite as described in [Issue Relationships](Issues/Process/Relationships.md#execution-order); prose, sub-issue order, and stack position do not create the gate.
 2. **Open every layer as a draft.** After the initial commit, push the branch and open its pull request immediately. Use the standard user-facing title and description from [PR Format](PR-Format.md); do not add stack position or an internal branch name to the title.
-3. **Link the stack in Technical Details.** Add fully qualified pull request links for the immediate dependency and dependent, using `Depends on Owner/Repo#N` and `Followed by Owner/Repo#N`. Each pull request closes only its own Task issue.
+3. **Link the stack in Technical Details.** Add fully qualified pull request links for the immediate dependency and dependent, using `Depends on Owner/Repo#N` and `Followed by Owner/Repo#N`. Each pull request closes only its own Task or Bug.
 4. **Keep each delta isolated.** The pull request diff against its current base contains only that layer's change. Run its tests, checks, and automated review even when an earlier layer already exercised the combined code.
 5. **Make one layer ready at a time.** Only the lowest unmerged layer is marked ready and given auto-merge. Every later layer stays draft, even when its current checks are green.
 6. **Advance after merge.** When the lowest layer lands, refresh the next branch against the landed target, retarget its pull request to that target, and verify that the diff still contains only its intended change. Run CI and the automated review loop again before marking it ready.