agile-ledger-workspace

Agile-Ledger Workspace (the ledger repo)

The layer that owns where the ledger lives. Since v2.0 that is a dedicated ledger repository holding one folder per code repo:

<workspace-root>/                 e.g. ~/Projetos/
├── agile-ledger/                 ← THE LEDGER REPO — its own git repo, pushed like any other
│   ├── Registry.md               # the marker + the map: repo slug ↔ code path ↔ remote ↔ sync state
│   ├── Config.md                 # org, clone target, filters, commit/push policy, default repo
│   ├── repo-a/                   # the eight ledger files for repo-a
│   └── repo-b/
└── repo-a/ · repo-b/             ← the code repos, with NO ledger files in them

Why this shape. The PM layer changes on the PM's clock, many times a day; the code changes on the developers' clock. Keeping the ledger out of the code repo means a backlog edit never reaches a developer's working branch, nobody rebases or pulls to receive bookkeeping, and the whole portfolio is readable — and diffable — in one place. One repo to clone, one place to look, one history of PM decisions (ledger(repo-a): …).

The agile-ledger skill holds the PM rules and writes inside a repo folder. This skill decides which folder that is, keeps Registry.md true, and talks to the network.

Golden safety rules (never violate)

These are stricter than the per-repo skill because this layer touches the network, the filesystem, and two git repos at once:

• Ledger files never go into a code repo. The ledger repo is the only home. A command that would write Markdown into a project's working tree is wrong — the one exception is /migrate-ledger removing a legacy folder, on a branch, after confirmation.
• Registry.md is the map, not the truth about work. Each repo folder's own files are authoritative for that project's backlog, sprint, and releases.
• Discovery uses your existing gh auth. Run gh repo list <org> … (read-only). Never request, read, store, or handle tokens or credentials. If gh is not authenticated, say so and stop.
• Cloning downloads code → always propose and wait. List the repos that would be cloned and wait for explicit confirmation before any git clone. No hands-off cloning.
• Never push, open a PR, or merge without confirmation — in either repo. ledger_commit may commit in the ledger repo; ledger_push is off by default and every push is confirmed when it happens. Changes in a code repo stay local on a branch and the user pushes.
• Reconstructed work is always a proposal, never truth. Epics/stories mined from git land only in the target repo folder's 💡 Inbox (Ideas.md) as drafts flagged 🔍 reconstructed from git — needs review. Never write acceptance criteria, estimates, or a Ready/Delivered state from inference. Never invent the "so that…". Never overwrite anything a human wrote.
• Sweeps are read-only by default. Every state-changing action (clone, register, draft, commit) is surfaced and confirmed, then performed — not assumed.
• Never delete rows from the Registry; mark them archived/gone instead.
• Migration copies before it removes. Verify the files landed in the ledger repo (and are committed) before offering to delete anything from a code repo.