@olegkoval/agent-skills 1.38.0 → 1.38.2

package/.github/prompts/context-repo.prompt.md

@@ -1,7 +1,7 @@
 <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
 
 ---
-description: "Bootstrap and maintain one private GitHub repository as the durable store for agent-produced context, creating it once with explicit consent and returning a verified receipt."
+description: "Resolve one private GitHub repository as the durable store for agent-produced context, searching the account for a store that already exists before ever offering to create one, and returning a verified receipt."
 ---
 
 Use the olko:context-repo skill.
@@ -21,7 +21,7 @@ Do not use this skill to read or write arbitrary GitHub repositories. It manages
 
 Pointer file, the single source of truth for whether a store has been resolved:
 
-```
+```text
 ${XDG_CONFIG_HOME:-$HOME/.config}/agent-context/config.json
 ```
 
@@ -41,39 +41,63 @@ A pointer in the refusal shape means the answer is already known. Do not prompt
 
 Clone location, fixed regardless of the resolved repo name:
 
-```
+```text
 ${XDG_DATA_HOME:-$HOME/.local/share}/agent-context/repo
 ```
 
-Repository tree, seeded on creation and extended by callers afterward:
+Repository tree. This is the layout of the store that already exists; a store created from scratch is seeded to match it:
 
-```
+```text
 README.md
+AGENTS.md
 .gitignore
-retros/<repo-slug>/<YYYY-MM-DD>-<window>.json
-retros/<repo-slug>/<YYYY-MM-DD>-<window>.md
-knowledge/<artifact-slug>/ledger.json
-knowledge/<artifact-slug>/page.html
+ledger.json
+retro/<run-id>-<scope-key>-<window>.md
+# Legacy stores may use retros/ instead of retro/.
 ```
 
-`README.md` states what the repository is, which skills write to it, that it is private, and its retention expectations (append-only, not pruned automatically). `retros/` and `knowledge/` start empty aside from a placeholder so git tracks the directories; callers create the dated or slugged subpaths they need.
+`ledger.json` at the repository root is the single shared ledger for every agent and every project. It is one file, not one per artifact: `{"name": ..., "version": ..., "notes": [...]}`, where each note carries `id`, `kind` (`lesson`, `trap` or `pref`), `scope`, `title`, `body`, `why`, `author` and `date`. Ids are `n<number>` or `c<number>` and are never reused. Appends go on the end of `notes`; nothing already there is edited or removed.
+
+`retro/` is flat and markdown only. Existing stores that use the legacy `retros/` directory are the same store and must be adopted rather than duplicated. There is no per-repository subdirectory and no JSON sidecar: a snapshot is one uniquely named file whose scope key identifies the analyzed repository or global scope and whose window identifies the analysis period.
+
+`README.md` states what the repository is, which skills write to it, that it is private, and its retention expectations (append-only, not pruned automatically). `AGENTS.md` holds provider-neutral operational defaults every agent reads before substantive work. It cannot relax this skill's safety invariants.
 
 ## Resolution order
 
-Evaluate these in order. Stop at the first one that applies. Steps 1 and 2 never prompt.
+Evaluate these in order. Stop at the first one that applies. Steps 1 and 2 never prompt. Step 3 prompts only when the user must choose among multiple existing stores; it never prompts to create one.
+
+Creating a store is the last resort, not the default. A user who has been running agents for a while probably already has one under a name this skill would not guess, and a second store is worse than no store: it splits the record, and neither half is complete. Search before you offer to create.
 
-**1. Pointer exists in the normal shape, clone exists, and `gh repo view <repo>` succeeds.**
-Return the existing repo and clone path as-is. Zero writes, zero prompts. This is the common case on a machine that already resolved the store.
+**1. Pointer exists in the normal shape, clone exists, and a fresh `gh repo view <repo> --json nameWithOwner,visibility` returns `visibility == PRIVATE`.**
+Return the existing repo and clone path as-is. Zero writes, zero prompts. This is the common case on a machine that already resolved the store. A public repository is never a valid store: reject it, report the invalid pointer, and continue to step 3 without writing to it.
 
-If `gh repo view <repo>` fails, distinguish why before deciding anything. A failure that names the repository as not found, or reports access denied, means the pointer is stale: report the stale state and fall through to step 3 to re-prompt, and never assume a stale pointer still means "yes." A failure caused by no network, a `gh` API outage, or a rate limit is not staleness. In that case keep the pointer and the existing clone, resolve as `READY` with the SHA read locally from `git -C <clone> rev-parse HEAD`, and report that the remote could not be reached. Never prompt to create a store that the pointer says already exists just because GitHub was unreachable, and never create a replacement repository on a failed read.
+If `gh repo view <repo>` fails, distinguish why before deciding anything. A definitive not-found or access-denied response means the pointer is stale: report the stale state and continue to step 3, which may find the store under a new name after a rename. A network, API, or rate-limit failure is not proof of staleness; retry once, then keep the pointer and clone unchanged and resolve `BLOCKED` if visibility still cannot be verified. Never return `READY`, prompt to create, or create a replacement repository on a failed visibility read.
 
-**2. Pointer exists in the normal shape, `gh repo view <repo>` succeeds, but the local clone directory is missing.**
-Re-clone silently into the fixed clone location. Report to the caller that a re-clone happened (this is expected the first time a given machine touches an already-resolved store). Zero prompts.
+**2. Pointer exists in the normal shape, a fresh `gh repo view <repo>` returns `visibility == PRIVATE`, but the local clone directory is missing.**
+Re-clone silently into the fixed clone location, then read back visibility again and return `READY` only while it remains `PRIVATE`. Report to the caller that a re-clone happened (this is expected the first time a given machine touches an already-resolved store). Reject public visibility. Zero prompts.
 
-**3. No pointer, or the pointer is in the refusal shape, or the pointer was found stale in step 1.**
-If the pointer is in the refusal shape, stop here: resolve to `LOCAL_ONLY` without prompting, and tell the caller the user previously declined. The one override: if the user has asked for the store in this run, explicitly and in their own words, treat that as consent already given, replace the refusal pointer, and continue to the preconditions below. A caller's need for the store is never such a request; only the user is.
+If the pointer is in the refusal shape, resolve to `LOCAL_ONLY` without prompting unless the user explicitly asks in their own words to resume store resolution. A caller's need for the store is not such a request. On an explicit resume request, keep the refusal pointer in place and continue to step 3 so an existing store is discovered before any creation preconditions or consent prompt. Replace the refusal pointer only after a store is adopted or created.
 
-Otherwise check preconditions before offering to create anything:
+**3. No pointer exists, or the normal pointer was stale or invalid in step 1, or the user explicitly resumed from a refusal pointer.**
+Before evaluating creation preconditions or offering to create anything, exhaustively list the user's private repositories and test every candidate for the layout, not for the name. The authenticated user's endpoint paginates until no next page remains:
+
+```bash
+gh api --paginate --method GET /user/repos \
+  -f per_page=100 -f visibility=private -f affiliation=owner \
+  --jq '.[] | [.name, .pushed_at] | @tsv'
+gh api 'repos/<owner>/<name>/git/trees/HEAD?recursive=1' -q '.tree[].path'
+```
+
+A repository is the store when its tree carries a root `ledger.json` **and** a `retro/` (or legacy `retros/`) directory. Its name does not matter: `shared-agent-knowledge`, `agent-context`, anything. Collect all matches before deciding. Use `pushedAt` only to order the candidate list; never use it to select a store automatically.
+
+Repository listing and tree probes are failure-aware. Retry a transient network, API, or rate-limit failure once. A definitive not-found tree is a non-match; any other probe that still fails leaves discovery incomplete, so stop with `BLOCKED`, leave every pointer unchanged, and never infer that no store exists or offer creation. Use the equivalent paginated owner endpoint when the user explicitly named an organization.
+
+If exactly one candidate matches, select it automatically. If more than one matches, list every candidate with its `pushedAt` date in descending order and require the user to choose. Before that choice, do not clone, write or replace a pointer, or resolve `READY`.
+
+For the selected candidate, freshly read `gh repo view <owner>/<name> --json nameWithOwner,visibility` and require `visibility == PRIVATE`; reject public visibility. Only after that check may this skill clone to the fixed location. Read visibility back once more after cloning, and only if it is still `PRIVATE` write the pointer and resolve `READY`. Report which repository was adopted and that nothing was created. Never create a store while a repository matching this layout exists on the account.
+
+**4. Step 3 completed successfully and found no existing store.**
+Only now check creation preconditions before offering to create anything:
 
 - `gh --version` must succeed.
 - `gh auth status` must succeed and the active account must carry the `repo` scope.
@@ -83,49 +107,50 @@ If either check fails, resolve to `BLOCKED` with the exact remedy `gh auth login
 If preconditions pass, ask once, in one message, before creating anything. State plainly:
 
 - **Owner**: the account from `gh api user -q .login`.
-- **Name**: the proposed repository name, default `agent-context`.
+- **Name**: the proposed repository name, default `shared-agent-knowledge`.
 - **Visibility**: private.
-- **Paths that will be written**: the pointer file path, the clone path, and the seeded tree (`README.md`, `.gitignore`, `retros/`, `knowledge/`).
+- **Paths that will be written**: the pointer file path, the clone path, and the seeded tree (`README.md`, `AGENTS.md`, `.gitignore`, `ledger.json`, `retro/`).
+- **That exhaustive step 3 found no existing store**, and which repositories were checked, so the user can correct you if they know of one you missed.
 - That nothing outside this one repository is touched: no other GitHub repository, no existing local files besides the two paths above.
 
 Offer exactly three answers:
 
-- `y`: proceed to step 4.
+- `y`: proceed to step 5.
 - `n`: do not create anything and do not write a pointer. Resolve this run as `LOCAL_ONLY`. Ask again next time a caller needs the store.
 - `never`: do not create anything. Write the refusal-shape pointer so future runs stop asking. Resolve this run as `LOCAL_ONLY`.
 
 **Name collision.** If `<owner>/<name>` already exists on GitHub:
 
-- If it already carries this layout (a `retros/` directory and a `knowledge/` directory at the repository root, and a `README.md` that identifies it as an agent context store), adopt it: skip creation, clone it, and proceed as if step 4 had just run.
-- Otherwise it is an unrelated repository. Never write into it. Offer `agent-context-2` (incrementing further only if that also collides) as the name and re-run the consent prompt with the new name.
+- If it already carries this layout (a root `ledger.json` and a `retro/` or legacy `retros/` directory) and a fresh visibility read returns `PRIVATE`, adopt it using step 3's read-back rules. Step 3 should normally have caught this already.
+- Otherwise it is an unrelated repository. Never write into it. Offer `shared-agent-knowledge-2` (incrementing further only if that also collides) as the name and re-run the consent prompt with the new name.
 
-**4. Create, seed, and push.**
-Only reached after explicit `y` consent (or an adopted existing repo with the right layout).
+**5. Create, seed, and push.**
+Only reached after explicit `y` consent, step 3 having found no existing store.
 
-```
+```bash
 gh repo create <owner>/<name> --private
 git clone https://github.com/<owner>/<name>.git <clone>
 ```
 
-Seed the tree inside `<clone>`: write `README.md`, `.gitignore`, and empty `retros/` and `knowledge/` directories (each holding a placeholder file so git tracks them). Then:
+Seed the tree inside `<clone>`: write `README.md`, `AGENTS.md`, `.gitignore`, a `ledger.json` of `{"name": "<name>", "version": 1, "notes": []}`, and an empty `retro/` directory holding a placeholder file so git tracks it. Then:
 
-```
+```bash
 git -C <clone> add -A
 git -C <clone> commit -m "chore: initialize agent context store"
 git -C <clone> push -u origin HEAD
 ```
 
-**5. Write the pointer, then verify from a fresh source.**
+**6. Write the pointer, then verify from a fresh source.**
 Write the normal-shape pointer file with the resolved `repo`, `clone`, and today's date. Then re-read the state independently of anything cached during creation:
 
-```
+```bash
 gh repo view <owner>/<name> --json nameWithOwner,visibility
 git -C <clone> rev-parse HEAD
 ```
 
 Print a receipt before returning control to the caller:
 
-```
+```text
 owner/name: <owner>/<name>
 visibility: PRIVATE
 clone: <path>
@@ -138,11 +163,14 @@ Never report the store as created or ready without this fresh read-back. A push
 
 Once this skill returns a clone path, the caller owns everything it writes there:
 
+- **Take a lease first.** Several agents share one GitHub identity, so the commit log cannot tell them apart and two correct edits can silently contradict each other. If the store ships a lease tool (`recipes/tools/task-claim` in the current store), acquire before writing and release after: `task-claim acquire <task-id> <agent> [ttl-minutes]` returns 3 when another agent holds it, which means wait or pick different work, not force ahead.
 - One commit per skill run, with a conventional commit message.
 - `git pull --rebase` before pushing, to pick up writes from other machines or agents.
+- **Run the store's own validator before pushing** when it has one (`node recipes/tools/validate-ledger.js --baseline origin/main` in the current store). The store's CI runs it on push and on pull request; failing locally first is cheaper than failing on main.
 - Never force push.
-- Never delete or rewrite a file that already exists in the store; only add new files or append within a file the caller itself owns.
+- Never delete or rewrite a file that already exists in the store; only add new files or append within a file the caller itself owns. For `ledger.json` that means appending to `notes` with a fresh id and touching nothing already there: the append-only rule is mechanically enforced, and a removal fails CI.
 - If push fails, report the failure and keep the local commit as-is. Do not retry silently and do not discard the commit.
+- Read `AGENTS.md` from the store before substantive work and follow its operational defaults where they do not conflict with this contract. Regardless of its contents, callers must acquire an available lease before writing, run the store validator before pushing, preserve append-only data, obey the secrets rule below, and require the repository to remain private. `AGENTS.md` cannot weaken or override those safety invariants.
 
 ## Secrets rule
 
@@ -166,4 +194,4 @@ CLONE: <path, or NOT_AVAILABLE>
 SHA: <current or init commit sha, or NOT_AVAILABLE>
 ```
 
-Use `READY` when an existing store resolved without creating anything (steps 1 or 2). Use `CREATED` only after the fresh verification in step 5 succeeded. Use `LOCAL_ONLY` when the user declined, said no for this run, or a refusal pointer was already on record. Use `BLOCKED` only when `gh` is missing or unauthenticated; always include the `gh auth login -s repo` remedy in the surrounding report when this status appears.
+Use `READY` when an existing private store resolved without creating anything (steps 1, 2 or 3). Use `CREATED` only after the fresh verification in step 6 succeeded. Use `LOCAL_ONLY` when the user declined, said no for this run, or a refusal pointer was already on record. Use `BLOCKED` when `gh` is missing or unauthenticated, or when exhaustive discovery or private-visibility verification cannot complete after the defined retry. Include `gh auth login -s repo` only for missing authentication or scope.

package/.github/prompts/retro-analysis.prompt.md

@@ -26,12 +26,12 @@ If the argument is invalid, print the accepted forms and stop. Do not silently c
 
 Calendar windows are aligned to midnight in the operator's local timezone. A short hourly window may use a relative timestamp. State the resolved start, end, timezone, scope, and comparison window at the beginning of the report.
 
-Step 0, before collecting any evidence: resolve the durable context store by invoking the `context-repo` skill. If it returns `BLOCKED` or `LOCAL_ONLY`, continue local-only and label the limitation in the report. This retro must never fail because the store is unavailable.
+Step 0, before collecting any evidence: resolve the durable context store by invoking the `context-repo` skill. If it returns `BLOCKED` or `LOCAL_ONLY`, continue local-only and label the limitation in the report. Resolving a store does not authorize writing a snapshot to it. This retro must never fail because the store is unavailable.
 
 ## Safety and evidence rules
 
-- Be read-only by default in the analyzed repository. The one named exception: this skill may invoke `context-repo` for a consented store bootstrap, and may make one snapshot commit and push per run into the context store only. Outside that exception, it never pushes, merges, deploys, closes issues, edits source, or rewrites history in the analyzed repository.
-- A retro may write one task-owned snapshot per run: to the context store's `retros/<repo-slug>/` when the store resolves, otherwise to `.context/retros/` when that directory exists or when persistence is explicitly requested. Never overwrite an existing snapshot; use a date and window-specific filename.
+- Be read-only by default in the analyzed repository. The named exceptions are a `context-repo` bootstrap performed under that skill's own consent flow, and one context-store snapshot commit and push when the user explicitly consented to remote snapshot persistence for this run or through a recorded standing workflow preference. Outside those exceptions, this skill never pushes, merges, deploys, closes issues, edits source, or rewrites history in the analyzed repository.
+- A retro may write one task-owned snapshot per run. Generate one collision-resistant run id and reuse it for the whole run, in the form `<YYYYMMDDTHHMMSSZ>-<short-unique-suffix>`. Derive one scope key: the normalized `<owner>-<repo>` slug in repository mode and the literal `global` in global mode, independent of which repositories were discovered or their order. The filename is `<run-id>-<scope-key>-<window>.md`. Write it to the context store's `retro/` only with explicit remote-persistence consent; otherwise use `.context/retros/` when that directory exists or local persistence was explicitly requested. Create the file only if absent and generate a new run id on collision; never overwrite an existing snapshot.
 - Do not fetch or refresh remote refs unless the user or the surrounding workflow authorized that read-side state change. If refs may be stale, say so and use the available evidence.
 - Preserve dirty work, untracked files, existing snapshots, credentials, and unrelated temporary artifacts.
 - Never infer delivery from a local commit. Treat local Git, remote/PR state, CI, deployment, and device or human QA as separate evidence gates.
@@ -47,7 +47,7 @@ For repository mode:
 2. Preserve and report pre-existing dirty paths; do not include their changes as delivered work unless the evidence links them to the window.
 3. Use the repository's local timezone for calendar boundaries. Use UTC timestamps in stored machine-readable data.
 4. Read only relevant project documentation and task artifacts needed to interpret the changes. Do not invent milestones, objectives, or acceptance criteria.
-5. Locate prior snapshots in the context store's `retros/<repo-slug>/` first, then in `.context/retros/`. Reading the store first is what makes `compare` and `global` work across machines instead of only where the last run happened. Load the immediately preceding comparable snapshot when available.
+5. Locate prior snapshots by the same scope key and window, newest run timestamp first: the context store's `retro/`, then its legacy `retros/`, then `.context/retros/`. For pre-run-id repository snapshots, fall back to matching the repository slug; never treat a repository snapshot as a global snapshot. Reading the store first is what makes `compare` and `global` work across machines instead of only where the last run happened. Load the immediately preceding comparable snapshot when available.
 
 For global mode:
 
@@ -55,6 +55,7 @@ For global mode:
 2. For each repository, collect the same bounded evidence as repository mode and skip missing, inaccessible, or non-Git directories.
 3. Optionally include available agent/session summaries or tool telemetry, but only as aggregate, redacted evidence. Do not require a specific agent vendor, plugin, or telemetry format.
 4. Keep per-project results separate before producing cross-project totals. Never hide a repository-level failure in an aggregate.
+5. Use the literal `global` scope key to locate the prior global snapshot with the same store-first ordering as repository mode. Never derive the lookup key from the discovered repository set or its order.
 
 ## 2. Collect raw evidence
 
@@ -142,7 +143,7 @@ For `compare` or any window with a prior snapshot:
 - preserve the same metric definitions between periods; do not compare a repository window to a global window as if they were equivalent
 - report streaks, recurring hotspots, repeated failure modes, and unresolved improvements only when snapshots support them
 
-Store a JSON snapshot with stable keys, UTC timestamps, resolved window, scope, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. If the store pointer resolved, write the snapshot to `<clone>/retros/<repo-slug>/<YYYY-MM-DD>-<window>.json` plus the matching `.md`, then commit and push per the `context-repo` caller contract. Otherwise fall back to `.context/retros/` exactly as today. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.
+Store a JSON snapshot with stable keys, the run id, UTC timestamps, resolved window, scope key, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. When the store pointer resolved and the user explicitly consented to remote snapshot persistence for this run or through a recorded standing workflow preference, create `<clone>/retro/<run-id>-<scope-key>-<window>.md`, with the machine-comparable JSON in a fenced block inside that file rather than as a separate sidecar, then commit and push per the `context-repo` caller contract, lease and validator included. Store resolution alone never authorizes the write, commit, or push. Without that consent, or when the store is unavailable, fall back to `.context/retros/` exactly as described above and do not modify the store. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.
 
 ## 5. Optionally promote durable lessons
 

package/.kiro/steering/context-repo.md

@@ -2,7 +2,7 @@
 
 ---
 inclusion: manual
-description: "Bootstrap and maintain one private GitHub repository as the durable store for agent-produced context, creating it once with explicit consent and returning a verified receipt."
+description: "Resolve one private GitHub repository as the durable store for agent-produced context, searching the account for a store that already exists before ever offering to create one, and returning a verified receipt."
 ---
 
 # Context Repo
@@ -20,7 +20,7 @@ Do not use this skill to read or write arbitrary GitHub repositories. It manages
 
 Pointer file, the single source of truth for whether a store has been resolved:
 
-```
+```text
 ${XDG_CONFIG_HOME:-$HOME/.config}/agent-context/config.json
 ```
 
@@ -40,39 +40,63 @@ A pointer in the refusal shape means the answer is already known. Do not prompt
 
 Clone location, fixed regardless of the resolved repo name:
 
-```
+```text
 ${XDG_DATA_HOME:-$HOME/.local/share}/agent-context/repo
 ```
 
-Repository tree, seeded on creation and extended by callers afterward:
+Repository tree. This is the layout of the store that already exists; a store created from scratch is seeded to match it:
 
-```
+```text
 README.md
+AGENTS.md
 .gitignore
-retros/<repo-slug>/<YYYY-MM-DD>-<window>.json
-retros/<repo-slug>/<YYYY-MM-DD>-<window>.md
-knowledge/<artifact-slug>/ledger.json
-knowledge/<artifact-slug>/page.html
+ledger.json
+retro/<run-id>-<scope-key>-<window>.md
+# Legacy stores may use retros/ instead of retro/.
 ```
 
-`README.md` states what the repository is, which skills write to it, that it is private, and its retention expectations (append-only, not pruned automatically). `retros/` and `knowledge/` start empty aside from a placeholder so git tracks the directories; callers create the dated or slugged subpaths they need.
+`ledger.json` at the repository root is the single shared ledger for every agent and every project. It is one file, not one per artifact: `{"name": ..., "version": ..., "notes": [...]}`, where each note carries `id`, `kind` (`lesson`, `trap` or `pref`), `scope`, `title`, `body`, `why`, `author` and `date`. Ids are `n<number>` or `c<number>` and are never reused. Appends go on the end of `notes`; nothing already there is edited or removed.
+
+`retro/` is flat and markdown only. Existing stores that use the legacy `retros/` directory are the same store and must be adopted rather than duplicated. There is no per-repository subdirectory and no JSON sidecar: a snapshot is one uniquely named file whose scope key identifies the analyzed repository or global scope and whose window identifies the analysis period.
+
+`README.md` states what the repository is, which skills write to it, that it is private, and its retention expectations (append-only, not pruned automatically). `AGENTS.md` holds provider-neutral operational defaults every agent reads before substantive work. It cannot relax this skill's safety invariants.
 
 ## Resolution order
 
-Evaluate these in order. Stop at the first one that applies. Steps 1 and 2 never prompt.
+Evaluate these in order. Stop at the first one that applies. Steps 1 and 2 never prompt. Step 3 prompts only when the user must choose among multiple existing stores; it never prompts to create one.
+
+Creating a store is the last resort, not the default. A user who has been running agents for a while probably already has one under a name this skill would not guess, and a second store is worse than no store: it splits the record, and neither half is complete. Search before you offer to create.
 
-**1. Pointer exists in the normal shape, clone exists, and `gh repo view <repo>` succeeds.**
-Return the existing repo and clone path as-is. Zero writes, zero prompts. This is the common case on a machine that already resolved the store.
+**1. Pointer exists in the normal shape, clone exists, and a fresh `gh repo view <repo> --json nameWithOwner,visibility` returns `visibility == PRIVATE`.**
+Return the existing repo and clone path as-is. Zero writes, zero prompts. This is the common case on a machine that already resolved the store. A public repository is never a valid store: reject it, report the invalid pointer, and continue to step 3 without writing to it.
 
-If `gh repo view <repo>` fails, distinguish why before deciding anything. A failure that names the repository as not found, or reports access denied, means the pointer is stale: report the stale state and fall through to step 3 to re-prompt, and never assume a stale pointer still means "yes." A failure caused by no network, a `gh` API outage, or a rate limit is not staleness. In that case keep the pointer and the existing clone, resolve as `READY` with the SHA read locally from `git -C <clone> rev-parse HEAD`, and report that the remote could not be reached. Never prompt to create a store that the pointer says already exists just because GitHub was unreachable, and never create a replacement repository on a failed read.
+If `gh repo view <repo>` fails, distinguish why before deciding anything. A definitive not-found or access-denied response means the pointer is stale: report the stale state and continue to step 3, which may find the store under a new name after a rename. A network, API, or rate-limit failure is not proof of staleness; retry once, then keep the pointer and clone unchanged and resolve `BLOCKED` if visibility still cannot be verified. Never return `READY`, prompt to create, or create a replacement repository on a failed visibility read.
 
-**2. Pointer exists in the normal shape, `gh repo view <repo>` succeeds, but the local clone directory is missing.**
-Re-clone silently into the fixed clone location. Report to the caller that a re-clone happened (this is expected the first time a given machine touches an already-resolved store). Zero prompts.
+**2. Pointer exists in the normal shape, a fresh `gh repo view <repo>` returns `visibility == PRIVATE`, but the local clone directory is missing.**
+Re-clone silently into the fixed clone location, then read back visibility again and return `READY` only while it remains `PRIVATE`. Report to the caller that a re-clone happened (this is expected the first time a given machine touches an already-resolved store). Reject public visibility. Zero prompts.
 
-**3. No pointer, or the pointer is in the refusal shape, or the pointer was found stale in step 1.**
-If the pointer is in the refusal shape, stop here: resolve to `LOCAL_ONLY` without prompting, and tell the caller the user previously declined. The one override: if the user has asked for the store in this run, explicitly and in their own words, treat that as consent already given, replace the refusal pointer, and continue to the preconditions below. A caller's need for the store is never such a request; only the user is.
+If the pointer is in the refusal shape, resolve to `LOCAL_ONLY` without prompting unless the user explicitly asks in their own words to resume store resolution. A caller's need for the store is not such a request. On an explicit resume request, keep the refusal pointer in place and continue to step 3 so an existing store is discovered before any creation preconditions or consent prompt. Replace the refusal pointer only after a store is adopted or created.
 
-Otherwise check preconditions before offering to create anything:
+**3. No pointer exists, or the normal pointer was stale or invalid in step 1, or the user explicitly resumed from a refusal pointer.**
+Before evaluating creation preconditions or offering to create anything, exhaustively list the user's private repositories and test every candidate for the layout, not for the name. The authenticated user's endpoint paginates until no next page remains:
+
+```bash
+gh api --paginate --method GET /user/repos \
+  -f per_page=100 -f visibility=private -f affiliation=owner \
+  --jq '.[] | [.name, .pushed_at] | @tsv'
+gh api 'repos/<owner>/<name>/git/trees/HEAD?recursive=1' -q '.tree[].path'
+```
+
+A repository is the store when its tree carries a root `ledger.json` **and** a `retro/` (or legacy `retros/`) directory. Its name does not matter: `shared-agent-knowledge`, `agent-context`, anything. Collect all matches before deciding. Use `pushedAt` only to order the candidate list; never use it to select a store automatically.
+
+Repository listing and tree probes are failure-aware. Retry a transient network, API, or rate-limit failure once. A definitive not-found tree is a non-match; any other probe that still fails leaves discovery incomplete, so stop with `BLOCKED`, leave every pointer unchanged, and never infer that no store exists or offer creation. Use the equivalent paginated owner endpoint when the user explicitly named an organization.
+
+If exactly one candidate matches, select it automatically. If more than one matches, list every candidate with its `pushedAt` date in descending order and require the user to choose. Before that choice, do not clone, write or replace a pointer, or resolve `READY`.
+
+For the selected candidate, freshly read `gh repo view <owner>/<name> --json nameWithOwner,visibility` and require `visibility == PRIVATE`; reject public visibility. Only after that check may this skill clone to the fixed location. Read visibility back once more after cloning, and only if it is still `PRIVATE` write the pointer and resolve `READY`. Report which repository was adopted and that nothing was created. Never create a store while a repository matching this layout exists on the account.
+
+**4. Step 3 completed successfully and found no existing store.**
+Only now check creation preconditions before offering to create anything:
 
 - `gh --version` must succeed.
 - `gh auth status` must succeed and the active account must carry the `repo` scope.
@@ -82,49 +106,50 @@ If either check fails, resolve to `BLOCKED` with the exact remedy `gh auth login
 If preconditions pass, ask once, in one message, before creating anything. State plainly:
 
 - **Owner**: the account from `gh api user -q .login`.
-- **Name**: the proposed repository name, default `agent-context`.
+- **Name**: the proposed repository name, default `shared-agent-knowledge`.
 - **Visibility**: private.
-- **Paths that will be written**: the pointer file path, the clone path, and the seeded tree (`README.md`, `.gitignore`, `retros/`, `knowledge/`).
+- **Paths that will be written**: the pointer file path, the clone path, and the seeded tree (`README.md`, `AGENTS.md`, `.gitignore`, `ledger.json`, `retro/`).
+- **That exhaustive step 3 found no existing store**, and which repositories were checked, so the user can correct you if they know of one you missed.
 - That nothing outside this one repository is touched: no other GitHub repository, no existing local files besides the two paths above.
 
 Offer exactly three answers:
 
-- `y`: proceed to step 4.
+- `y`: proceed to step 5.
 - `n`: do not create anything and do not write a pointer. Resolve this run as `LOCAL_ONLY`. Ask again next time a caller needs the store.
 - `never`: do not create anything. Write the refusal-shape pointer so future runs stop asking. Resolve this run as `LOCAL_ONLY`.
 
 **Name collision.** If `<owner>/<name>` already exists on GitHub:
 
-- If it already carries this layout (a `retros/` directory and a `knowledge/` directory at the repository root, and a `README.md` that identifies it as an agent context store), adopt it: skip creation, clone it, and proceed as if step 4 had just run.
-- Otherwise it is an unrelated repository. Never write into it. Offer `agent-context-2` (incrementing further only if that also collides) as the name and re-run the consent prompt with the new name.
+- If it already carries this layout (a root `ledger.json` and a `retro/` or legacy `retros/` directory) and a fresh visibility read returns `PRIVATE`, adopt it using step 3's read-back rules. Step 3 should normally have caught this already.
+- Otherwise it is an unrelated repository. Never write into it. Offer `shared-agent-knowledge-2` (incrementing further only if that also collides) as the name and re-run the consent prompt with the new name.
 
-**4. Create, seed, and push.**
-Only reached after explicit `y` consent (or an adopted existing repo with the right layout).
+**5. Create, seed, and push.**
+Only reached after explicit `y` consent, step 3 having found no existing store.
 
-```
+```bash
 gh repo create <owner>/<name> --private
 git clone https://github.com/<owner>/<name>.git <clone>
 ```
 
-Seed the tree inside `<clone>`: write `README.md`, `.gitignore`, and empty `retros/` and `knowledge/` directories (each holding a placeholder file so git tracks them). Then:
+Seed the tree inside `<clone>`: write `README.md`, `AGENTS.md`, `.gitignore`, a `ledger.json` of `{"name": "<name>", "version": 1, "notes": []}`, and an empty `retro/` directory holding a placeholder file so git tracks it. Then:
 
-```
+```bash
 git -C <clone> add -A
 git -C <clone> commit -m "chore: initialize agent context store"
 git -C <clone> push -u origin HEAD
 ```
 
-**5. Write the pointer, then verify from a fresh source.**
+**6. Write the pointer, then verify from a fresh source.**
 Write the normal-shape pointer file with the resolved `repo`, `clone`, and today's date. Then re-read the state independently of anything cached during creation:
 
-```
+```bash
 gh repo view <owner>/<name> --json nameWithOwner,visibility
 git -C <clone> rev-parse HEAD
 ```
 
 Print a receipt before returning control to the caller:
 
-```
+```text
 owner/name: <owner>/<name>
 visibility: PRIVATE
 clone: <path>
@@ -137,11 +162,14 @@ Never report the store as created or ready without this fresh read-back. A push
 
 Once this skill returns a clone path, the caller owns everything it writes there:
 
+- **Take a lease first.** Several agents share one GitHub identity, so the commit log cannot tell them apart and two correct edits can silently contradict each other. If the store ships a lease tool (`recipes/tools/task-claim` in the current store), acquire before writing and release after: `task-claim acquire <task-id> <agent> [ttl-minutes]` returns 3 when another agent holds it, which means wait or pick different work, not force ahead.
 - One commit per skill run, with a conventional commit message.
 - `git pull --rebase` before pushing, to pick up writes from other machines or agents.
+- **Run the store's own validator before pushing** when it has one (`node recipes/tools/validate-ledger.js --baseline origin/main` in the current store). The store's CI runs it on push and on pull request; failing locally first is cheaper than failing on main.
 - Never force push.
-- Never delete or rewrite a file that already exists in the store; only add new files or append within a file the caller itself owns.
+- Never delete or rewrite a file that already exists in the store; only add new files or append within a file the caller itself owns. For `ledger.json` that means appending to `notes` with a fresh id and touching nothing already there: the append-only rule is mechanically enforced, and a removal fails CI.
 - If push fails, report the failure and keep the local commit as-is. Do not retry silently and do not discard the commit.
+- Read `AGENTS.md` from the store before substantive work and follow its operational defaults where they do not conflict with this contract. Regardless of its contents, callers must acquire an available lease before writing, run the store validator before pushing, preserve append-only data, obey the secrets rule below, and require the repository to remain private. `AGENTS.md` cannot weaken or override those safety invariants.
 
 ## Secrets rule
 
@@ -165,4 +193,4 @@ CLONE: <path, or NOT_AVAILABLE>
 SHA: <current or init commit sha, or NOT_AVAILABLE>
 ```
 
-Use `READY` when an existing store resolved without creating anything (steps 1 or 2). Use `CREATED` only after the fresh verification in step 5 succeeded. Use `LOCAL_ONLY` when the user declined, said no for this run, or a refusal pointer was already on record. Use `BLOCKED` only when `gh` is missing or unauthenticated; always include the `gh auth login -s repo` remedy in the surrounding report when this status appears.
+Use `READY` when an existing private store resolved without creating anything (steps 1, 2 or 3). Use `CREATED` only after the fresh verification in step 6 succeeded. Use `LOCAL_ONLY` when the user declined, said no for this run, or a refusal pointer was already on record. Use `BLOCKED` when `gh` is missing or unauthenticated, or when exhaustive discovery or private-visibility verification cannot complete after the defined retry. Include `gh auth login -s repo` only for missing authentication or scope.

package/.kiro/steering/retro-analysis.md

@@ -25,12 +25,12 @@ If the argument is invalid, print the accepted forms and stop. Do not silently c
 
 Calendar windows are aligned to midnight in the operator's local timezone. A short hourly window may use a relative timestamp. State the resolved start, end, timezone, scope, and comparison window at the beginning of the report.
 
-Step 0, before collecting any evidence: resolve the durable context store by invoking the `context-repo` skill. If it returns `BLOCKED` or `LOCAL_ONLY`, continue local-only and label the limitation in the report. This retro must never fail because the store is unavailable.
+Step 0, before collecting any evidence: resolve the durable context store by invoking the `context-repo` skill. If it returns `BLOCKED` or `LOCAL_ONLY`, continue local-only and label the limitation in the report. Resolving a store does not authorize writing a snapshot to it. This retro must never fail because the store is unavailable.
 
 ## Safety and evidence rules
 
-- Be read-only by default in the analyzed repository. The one named exception: this skill may invoke `context-repo` for a consented store bootstrap, and may make one snapshot commit and push per run into the context store only. Outside that exception, it never pushes, merges, deploys, closes issues, edits source, or rewrites history in the analyzed repository.
-- A retro may write one task-owned snapshot per run: to the context store's `retros/<repo-slug>/` when the store resolves, otherwise to `.context/retros/` when that directory exists or when persistence is explicitly requested. Never overwrite an existing snapshot; use a date and window-specific filename.
+- Be read-only by default in the analyzed repository. The named exceptions are a `context-repo` bootstrap performed under that skill's own consent flow, and one context-store snapshot commit and push when the user explicitly consented to remote snapshot persistence for this run or through a recorded standing workflow preference. Outside those exceptions, this skill never pushes, merges, deploys, closes issues, edits source, or rewrites history in the analyzed repository.
+- A retro may write one task-owned snapshot per run. Generate one collision-resistant run id and reuse it for the whole run, in the form `<YYYYMMDDTHHMMSSZ>-<short-unique-suffix>`. Derive one scope key: the normalized `<owner>-<repo>` slug in repository mode and the literal `global` in global mode, independent of which repositories were discovered or their order. The filename is `<run-id>-<scope-key>-<window>.md`. Write it to the context store's `retro/` only with explicit remote-persistence consent; otherwise use `.context/retros/` when that directory exists or local persistence was explicitly requested. Create the file only if absent and generate a new run id on collision; never overwrite an existing snapshot.
 - Do not fetch or refresh remote refs unless the user or the surrounding workflow authorized that read-side state change. If refs may be stale, say so and use the available evidence.
 - Preserve dirty work, untracked files, existing snapshots, credentials, and unrelated temporary artifacts.
 - Never infer delivery from a local commit. Treat local Git, remote/PR state, CI, deployment, and device or human QA as separate evidence gates.
@@ -46,7 +46,7 @@ For repository mode:
 2. Preserve and report pre-existing dirty paths; do not include their changes as delivered work unless the evidence links them to the window.
 3. Use the repository's local timezone for calendar boundaries. Use UTC timestamps in stored machine-readable data.
 4. Read only relevant project documentation and task artifacts needed to interpret the changes. Do not invent milestones, objectives, or acceptance criteria.
-5. Locate prior snapshots in the context store's `retros/<repo-slug>/` first, then in `.context/retros/`. Reading the store first is what makes `compare` and `global` work across machines instead of only where the last run happened. Load the immediately preceding comparable snapshot when available.
+5. Locate prior snapshots by the same scope key and window, newest run timestamp first: the context store's `retro/`, then its legacy `retros/`, then `.context/retros/`. For pre-run-id repository snapshots, fall back to matching the repository slug; never treat a repository snapshot as a global snapshot. Reading the store first is what makes `compare` and `global` work across machines instead of only where the last run happened. Load the immediately preceding comparable snapshot when available.
 
 For global mode:
 
@@ -54,6 +54,7 @@ For global mode:
 2. For each repository, collect the same bounded evidence as repository mode and skip missing, inaccessible, or non-Git directories.
 3. Optionally include available agent/session summaries or tool telemetry, but only as aggregate, redacted evidence. Do not require a specific agent vendor, plugin, or telemetry format.
 4. Keep per-project results separate before producing cross-project totals. Never hide a repository-level failure in an aggregate.
+5. Use the literal `global` scope key to locate the prior global snapshot with the same store-first ordering as repository mode. Never derive the lookup key from the discovered repository set or its order.
 
 ## 2. Collect raw evidence
 
@@ -141,7 +142,7 @@ For `compare` or any window with a prior snapshot:
 - preserve the same metric definitions between periods; do not compare a repository window to a global window as if they were equivalent
 - report streaks, recurring hotspots, repeated failure modes, and unresolved improvements only when snapshots support them
 
-Store a JSON snapshot with stable keys, UTC timestamps, resolved window, scope, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. If the store pointer resolved, write the snapshot to `<clone>/retros/<repo-slug>/<YYYY-MM-DD>-<window>.json` plus the matching `.md`, then commit and push per the `context-repo` caller contract. Otherwise fall back to `.context/retros/` exactly as today. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.
+Store a JSON snapshot with stable keys, the run id, UTC timestamps, resolved window, scope key, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. When the store pointer resolved and the user explicitly consented to remote snapshot persistence for this run or through a recorded standing workflow preference, create `<clone>/retro/<run-id>-<scope-key>-<window>.md`, with the machine-comparable JSON in a fenced block inside that file rather than as a separate sidecar, then commit and push per the `context-repo` caller contract, lease and validator included. Store resolution alone never authorizes the write, commit, or push. Without that consent, or when the store is unavailable, fall back to `.context/retros/` exactly as described above and do not modify the store. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.
 
 ## 5. Optionally promote durable lessons