git:20260714.3018958 to git:20260716.32be654

- <!-- markdownlint-disable MD024 -->

-

- # Agent Instructions

-

- <!-- bd-doctor-divergence: ok -->

- <!-- AGENTS.md and CLAUDE.md are intentionally distinct in this repo.

- CLAUDE.md = repository-specific guidance (build commands, conventions, marketplace layout).

- AGENTS.md = generic agent / beads session protocol.

- CLAUDE.md explicitly delegates session protocol here ("Session protocol lives in AGENTS.md"). -->

-

- This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.

-

- ---

-

- ## 🚨 MANDATORY: Session Continuation Protocol

-

- **CRITICAL**: When this session continues after context compaction/summarization:

-

- **YOU MUST IMMEDIATELY RUN**:

-

- ```bash

- bd ready

- ```

-

- **WHY**: After context loss, beads is your ONLY source of truth for:

-

- - What tasks are in progress

- - What was being worked on before context compaction

- - What's blocked/ready to work on

- - Project status and next steps

-

- **THIS IS NON-NEGOTIABLE**: Do NOT proceed with ANY work until you've run `bd ready`.

-

- **Failure to read beads after context compaction = working blind = wasted effort**

-

- ---

-

- ## Cross-session coordination

-

- This repo is often worked in **two Claude sessions at once** — one here, and one in the `intent-eval-platform` umbrella (that platform's CCPI validator, `jrig-cli`, and kernel reach into this repo). The two sessions are separate processes that share only the filesystem, so stay in sync on the shared surfaces:

-

- - **Shared journal — read on start, append on any cross-repo work.** `~/000-projects/CROSS-SESSION-LOG.md` (untracked, newest-first). One pipe line per action: `YYYY-MM-DD HH:MM UTC | repo/session | what | branch or PR# | status`. Append a line _before AND after_ touching anything the other session may also be in.

- - **Beads split rule — this is how cross-cutting work stays visible.** Marketplace-only work → **this repo's own beads** (`bd ready`, prefix `claude-code-plugins-*`). **Platform-touching / cross-cutting work → the UMBRELLA beads**, so the `intent-eval-platform` session sees it: `bd -C ~/000-projects ready` and `bd -C ~/000-projects create … --label cross-session` (view with `bd -C ~/000-projects list --label cross-session`) — **plus** a journal line. The two beads workspaces are separate dolt DBs; a cross-cutting task filed only in this repo's local beads is **invisible** to the umbrella session.

- - **Working-tree hazard — commit early or use a worktree.** This repo has ONE working tree; a concurrent session's `git checkout`/`reset` can wipe your **uncommitted** work (happened 2026-07-01). Commit early, or do multi-step file work in a `git worktree`.

-

- Full protocol (loaded by every session on this box): `/home/jeremy/CLAUDE.md` § "Cross-session coordination".

-

- ---

-

- ## Quick Reference

-

- ```bash

- bd ready # Find available work

- bd show <id> # View issue details

- bd update <id> --status in_progress # Claim work

- bd close <id> # Complete work

- bd sync # Sync with git

- ```

-

- ## Landing the Plane (Session Completion)

-

- **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.

-

- **MANDATORY WORKFLOW:**

-

- 1. **File issues for remaining work** - Create issues for anything that needs follow-up

- 2. **Run quality gates** (if code changed) - Tests, linters, builds

- 3. **Update issue status** - Close finished work, update in-progress items

- 4. **PUSH TO REMOTE** - This is MANDATORY:

-

- ```bash

- git pull --rebase

- bd sync

- git push

- git status # MUST show "up to date with origin"

- ```

-

- 5. **Clean up** - Clear stashes, prune remote branches

- 6. **Verify** - All changes committed AND pushed

- 7. **Hand off** - Provide context for next session

-

- **CRITICAL RULES:**

-

- - Work is NOT complete until `git push` succeeds

- - NEVER stop before pushing - that leaves work stranded locally

- - NEVER say "ready to push when you are" - YOU must push

- - If push fails, resolve and retry until it succeeds

-

- ---

-

- ## Before You Touch Validators, Schemas, or the Kernel Pin

-

- This repo is mid-migration toward a single source of truth for "what is a valid agent-native artifact." An agent working here must know the following before changing anything under `scripts/validate-*`, `package.json`'s kernel pin, or the schema docs.

-

- **The authoritative gate is `scripts/validate-skills-schema.py`.** It is the one in the branch-protection required-status set. At marketplace tier, a missing required field is an **ERROR, not a warning**. The IS 8-field `ALWAYS_REQUIRED` set is hand-authored and stays **AUTHORITATIVE**. The IS rubric sits on top of Anthropic's permissive spec — do not reduce the 8-field set, do not demote marketplace errors to warnings, do not "realign" to Anthropic's floor. Read `000-docs/SCHEMA_CHANGELOG.md` § NON-NEGOTIABLES first; any change to required-fields / tier model / error-vs-warning semantics is approval-gated there.

-

- **The kernel `@intentsolutions/core` (`schemas/authoring/v1` byte-frozen + `authoring/v2` strict fork) is the SSoT.** The validator is migrating to consume the kernel folds instead of its hand-rolled rule sets — that work is in progress and the advisory→authoritative flip has **not** happened.

-

- **Pin tracks the latest published kernel — exactly `0.9.0` (no `^`/`~`).** The `authoring/v1` family is byte-frozen across kernel versions, so the pin bump is a governance/coupling update, not an authority change. Keep it EXACT (no `^`/`~`); bump it deliberately when the kernel publishes a new latest, in a dedicated coupling PR. The advisory→authoritative flip is a SEPARATE, gated step — bumping the pin must never flip it.

-

- **Two advisory CI lanes — they never block:**

-

- - `kernel-shadow-validation.yml` (DR-049 shadow soak) runs the kernel-pinned schema over the SKILL.md corpus and logs AGREE/DISAGREE to `scripts/.kernel-shadow/report.json`.

- - `kernel-vendor-hash.yml` enforces the V ≤ C ≤ K version-coupling invariant + a ≤7-day staleness bound.

-

- Both are `continue-on-error: true`, are not required checks, and mutate nothing. Do not treat their output as a merge blocker, and do not "fix" them by bumping the pin.

-

- **Do NOT flip the shadow lane to blocking** until ALL hold: ≥99.5% corpus agreement (deterministic folds = 100%; the 0.5% band is non-deterministic surfaces only), ≥30 days of advisory soak, zero open P0 blockers, the Rekor superseding-event rollback protocol implemented and tested, CTO + CISO + VP-DevRel governance sign-off, and a ≥14-day public deprecation-window notice to affected authors. The soak has not met this bar yet — the open disagreements are real tool-safety / shell-substitution security cases the current validator correctly blocks. Promotion to blocking is a separate, later, condition-gated step, never a side effect of an unrelated change.

-

- **`[skip auto-bump]` for non-release PRs.** `auto-bump-on-pr.yml` auto-bumps changed plugins' patch versions (only on `plugins/**` / `packages/**` changes). For a docs-only or non-release PR, put `[skip auto-bump]` in the PR title or body so the auto-bumper steps aside.

-

- ---

-

- ## External Plugin Sync — mirror, don't curate

-

- 63 of the ~470 plugins here are externally synced (57 third-party sources + 6 of Jeremy's own repos, per `sources.yaml`); the other ~87% are in-repo Intent Solutions work. External contributors are a curated **minority augment**, not the core — the sync is a side-channel. The adopted model is **mirror by default · upstream improvements · never clobber**. An agent working under `plugins/` on a synced source, in `sources.yaml`, or on `scripts/sync-external.mjs` / `.github/workflows/sync-external.yml` must know the following.

-

- **A sync PR is mirror OUTPUT of a contributor's repo — do NOT hand-curate mirrored files.** For a normal (non-curated) source the contributor's own repo is the source of truth. `scripts/sync-external.mjs` mirrors its files into `plugins/` and `sync-external.yml` opens an automated PR for a human to review (historically ~1 of 10 sync PRs merges). If a mirrored plugin should meet our A-grade bar, **upstream the improvement** — open a friendly issue, then a PR, on the CONTRIBUTOR'S OWN repo. Once merged upstream, the mirror becomes A-grade naturally and the sync never reverts anything. Do NOT hold a divergent, clobber-prone local copy by editing the mirrored files in place.

-

- **NEVER remove a `curated: true` flag or edit a curated plugin's files to "improve" them.** A source marked `curated: true` in `sources.yaml` is **frozen**: the sync skips it entirely (no clone, no overwrite, no orphan-prune) and only keeps its catalog entry current, so even a `--force` sync cannot revert our edits. `tonone`, `servicegraph`, and `schedule-after-usage-reset` carry `curated: true` today; `hyperflow` does NOT — its frontmatter hardening merged upstream and the flag was deliberately dropped in #1008 (the completed off-ramp, not an accidental removal — do not "restore" it). Removing a live flag or hand-editing a curated plugin's files reintroduces the exact clobber this guard exists to stop — a prior `--force` run reverted ~100 A-graded agents to 3-field upstream stubs (the ~18.9k-line deletion that started this). Note `curated:` and `verified:` are **orthogonal**: `verified:` means a maintainer vetted the source's trust/quality; `curated:` means we locally hardened the plugin past upstream and the sync must not overwrite it. All three curated sources are `curated: true` but `verified: false` — an honest, intended state.

-

- **The sync keeps at most ONE open sync PR by design — do not reopen closed sync PRs.** `sync-external.yml` runs a "Close superseded sync PRs" step before Create-PR that closes older open `automation/sync-external-*` PRs (with `--delete-branch`). This prunes the pileup; it preserves the safe unique-per-run-branch model. A closed sync PR was superseded on purpose — the next scheduled or dispatched run reproduces the current mirror. Do not reopen one to "recover" it.

-

- **Any issue / PR / comment on a CONTRIBUTOR'S repo is drafted and shown to Jeremy for wording sign-off BEFORE posting.** Curated and long-time contributors are handled respectfully — a friendly ISSUE first ("we featured your plugin and hardened its frontmatter to our A-grade bar — would you be open to a PR upstreaming it?"), THEN a PR they own and merge. No surprise PRs; credit preserved; they decide. Keep the tone peer/contribute-back, never extractive or entitled.

-

- The decision record for this model is `000-docs/694-AT-DECR`; the earlier shared-branch clobber fix (the safe unique-per-run-branch model this step builds on) is `000-docs/691-AT-AUDT-sync-external-pipeline-audit-and-hardening.md`.

-

- ---

-

- ## Note to automated PR reviewers

-

- If you are an AI PR reviewer (Codex, Greptile, or similar), review against **this repo's specs**, not general priors or a web search:

-

- - **The deterministic gate is `scripts/validate-skills-schema.py`** plus the required CI checks. Ground any skill / plugin / agent frontmatter finding in the validator and `000-docs/SCHEMA_CHANGELOG.md` (the 8-field `ALWAYS_REQUIRED` set; at marketplace tier a missing required field is an ERROR, not a warning). If the validator would accept it, do not invent a frontmatter objection.

- - **A `sources.yaml` entry is a pointer**, validated at weekly-sync time by `sync-external.mjs --strict` plus the validator, not at PR time. Do **not** assert whether an upstream repo exists, is reachable, or has valid frontmatter from a web search; repo existence is time-sensitive and non-deterministic at review time. Phrase any upstream risk as "the sync will verify at clone time," never "the repo does not exist."

- - **Defer style** (naming, formatting, import order) to eslint / prettier / ruff / markdownlint / shellcheck. Prioritize correctness, security, and gate integrity.

- - **Never suggest weakening a gate** (a threshold, test, assertion, security check, or required field) unless the same PR replaces it with a stronger equivalent. See `CLAUDE.md` and `.greptile/rules.md`.

- <!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:7510c1e2 -->

- ## Beads Issue Tracker

- This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.

- ### Quick Reference

- bd ready # Find available work

- bd show <id> # View issue details

- bd update <id> --claim # Claim work

- bd close <id> # Complete work

- ### Rules

-

- - Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists

- - Run `bd prime` for detailed command reference and session close protocol

- - Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files

-

- **Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

-

- ## Session Completion

-

- **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.

- **MANDATORY WORKFLOW:**

- 1. **File issues for remaining work** - Create issues for anything that needs follow-up

- 2. **Run quality gates** (if code changed) - Tests, linters, builds

- 3. **Update issue status** - Close finished work, update in-progress items

- 4. **PUSH TO REMOTE** - This is MANDATORY:

- ```bash

- git pull --rebase

- git push

- git status # MUST show "up to date with origin"

- ```

- 5. **Clean up** - Clear stashes, prune remote branches

- 6. **Verify** - All changes committed AND pushed

- 7. **Hand off** - Provide context for next session

- **CRITICAL RULES:**

- - Work is NOT complete until `git push` succeeds

- - NEVER stop before pushing - that leaves work stranded locally

- - NEVER say "ready to push when you are" - YOU must push

- - If push fails, resolve and retry until it succeeds

- <!-- END BEADS INTEGRATION -->