@vegastack/skills 0.5.0 → 0.7.0

package/skill/dev-setup/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: dev-setup
+description: Bootstrap a project for issue-driven agent development. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", or invoked as dev-setup; also run automatically when dev-intake, dev-implement, or dev-ship find no .vegastack/dev.md in the project. Creates the project profile, the AGENTS.md dev section plus CLAUDE.md import, the five workflow labels on the GitHub repo, and the decision register. Not for architecture profiles or advice (that is architect and .vegastack/arch.md), not for authoring skills, not for repos without git.
+---
+
+# dev-setup
+
+Re-runnable bootstrap that gives a project everything the dev workflow needs: a profile file holding the knobs, a thin AGENTS.md section that both Claude Code and Codex read, the GitHub labels, and the decision register. The other dev skills call this automatically when `.vegastack/dev.md` is missing, then continue with their original request.
+
+Nearest neighbor: `architect` owns `.vegastack/arch.md` (architecture facts and advice); dev-setup owns `.vegastack/dev.md` (workflow facts and knobs). When arch.md exists, point dev.md at it for stack facts instead of duplicating them.
+
+## Step 1 — Detect before asking
+
+Facts are your job; decisions are the user's. Gather these silently and present findings as "here's what I found — correct me if wrong", never as open questions:
+
+| What | How |
+|---|---|
+| repo, default branch | `git remote get-url origin` · `gh repo view --json nameWithOwner,defaultBranchRef` |
+| gh authenticated | `gh auth status` |
+| stack and commands | package.json scripts, lockfiles, framework configs |
+| web app (UI evidence relevant) | framework dependencies (next, react, vue, …) |
+| existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, `.vegastack/arch.md`, docs/decisions.md |
+| existing labels | `gh label list` |
+
+Not a git repo, or no origin remote: stop and say exactly what is missing. A half-installed workflow is worse than none.
+
+## Step 2 — The interview
+
+Ask with your harness's question tool — AskUserQuestion in Claude Code, `request_user_input` in Codex where the mode allows it (availability details: [harness-facts](references/harness-facts.md)). When no question tool is available (headless run, gated mode), write the defaults, mark every unconfirmed knob `# TODO confirm`, and say so in your reply — a wrong invented preference costs more than a TODO.
+
+**Round A — confirm the detected facts** in one compact summary (repo, stack, commands, web app or not). Ask only about what detection could not fill.
+
+**Round B — the four workflow knobs**, recommended default first:
+
+1. Review of finished work: **subagent** · cross-agent (Codex↔Claude) · cross-agent only on `risky` issues
+2. Proof for UI work: **playwright screenshots** · none
+3. Gates: **3** (approve → PR → merge as separate user words) · 2 (approve → one "ship it" covers PR and merge)
+4. Tests: **required for every change** · required for logic changes only
+
+**Round C — only when the situation exists:**
+
+- AGENTS.md already has content → append the marked section (default) or show a merge proposal first
+- CLAUDE.md already has content → add the `@AGENTS.md` import as its first line (default) or move its content into AGENTS.md and leave only the import
+- Evidence repo for UI screenshots → default `<owner>/dev-review-assets`; offer to create it (`gh repo create --private`) if missing
+- Different label names or a different decision-register path, if the user brings it up
+
+Everything else — merge style, branch naming, the stop-and-ask list — takes its documented default straight into dev.md. The profile is plain text the user can edit anytime; the interview is a convenience, not the source of truth.
+
+## Step 3 — Write
+
+| Target | Action |
+|---|---|
+| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers |
+| `AGENTS.md` | create it, or insert/replace only the block between `<!-- vsk-dev:start -->` and `<!-- vsk-dev:end -->` using the [agents-section template](assets/agents-section.md.template); content outside the markers is the user's and stays untouched |
+| `CLAUDE.md` | ensure its first line is `@AGENTS.md` — Claude Code does not read AGENTS.md natively and needs this import ([harness-facts](references/harness-facts.md)); create the file when absent |
+| labels | `gh label create <name> --color <hex> --description "<text>"`, skipping ones that exist: `needs-you` FBCA04 (waiting on the user) · `ready` 0E8A16 (approved, agent may start) · `working` 1D76DB (claimed by an agent) · `for-you` 5319E7 (result awaiting user review) · `risky` B60205 (security, money, data, or production) |
+| decision register | create the file the `decisions:` knob names (default `docs/decisions.md`) with a two-line header and one example entry, when missing; a project with an existing register keeps it and the knob points there |
+
+## Step 4 — Report
+
+One summary: what was created, what was skipped and why, what remains TODO. When `gh` was unauthenticated, print the exact `gh auth login` and `gh label create` commands the user can run later, and name the gap plainly.
+
+## Re-runs
+
+Re-running is safe and is how knobs get revisited: show what differs per target and change only what the user confirms. The marked block is the only part of AGENTS.md this skill owns. Hand edits inside dev.md win — read them and keep them; the templates are for creation, not for resetting.

package/skill/dev-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-setup"
+  short_description: "Bootstrap a repo for the issue-driven dev workflow"
+  default_prompt: "Use $dev-setup to bootstrap this project's dev workflow."

package/skill/dev-setup/assets/agents-section.md.template

@@ -0,0 +1,9 @@
+<!-- vsk-dev:start -->
+## Dev workflow
+
+Read `.vegastack/dev.md` for this project's stack, commands, and workflow knobs.
+
+Work flows through GitHub issues. An issue labeled `ready` carries the user's recorded approval and a complete brief — implement it end to end per the `dev-implement` skill, post the evidence in the issue, and hand it back with `for-you`. Start only on `ready` issues. These five labels are the whole workflow vocabulary — use them and no others: `needs-you` (waiting on the user) → `ready` (approved) → `working` (claimed by an agent) → `for-you` (result awaiting user review); `risky` flags security, money, data, or production work.
+
+The user holds the gates: they approve the issue, say the word for a PR, and say a separate word to merge (see `gates` in dev.md). Material decisions get one dated line in the decision register dev.md names (`decisions:` knob).
+<!-- vsk-dev:end -->

package/skill/dev-setup/assets/dev-profile.md.template

@@ -0,0 +1,24 @@
+# Dev profile — {{owner/repo}}
+
+repo: {{owner/repo}} · default branch {{branch}}
+stack: {{one line, or "see .vegastack/arch.md"}}
+commands: test `{{test}}` · build `{{build}}` · dev `{{dev}}`
+
+## Knobs
+
+review: subagent            # subagent | cross-agent | cross-agent-risky
+ui-evidence: playwright     # playwright | none
+evidence-repo: {{owner}}/dev-review-assets
+gates: 3                    # 3 = approve/PR/merge · 2 = approve/ship
+tests: required             # required | logic-only
+merge: squash
+branch: <type>/<issue>-<slug>   # type: feat | fix | docs | chore | refactor
+decisions: docs/decisions.md
+
+## Stop and ask
+
+Dark execution ends and the user decides when work would involve: a change of scope or product behavior, a significant new dependency or runtime, spending money, anything destructive or touching production, or a blocker the brief cannot resolve.
+
+## Project rules
+
+- {{project-specific rules, one per line; delete this section if none}}

package/skill/dev-setup/references/harness-facts.md

@@ -0,0 +1,22 @@
+# Harness facts
+
+Verified mechanics of the two harnesses this workflow targets. Everything here is volatile — vendors change these — so each claim carries its source; the refresh contract tracks them. Verified 2026-08-27.
+
+## Claude Code
+
+- Claude Code does **not** read AGENTS.md natively. The documented pattern is a CLAUDE.md that imports it: a line containing `@AGENTS.md` (import syntax is `@path/to/file`, resolved relative to the containing file, maximum 4 hops of recursion; `@` inside backticks stays literal). <!-- source: CC-MEMORY -->
+- `CLAUDE.local.md` in the project root loads after CLAUDE.md and is meant to be gitignored — leave it alone; it is the user's personal file. <!-- source: CC-MEMORY -->
+- Project skills load from `.claude/skills/<name>/SKILL.md`; personal skills from `~/.claude/skills/`. <!-- source: CC-SKILLS -->
+- The structured question tool is **AskUserQuestion**. It is unavailable in non-interactive runs (`claude -p`); a configurable timeout can auto-submit pre-selected options. <!-- source: CC-TOOLS -->
+
+## Codex
+
+- Codex reads AGENTS.md natively: from `~/.codex/` (global; `AGENTS.override.md` wins over `AGENTS.md`), then from the repo root down to the working directory, one file per directory, concatenated root-first so closer files override. Combined size is capped by `project_doc_max_bytes`, default 32 KiB. There is **no** `@file` import mechanism — layering is directory-based only. <!-- source: CODEX-AGENTS -->
+- Skills load from `.agents/skills/` in each directory from the working directory up to the repo root, plus `~/.agents/skills/` for the user. Frontmatter requires only `name` and `description`; an optional `agents/openai.yaml` adds display metadata and invocation policy. <!-- source: CODEX-SKILLS -->
+- The structured question tool is **`request_user_input`** — collaboration-mode-gated (available in Plan mode; elsewhere it fails fast with a clear error, and it is not available to subagents). Community posts mention an "ask_user_question"/"clarify" tool; that is a proposal, not a shipped tool — do not design against it. <!-- source: CODEX-SKILLS -->
+- Non-interactive mode is `codex exec`: fully unattended, human-input tools unavailable, AGENTS.md discovery unchanged. <!-- source: CODEX-EXEC -->
+
+## What this means for the dev skills
+
+- AGENTS.md is the shared instruction file; the one-line CLAUDE.md import makes it reach Claude Code. Keep the marked section small — it counts against Codex's 32 KiB budget along with everything else in AGENTS.md.
+- Any skill that wants to ask the user must degrade cleanly: no question tool available → use documented defaults, mark them `# TODO confirm`, and say so.

package/skill/dev-setup/refresh/REFRESH.md

@@ -0,0 +1,13 @@
+# Refresh contract — dev-setup
+
+Instructions for the scheduled refresh agent (and any human running a manual refresh). This file plus `sources.json` is the complete freshness contract for this skill.
+
+## What this skill claims
+
+- **Durable rules** (SKILL.md, assets): the detect-then-ask discipline, the interview rounds and knobs, the marked-section AGENTS.md contract, the label set, the defaults-plus-TODO fallback. Versionless; the refresh agent NEVER edits these — if evidence invalidates one, open an issue quoting it.
+- **Volatile facts**: everything in `references/harness-facts.md` — Claude Code memory/import/skill/question-tool mechanics and Codex AGENTS.md/skills/question-tool/exec mechanics. That file is the only refresh-tracked file; its sentences carry `<!-- source: SOURCE-ID -->` markers matching the registry.
+
+## How to refresh
+
+1. Run the shared runner against this registry; on drift, read the changed page and propose edits to the marked sentences in `references/harness-facts.md` — and to the three harness-mechanism mentions in SKILL.md that mirror it (the two question tools in Step 2, the `@AGENTS.md` import in Step 3) — in the same PR as the registry update.
+2. Never auto-apply harness behavior changes; a human reviews — these facts change what dev-setup writes into user projects.

package/skill/dev-setup/refresh/sources.json

@@ -0,0 +1,152 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-27",
+  "policy": {
+    "criticalTopics": [
+      "claude-code-memory",
+      "codex-agents-md"
+    ],
+    "defaultChecksumScope": "html-text-v1",
+    "offline": "Use cached metadata only; fail closed when a critical entry is missing or older than thresholdDays.",
+    "drift": "Any drift requires reading the changed page and a human-reviewed PR updating references/harness-facts.md; never auto-apply.",
+    "copyright": "Store claim metadata, URLs, hashes, and concise excerpts only; never archive third-party documentation corpora.",
+    "cadence": "weekly scheduled-agent refresh; thresholdDays must be >= 14 (2x cadence) so a single missed run never breaches a threshold"
+  },
+  "sources": [
+    {
+      "id": "CC-MEMORY",
+      "service": "Claude Code memory files and imports (CLAUDE.md, AGENTS.md, @imports)",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/memory.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "claude-code-memory"
+      ],
+      "affected": [
+        "references/harness-facts.md",
+        "SKILL.md"
+      ],
+      "checksum": "e989818335ae45abb756df759d4859aa9daa6764393a3e39c46e505f181a33b6",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CC-SKILLS",
+      "service": "Claude Code skill discovery locations and frontmatter",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/skills.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "claude-code-skills"
+      ],
+      "affected": [
+        "references/harness-facts.md"
+      ],
+      "checksum": "8d03177dcc10ffbff5313c43023da15ff1059197c1fff05eb9dba3fe6361c767",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CC-TOOLS",
+      "service": "Claude Code AskUserQuestion tool behavior",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/tools-reference.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "claude-code-tools"
+      ],
+      "affected": [
+        "references/harness-facts.md",
+        "SKILL.md"
+      ],
+      "checksum": "3bdd8429e76be8213e9263103134ac7b6892f4574820e40bf84032a98c5d0aeb",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CODEX-AGENTS",
+      "service": "Codex AGENTS.md discovery, merging, and size cap",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://learn.chatgpt.com/docs/agent-configuration/agents-md.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "codex-agents-md"
+      ],
+      "affected": [
+        "references/harness-facts.md"
+      ],
+      "checksum": "9eacb3d812b87be4acc1213af58ded35e8f387bcf1589c203bbb452ead0c4774",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CODEX-SKILLS",
+      "service": "Codex skills discovery, frontmatter, and request_user_input gating",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://learn.chatgpt.com/docs/build-skills.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "codex-skills"
+      ],
+      "affected": [
+        "references/harness-facts.md",
+        "SKILL.md"
+      ],
+      "checksum": "44aa6d490f4567c0b1fb064deab642bfac590f0e721228e0c53fe738db191026",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CODEX-EXEC",
+      "service": "Codex non-interactive mode (codex exec)",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://learn.chatgpt.com/docs/non-interactive-mode.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "codex-exec"
+      ],
+      "affected": [
+        "references/harness-facts.md"
+      ],
+      "checksum": "df82c4bbf3b5bffca926a244549222c1235154cfba973b9a0bb1d7a0abd28d66",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    }
+  ]
+}

package/skill/dev-ship/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: dev-ship
+description: Create the pull request and merge for a finished issue, each only on the user's explicit word. Use when the user says "make the PR", "open a pull request" for an issue, "ship it", "merge it", "merge issue 12", or asks to close out a reviewed issue. Verifies the issue is at for-you with evidence, links the PR to the issue, and squash-merges on the separate merge instruction. Not for implementing issues (dev-implement) or writing and approving them (dev-intake).
+---
+
+# dev-ship
+
+Two gates, each one sentence from the user, each spent when used: their words asking for a PR authorize the PR and nothing more; their words asking to merge authorize the merge. With `gates: 2` in `.vegastack/dev.md`, one "ship it" covers both — that's the only case where they combine. Passing checks, PR permissions, and the calendar authorize nothing by themselves.
+
+Nearest neighbor: `dev-implement` produces the `for-you` issue with its evidence comment; ship packages and lands it. Corrections found here go back through implement's corrections loop.
+
+## Gate 1 — the PR
+
+On the user's PR instruction:
+
+- Verify the issue is at `for-you` with the evidence comment present, and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR.
+- `gh pr create` from the task branch: title from the issue, body is `Closes #<n>` plus a link to the evidence comment — the issue holds the report; the PR links it rather than duplicating it.
+- No draft PRs unless the user asks for one.
+- If required checks fail on the PR, that's implement work: hand the failures to the corrections loop, update the evidence comment, and tell the user.
+- User corrections left on the PR itself flow through the same corrections loop on the same branch — the PR updates with the push; nothing gets recreated.
+
+## Gate 2 — the merge
+
+On the user's separate merge instruction:
+
+- Re-check that the PR head is still the revision the evidence comment names and checks are green — a branch that moved since review gets re-verified before it lands.
+- A merge conflict with the default branch is corrections work: update the branch, re-verify what the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, which goes back to the user.
+- Merge per the dev.md `merge` knob (default `gh pr merge --squash`). `Closes #<n>` closes the issue; confirm both happened.
+- If the issue carries a `Decision:` comment (the dev-intake convention), append its one dated line to the register dev.md names (`decisions:` knob) now — the register is append-only and this is its moment.
+
+## Report
+
+One short confirmation each gate: what was created or merged, the link, and anything that still needs the user (failing check, moved head, missing evidence). When a gate's condition isn't met, the answer is what's missing — the gate itself never gets skipped to be helpful.

package/skill/dev-ship/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-ship"
+  short_description: "Open the PR and merge, each on the user's word"
+  default_prompt: "Use $dev-ship to create the PR or merge this issue's work."

package/skill/dev-ship/refresh/REFRESH.md

@@ -0,0 +1,3 @@
+# Refresh contract — dev-ship
+
+Evergreen: this skill asserts no version pins, vendor mechanism names beyond long-stable `gh` subcommands, numeric vendor limits, or dated facts — its content is the two-gate discipline, all versionless. Revisit if a future edit introduces a volatile fact.

package/skill/dev-ship/refresh/sources.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-27",
+  "note": "Evergreen waiver recorded in REFRESH.md; sources deliberately empty.",
+  "sources": []
+}

package/skill/skill-maintainer/SKILL.md

@@ -9,7 +9,7 @@ Maintenance skill for this repository. Every change under `skills/` must satisfy
 
 ## Operating rules
 
-1. Skill content lives only in `skills/<name>/`. Wiring lives outside it: the packaging allowlist in `packages/cli/scripts/sync-skill.mjs`, the root `README.md` skills table, and `CHANGELOG.md` (via changesets).
+1. Skill content lives only in `skills/<name>/`. Wiring lives outside it: the per-skill packaging allowlist in `packages/cli/packaging.json`, the root `README.md` skills table, and `CHANGELOG.md` (via changesets). The skillify scaffolder writes all three when creating a skill.
 2. Frontmatter is exactly two keys: `name` and `description`. The open spec also allows `license`, `compatibility`, and `metadata`, but this repo defaults to the minimal two; adding any other key is a policy exception needing maintainer sign-off.
 3. `name` must equal the directory name. Grammar: starts with a lowercase letter, then only lowercase letters, digits, and hyphens; no leading/trailing hyphen, no consecutive hyphens; at most 64 chars.
 4. `description`: at most 1024 chars, third person, states WHAT the skill does and WHEN to load it, trigger words front-loaded, no angle brackets. Never summarize the workflow in it — agents follow the summary and skip the body. Err slightly pushy: agents under-trigger.
@@ -23,29 +23,28 @@ Maintenance skill for this repository. Every change under `skills/` must satisfy
 | Need | Read |
 |---|---|
 | tri-harness standards: discovery paths, frontmatter rules, context budgets, install surfaces, portability rules, unverified items | [standards](references/standards.md) |
+| new skill: should-it-exist gate, scaffolding, the 8-item contract audit, behavioral evals | the `skillify` skill |
 | release, rename, deprecate, rollback mechanics | [release ops](references/release-ops.md) |
 | this skill's own freshness contract | [REFRESH](refresh/REFRESH.md), [sources](refresh/sources.json) |
 | authoritative repo policy | `CONTRIBUTING.md`, `docs/policies/content-versioning.md`, `docs/policies/release-and-rollback.md` at the repo root |
 
 ## Workflow: scaffold a new skill
 
-1. Create `skills/<name>/` with the full per-skill contract: `SKILL.md` (agent entry), `README.md` (repo-side walkthrough, never packaged), `references/`, `tests/` (bun tests, never packaged), `refresh/sources.json` + `refresh/REFRESH.md` (freshness contract), `agents/openai.yaml` (Codex interface metadata); `scripts/` and `assets/` only if the skill needs them.
-2. Write frontmatter and body per operating rules 2–6; the body routes to references, it does not inline them.
-3. Wire it in: add every packaged file to the allowlist in `packages/cli/scripts/sync-skill.mjs` (the build fails loudly on unlisted files); add a row to the root README skills table; add a changeset (a new skill is MINOR).
-4. The installer is multi-skill: every authored skill needs a packaging allowlist entry in packages/cli/scripts/sync-skill.mjs (the build fails loudly on unlisted files).
-5. Seed refresh baselines with the deterministic runner, never by hand — invocation in [REFRESH](refresh/REFRESH.md).
-6. Run the checks in operating rule 8.
+1. Run skillify's `scripts/scaffold-skill.mjs` — it creates the contract tree (`SKILL.md`, `README.md`, `refresh/`, `agents/openai.yaml`, tests and the trigger fixture) and performs the repo wiring itself: the `packages/cli/packaging.json` entry, the root README row, and the changeset (a new skill is MINOR). Fill in the README row description and changeset text it leaves as TODOs; files added after scaffolding go into the skill's `packaging.json` entry by hand (the build fails loudly on unlisted files).
+2. Write frontmatter and body per operating rules 2–6; the body routes to references, it does not inline them. `skillify` owns the full authoring and eval discipline.
+3. Seed refresh baselines with the deterministic runner, never by hand — invocation in [REFRESH](refresh/REFRESH.md).
+4. Run the checks in operating rule 8.
 
 ## Workflow: update or maintain
 
-- **Stable IDs are permanent.** Never renumber or reuse a rule ID; removing or renaming one is a MAJOR content change (`docs/policies/content-versioning.md`). New rules/references are MINOR; weakening a MUST is MAJOR; factual refreshes (pins, URLs, checksums) are PATCH.
+- **Content versioning.** New rules/references and new recorded decisions are MINOR; weakening a normative rule, removing or renaming a skill, or breaking a per-project profile format is MAJOR; factual refreshes (pins, URLs, checksums) are PATCH (`docs/policies/content-versioning.md`).
 - **Tag volatile claims.** Any sentence carrying a vendor version, mechanism name, or numeric budget gets a source marker comment mapping to an ID in that skill's `refresh/sources.json`, and the registry entry's `affected` list must name the reference it lives in. Untagged volatile facts rot silently.
 - **Description budgets.** Stay within 1024 chars and keep triggers in the first sentence: Codex truncates its skill list at 2% of the context window / 8,000 chars, Claude Code truncates a skill's always-loaded listing at 1,536 chars — the tail of a long description is the first thing lost.
-- **Packaged-file changes.** Any add/remove/rename of a packaged file must update the `sync-skill.mjs` allowlist in the same PR.
+- **Packaged-file changes.** Any add/remove/rename of a packaged file must update that skill's `packages/cli/packaging.json` entry in the same PR.
 
 ## Workflow: rename, deprecate, or remove
 
-Full playbook in [release ops](references/release-ops.md). Short form: a rename changes the directory and the frontmatter `name` in the same commit (they must stay equal), updates allowlist + root README table + CHANGELOG, and is MAJOR. Deprecation is announced in README/CHANGELOG before removal. Removal deletes the tree, unwires it, and is MAJOR.
+Full playbook in [release ops](references/release-ops.md). Short form: a rename changes the directory and the frontmatter `name` in the same commit (they must stay equal), updates the packaging.json entry + root README table + CHANGELOG, and is MAJOR. Deprecation is announced in README/CHANGELOG before removal. Removal deletes the tree, unwires it, and is MAJOR.
 
 ## Workflow: release
 

package/skill/skill-maintainer/references/release-ops.md

@@ -4,26 +4,22 @@ Condensed operational playbook. The authoritative policies live at the repo root
 
 ## Semver for skill content
 
-Consumers depend on rule IDs and rule strength, not an API surface.
+Content is advisory prose and decision tables — no rule IDs, no machine-extracted rule format.
 
 | Bump | Content change |
 |---|---|
-| MAJOR | Removing or renaming a rule ID (IDs are stable and permanent — never renumber or reuse). Changing a `MUST`/`MUST NOT` so it permits something previously forbidden. Removing or renaming a skill. |
-| MINOR | New rules or rule IDs. New references or reference sections. New skill. Loosening ceremony without weakening a `MUST`. Tightening a `SHOULD` to a `MUST`. |
-| PATCH | Factual refreshes: version pins, vendor mechanism names, URLs, registry checksums. Typos and non-normative wording. Test/fixture-only changes. |
+| MAJOR | Removing or renaming a skill. A breaking change to a per-project profile format (e.g. `.vegastack/arch.md`) that invalidates existing committed profiles. |
+| MINOR | New reference file or reference section. New or changed recorded decision (e.g. a new "use/not/why" row, a new red line). New skill. |
+| PATCH | Factual refreshes: pinned-fact updates, version pins, vendor mechanism names, URLs, registry checksums. Wording clarifications that don't change the recorded decision. Test/fixture-only changes. |
 
 Installer/CLI changes follow ordinary semver on the same package version; a release takes the highest bump either side requires.
 
-## Two version identities — never conflate
+## One version identity
 
-| Identity | Lives in | Governs |
-|---|---|---|
-| Package version | `packages/cli/package.json` (changesets) | npm releases of installer + content snapshot |
-| Foundation version | profile schema const, `profile-tool.mjs` default, `foundation-compatibility.json` | the profile/schema contract deployed `.vegastack/architecture` profiles validate against |
-
-- Bumping the **package** (even MAJOR) must never invalidate a deployed profile — profiles bind to the foundation version.
-- Bumping the **foundation** version is a content-contract event: it requires a compatibility entry describing how existing baselines are treated, and at minimum a MINOR package release.
-- Each identity has one source of truth; never introduce additional copies of either number.
+There is a single source of truth: the **package version** (`packages/cli/package.json`,
+changesets-managed) — the npm release identity for the installer and every bundled skill's
+content snapshot. No skill tracks a separate content-contract version, and no per-project
+profile carries a schema version to validate against.
 
 ## Release flow (tag-driven)
 
@@ -44,10 +40,10 @@ Contributors do not bump versions in PRs; releases are maintainer-driven.
 
 ## Rename a skill
 
-Derived from the stable-ID logic in content-versioning (skill names are consumer-facing identifiers like rule IDs):
+Skill names are consumer-facing identifiers — treat a rename as a stable-ID break:
 
 1. Rename the directory and the frontmatter `name` in the same commit — they must always stay equal.
-2. Update every wiring point in the same PR: the packaging allowlist in `packages/cli/scripts/sync-skill.mjs`, the root README skills table row, and any cross-skill or docs links.
+2. Update every wiring point in the same PR: the skill's entry in `packages/cli/packaging.json`, the root README skills table row, and any cross-skill or docs links.
 3. Changeset: MAJOR. Note the migration in `CHANGELOG.md`: copies installed under the old name are orphaned, and installer operations addressed to the old name stop resolving once the shipped manifest no longer knows it.
 4. Registry source IDs inside `refresh/sources.json` are skill-internal and unaffected, but every `affected` ref must still resolve to a real reference in the renamed tree.
 5. Re-run `node packages/cli/scripts/validate-skill.mjs skills/<new-name>` and the skill's tests — name/directory equality is validated.
@@ -60,4 +56,4 @@ Derived from the stable-ID logic in content-versioning (skill names are consumer
 
 ## Refresh branches
 
-Branches named `refresh/**` are reserved for the automated freshness loop and are CI-restricted to `skills/*/refresh/` and `skills/*/references/foundation-compatibility.json`. Human content changes go on normal branches. Never hand-edit checksums/versions/timestamps anywhere — CI re-fetches claimed baselines, so hand-edited values cannot merge.
+Branches named `refresh/**` are reserved for the automated freshness loop and are CI-restricted to `skills/*/refresh/`. Human content changes go on normal branches. Never hand-edit checksums/versions/timestamps anywhere — CI re-fetches claimed baselines, so hand-edited values cannot merge.

package/skill/skill-maintainer/refresh/REFRESH.md

@@ -5,18 +5,18 @@ Instructions for the scheduled refresh agent (and any human running a manual ref
 ## What this skill claims
 
 - **Durable content** (`SKILL.md` workflows and operating rules, `references/release-ops.md`): repo process, derived from `docs/policies/*` — the refresh agent NEVER edits these. If a policy doc changes, that is a normal human PR, not a refresh.
-- **Mechanism-coupled claims**: sentences marked `<!-- source: SOURCE-ID -->` inside `references/standards.md`. These carry the tri-harness standards — discovery paths, frontmatter rules, numeric context budgets, install surfaces. They are the compliance basis of every skill in this repo, so **all standards changes are semantic drift requiring a human-reviewed PR**: the agent may propose edits to marked sentences only, in the same PR as the registry update that evidences the change, and a maintainer must review before merge. The hard-limits table in `SKILL.md` mirrors several marked sentences; update it in the same PR (this is the one sanctioned SKILL.md touch, and only when a mirrored number changed).
+- **Volatile standards claims**: sentences marked `<!-- source: SOURCE-ID -->` inside `references/standards.md`. These carry the tri-harness standards — discovery paths, frontmatter rules, numeric context budgets, install surfaces. They are the compliance basis of every skill in this repo, so **all standards changes are semantic drift requiring a human-reviewed PR**: the agent may propose edits to marked sentences only, in the same PR as the registry update that evidences the change, and a maintainer must review before merge. The hard-limits table in `SKILL.md` mirrors several marked sentences; update it in the same PR (this is the one sanctioned SKILL.md touch, and only when a mirrored number changed).
 - **Volatile layer** (the only file the agent edits freely): `refresh/sources.json` — the source registry and staleness snapshot (checksums, retrieval times).
 
 ## How to refresh
 
-The deterministic runner is repo-shared and hosted in arch-guardian for now. Run from the repo root:
+The deterministic runner is repo-shared, hosted at `tooling/refresh/`. Run from the repo root:
 
 1. **Deterministic pass first** (no LLM judgment):
-   `node skills/arch-guardian/scripts/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json`
+   `node tooling/refresh/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json`
    drift/stale/unavailable results are the work-list. Exit 1 with a critical entry means fail-closed: the run must not be silently skipped. All four sources here are critical.
 2. **Accept verified changes** in the same code path:
-   `node skills/arch-guardian/scripts/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json --accept-baselines`
+   `node tooling/refresh/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json --accept-baselines`
    This writes registry, cache, and drift report together — never hand-edit checksums, versions, or timestamps; they must always come from a run. Baselines are runner-seeded; when a new source is added or a verified change is accepted, this accept-baselines invocation is the only sanctioned way to update them.
 3. **Semantic verification** for every source the deterministic pass flagged: read the changed page (fetch the registry URL), decide whether any `<!-- source: X -->` marked sentence in `references/standards.md` (or the mirrored SKILL.md hard-limits row) is now wrong, and propose the minimal edit. Unlike version-pin registries, checksum drift here is presumed meaningful until a human reads the diff — these pages define the standards themselves. Editorial churn may be accepted silently only after that read.
 4. **One standing refresh PR**, branch `refresh/weekly`, force-updated on every run (never stacked duplicates; the weekly workflow .github/workflows/refresh.yml maintains it). PR body lists: each changed source, old→new checksum, links to the evidence, and which marked sentences changed and why. A maintainer review is mandatory before merge.