# Contributing to Agent Skills Standard

Thank you for your interest in contributing! This document provides guidelines for setting up your environment and following our standards.

## 1. Development Setup

### Prerequisites

- **Repository Root & Tooling**: The root `package.json` *declares* `node: ">= 20.0.0"`. That manifest declaration covers root scripts only; it is not evidence that the CLI, MCP server, or website build runs on Node 20.
- **CLI Runtime & Website**: Supported Node.js 22 LTS `>= 22.13` on the 22.x line, or a newer supported LTS. The CLI declares no `engines` field; its declared dependency intersection is `^22.13.0 || >= 23.5.0` (`commander` 15 declares `>= 22.12.0`, `inquirer` 14 declares `>= 23.5.0 || ^22.13.0 || ^20.17.0`). The website package declares no `engines` field either, so use the same supported LTS line rather than any Node version above 22.13.
- **pnpm**: `v10.0.0+` (matching root `packageManager: pnpm@10.0.0`)

### Installation

```bash
# Install dependencies
pnpm install

# Build the project
pnpm build
```

## 2. Testing Standards

We maintain high test coverage (>90%). All PRs must include tests.

```bash
# Run all tests
npx vitest run

# Run with coverage report
npx vitest run --coverage
```

### Test Structure

- Unit tests live alongside source files in `__tests__` directories.
- Integration tests verify the CLI commands end-to-end.
- Snapshot testing is encouraged for critical outputs like `AGENTS.md`.
- Prefer consumer-visible behavior over pinned implementation detail. Do not snapshot the per-agent capability table merely to detect drift: capability and generated-export drift belongs to `pnpm docs:capabilities:check` and real transformer/ownership checks. When a test pins incidental wiring, source wording or a capability descriptor that is changing by design, remove it rather than repinning the old value.

### Session retrospective testing (local, synthetic only)

The retrospective core lives in `mcp/src/retrospective*` and powers the `ags retrospective` CLI command (`enable`, `disable`, `status`, `index`) alongside the stdio MCP server tools. Test it with synthetic session fixtures and a throwaway store root — never real sessions or `~/ags/diagnostics`.

```bash
# build (emits the MCP server and CLI)
rtk pnpm --filter agent-skills-standard-mcp build

# retrospective suites: store, publication, CLI, and engine specs
rtk pnpm --filter agent-skills-standard-mcp exec vitest run test/retrospective-*.spec.ts

# typecheck
rtk pnpm --filter agent-skills-standard-mcp exec tsc --noEmit

# tarball membership check
( cd mcp && rtk proxy npm pack --dry-run )
```

- Root validation: an existing `0755` root is refused with `ROOT_PERMISSIVE` — create a new root with `mkdir -m 700` or `chmod 700` on a dedicated directory, never a shared or synced folder.
- Assert exit codes and single JSON stdout lines / code-only JSON stderr — never report text or transcripts.

## 3. Creating Skills

Skills are the core value of this project.

1. **Draft**: Use `pnpm list-skills` or check `skills/metadata.json` to see existing categories.
2. **Create**: Add your category folder in `skills/`.
3. **Validate**: Keep each canonical `SKILL.md` at or below 100 lines; verify token budget with `pnpm calculate-tokens`.
4. **Reference**: Move detailed content to `references/`.
5. **Framework packs**: Large framework categories may add category-level `references/framework-map.md` for role navigation and stack routing (served via registry-backed MCP; current sync/generation tooling does not copy category-root guides to installed host directories (installed-host delivery deferred)); keep skill files focused on decisions and verification.
6. **Guardrail skills**: Add `pressure_scenarios`, `rationalizations`, `red_flags`, and behavior assertions to `evals/evals.json`.
7. **Evidence first**: Retain applicable earlier cases, remove obsolete expectations, and add preventing cases for corrected behavior. Candidate fixtures are not live efficacy evidence.
8. **Public package boundary**: Do not ship project-specific environment, VPN, account-selection, or credential-handling recipes in reusable skills or references.
9. **Trigger precision**: Qualify collision-prone framework topics; retain unrelated workflow negatives and intended qualified positives. Test consumer routing, not metadata copies.
10. **Requirements modeling & scope trees**: For complex feature discovery, load `references/requirements-modeling.md` on demand for verb-object scope trees, stop rules, and canonical shared definitions.
11. **Question-driven representations & diagram reuse**: Select views by question per `references/requirements-modeling.md`. Diagrams remain optional when markdown tables or prose answer precisely; reuse existing diagram capabilities.
12. **Low-risk equivalence & sensitive floors**: Low-risk maintenance tickets with approved behavioral AC, owner, scope fence, approval, and verification lane satisfy readiness without document creation. Enforce sensitive floors per `references/requirements-modeling.md`.
13. **Scoped change impact**: When requirements change, trace affected ACs, contracts, approvals, and evidence carrying existing IDs without reopening settled decisions.
14. **Host-neutral guidance**: Keep provider, account, profile, model, and machine specifics in host planning records only, not canonical guidance.
15. **System-design package**: Keep design-process ownership in `system-design-methodology` and critical-flow semantics in `system-design-data-architecture`; link to the canonical flow contract instead of copying it. Route mobile/client or SDK guidance only when those surface constraints affect correctness. Select views from decisions; do not impose infrastructure or diagram quotas.
16. **Delivery evidence**: Skill bodies are delivered per request in full. Never propose suppressing required content as a token optimization, and never claim savings from omitted bodies. Selection, returned-body and body-digest counts are different measurements.
17. **Routing metadata**: Keyword and composite patterns are consumer routing contracts. Qualify collision-prone substrings (for example delimiter-qualified `-view` / `-form`) and keep a positive control proving the intended match still fires.
18. **Diagnostic-prevention & trust boundaries**: Strictly scope operation-private capability minting to privileged mint, seal, restore, or high-risk mutation capabilities (ordinary user sessions follow their legitimate intended lifetime); require revalidation against authoritative sources (rejecting stale shared ledgers), and authentic caller provenance in persisted evidence without universal cryptographic signature mandates. Do not claim synthetic auth bypass (such as renderer-only fixtures, manual header injection, or standalone fetch) as proof of backend governance or CSRF enforcement.
19. **Truthful telemetry & resource accounting**: Follow the Missing ≠ Zero principle. In telemetry guidance and reporting, never coerce missing token counts or pricing rates to 0 or $0.00; distinguish catalog discovery from body fetch, context delivery, and active tool usage.
20. **Learning logs & no auto-promotion**: Document repeated mistakes and retrospective findings as proposed candidate lessons requiring human review. Do not auto-promote agent learnings directly into repository rules, instructions, or policy.
21. **Project verification guidance & operational kits**: Portable verification patterns belong in reusable skills (`skills/common/common-project-verification/`) with on-demand references (`kit-contract.md`, `maintenance.md`). Project-specific commands, URLs, handles, and journey maps remain project-owned (e.g. `docs/verification/<app>/`), never in public registry packages. Reusable kits must define launch, read-only doctor, drive, evidence retention, and cleanup. Reusable equivalents take precedence over creating competing kits; proofs require actual build/dirty-content identity and surviving evidence.

## 4. Creating Workflows

Workflows are portable SDLC procedures, not CLI commands. Keep canonical files in `.agents/workflows/*.md`; sync exports to each agent's native surface.

Rules:

1. Keep workflow files under 80 lines.
2. Use the order: goal, steps, output template.
3. Do not pre-fill example data.
4. Put heavy examples or checklists in `references/`.
5. Keep requirement naming explicit: BRD-lite (`brainstorm-feature`), PRD (`plan-feature`), SRS/FRS (`design-solution`).
6. Add to `DEFAULT_WORKFLOWS` only for the standard SDLC spine; add canonical source at `.agents/workflows/<name>.md`.
7. Core SDLC workflows expose `Runtime Contract`, `Handoff Payload`, `Blocking Questions`, and `Next Workflow`.
8. Run `pnpm audit:sdlc` after changes.
9. Never hand-edit a generated native workflow export. Sync installs the canonical body once for every configured provider and derives native output from it; regenerate through `pnpm generate-indices` and the normal sync tooling. In this repository, committed mirrors have no per-file lock ownership, so the generator forces only the deterministic export paths for the selected canonical workflows and backs up the replaced bytes first. It refuses to run from any working directory whose realpath differs from the authoring repository root, and it never forces `.agents/workflows/**` — the canonical catalog (including the Antigravity/Kiro native destination) is authored source, not a mirror.
10. Ownership is per canonical body: a workflow still bound by a configured agent or carrying a recorded native conflict survives partial uninstall; an edited, unowned or overridden canonical body is preserved and reported instead of being certified as managed.
11. MCP workflow lookup reads the installed catalog from `.skills-lock.json`; if a lock exists but the catalog metadata is missing, lookup reports `unverified` and asks for a sync instead of falling back to local or native copies.
12. Cloud operations stay on one entrypoint: `deploy-release` dispatches `setup|deploy|verify|monitor|diagnose|recover` (a genuinely omitted mode defaults to `deploy`) and the keyword-only `common-devops-operations` skill owns the shared MCP preflight, authorization, effect classification and reporting procedure. Provider MCP integrations are optional, consumer-owned setup described in `docs/mcp-integration-guide.md`; never add a provider-specific workflow, auto-install a provider driver or credential, or let guidance text stand in for host/IAM enforcement.
13. Retiring a workflow ID requires migrating active callers, chaining and audit lists, and stating the explicit consumer configuration update with no forwarding alias. Historical reports, receipts and run records keep the retired ID unchanged; generated exports are regenerated through the normal sync/generation path, never hand-edited.

## 5. Cybersecurity packages and governed evolution

- `cybersecurity` is opt-in, not part of default initialization. Select it in
  `.skillsrc` under `skills` with a reviewed immutable `ref`; before the first
  category release, use a reviewed commit SHA, not the unpublished
  `cybersecurity-v1.0.0` tag. Add `cyber-exercise`, `cyber-triage` and/or
  `cyber-purple-validation` explicitly to `workflows`.
- White team means exercise control and independent adjudication, not a synonym
  for compliance or white-hat testing. Use shared authorization/evidence skills
  across every team. Blue containment can be disruptive too.
- Keep examples synthetic or offline. Record scope, source/version, time,
  evidence, limitations, owner and finding status (`confirmed`, `suspected`,
  `blocked`, `not-tested`, `false-positive`). Missing telemetry is not success.
- Framework edges require framework/version/ID, relation, rationale, primary
  source and review status. An edge is not certification or measured efficacy.
- Keep root `LICENSE`/`NOTICE` attribution and package resources reviewable.
  Review scripts before execution; sync preserves bytes but does not approve
  code or enforce its runtime permissions.
- A retrospective creates a redacted proposal by default. Edit canonical source
  only with authorization; compare candidate/current/no-skill behavior with
  held-out cases; require independent review, staged rollout and rollback.
  Never treat a learning-log entry or a reviewer-name string as authorization.
- New release evidence must bind the complete package and immutable eval inputs.
  Resource changes invalidate skill-loaded evidence. Historical evidence remains
  readable but is not upgraded retroactively into whole-package proof.
- `cyber-lab-validation` is a strictly separate, opt-in candidate contract package within `cybersecurity`. It describes eligibility criteria for predeclared minimum-proof actions against pinned disposable synthetic local fixtures only. It requires explicit action- and version-specific approval, independently demonstrated host isolation and cancellation controls, finite limits, paired evidence, and bounded teardown. It is not an attack platform or general executor.
- `cyber-scoped-validation` remains the canonical offline and supplied-evidence validation lane. Canonical workflows (`cyber-exercise`, `cyber-purple-validation`, `cyber-triage`, `pentest`) route between safe offline analysis/replay and optional isolated lab validation through explicit preflights; if an active step is blocked or refused, dependent downstream steps are marked `dependency-blocked` (`evidence-missing`) while independent remediation, analysis, and rule drafting continue safely.
- Candidate contracts in `cyber-lab-validation` remain dormant in the repository without tool autoactivation. Multi-gate progression governs any future activation: G3 requires per-run host containment/cancellation proof; G4 requires evaluated model acceptance and independent review; G5 requires explicit publication approval.

## 6. Product management packages and evidence lifecycle

- `product-management` defaults to two foundation skills (`product-business-requirements` and `product-requirements`) via category include allowlist during `ags init`. The eight advanced skills (`product-evidence` and the seven discovery/validation methods) are opt-in. Select them in `.skillsrc` under `skills` with a reviewed immutable `ref` (omit `include` or list desired skills explicitly); before the first category release, use a reviewed commit SHA. Add `discover-product`, `validate-product` and/or `review-product-value` explicitly to `workflows` (or set `workflows: true`).
- All product decisions ground in `docs/product/<slug>/evidence.json` via `product-management/product-evidence`. Never fabricate customer observations, interview quotes, or causal ROI.
- Keep seven advanced PM skills keyword-only (`triggers.files: []`); keep `product-evidence` scoped to `docs/product/*/evidence.json`; keep foundation BRD/PRD skills scoped to their respective spec files. Never add broad markdown globs or universal file triggers that activate PM skills unexpectedly.
- Standalone validator (`validate-product-evidence.mjs`) and investment calculator
  (`evaluate-investment.mjs`) require Node >=20. In contrast, CLI sync and the T09
  integration harness use `Promise.withResolvers` (available from Node 22.0.0) and
  therefore run only on the supported CLI range in Prerequisites (Node 22 LTS
  `>= 22.13` or a newer supported LTS).
- Invocation of standalone resources returns structural findings and host-check
  eligibility, never autonomous action consent. Review scripts before execution;
  sync preserves bytes and ownership but does not grant autonomous spend,
  experiment exposure, or rollout authority.
- MCP workflow discovery (`list_workflows`, `get_workflow`) scans only canonical
  `<root>/.agents/workflows` (Antigravity/Kiro). Other agents export workflows to
  their native surfaces; no runtime scanner expansion is performed.
- JSON routing maps `*.json` to `common` and `product-management`. `product-evidence` matches exclusively `docs/product/*/evidence.json`, while advanced PM skills are strictly keyword-only and never match `package.json` or unrelated JSON files.

## 7. Marketing packages and evidence-led campaign lifecycle

- `marketing` is an optional, opt-in category (twelve skills: `marketing-audience-research`, `marketing-positioning`, `marketing-proof`, `marketing-strategy`, `marketing-content-strategy`, `marketing-copywriting`, `marketing-search-discovery`, `marketing-landing`, `marketing-community`, `marketing-launch`, `marketing-demo-video`, `marketing-measurement`). It is not part of default initialization. Because the category is newly authored in this branch and no published remote tag or commit contains these skills yet, selecting `marketing` against the remote registry remains blocked until an authorized release occurs. In `.skillsrc`, consumers will select `marketing` under `skills` with a reviewed immutable ref once published.
- Advanced PM dependencies (Measurement-only vs Full Campaign):
  - **Measurement-only**: Evaluating campaign scorecards via `marketing-measurement` requires explicit installation of `product-management/product-evidence` and `product-management/product-investment`.
  - **Full Campaign**: Conducting end-to-end campaign planning with `marketing-campaign` additionally requires `product-management/product-customer-discovery`, `product-management/product-market-research`, and `product-management/product-strategy` (and `product-metrics`/`product-experimentation` when verifying registered metric contracts or experiment bounds). Do not assume source checkout availability.
- Routing: marketing skills are keyword-routed without generic file capture. `marketing-landing` triggers specifically on `website/src/landing/**`, and `marketing-demo-video` triggers on `docs/product/*/campaigns/**/demo*` and `docs/product/*/media/**`. Unrelated files (e.g. `package.json`, generic `*.md`) never match marketing.
- Thin optional workflow: `.agents/workflows/marketing-campaign.md` provides thin optional orchestration for campaigns. It is not part of `DEFAULT_WORKFLOWS` or the core SDLC chain.
- Guardrails: all generated assets remain in `state: "prepared"`, `outcome: "propose"`. No autonomous publishing, promotional forum posting, or spend authorization.

## 8. Default Init Standards

`ags init` should create a useful SDLC standards layer without requiring profile files.

Rules:

1. Include `quality-engineering` as a skill category by default when registry metadata provides it.
2. Sync `specialists` directly as native sub-agents, not as `skills.specialists`.
3. Keep `custom_overrides` visible so teams know how to protect local standards.
4. Use pinned category refs from `skills/metadata.json`.
5. Treat Jira, ADO, Zephyr, and similar MCPs as optional workflow integrations, not required core dependencies.
6. Workflows may call available tasking/test MCPs, but must still work from local artifacts.
7. Channel agents must continue only when required artifacts/owners are known; otherwise return BLOCKED with max 3 blocking questions.
8. New specialists must include `evals/evals.json`, strict budgets, structured output, and `No sub-agents`.
9. Specialists and generated workflow skills set `metadata.internal: true` so skill installers (`npx skills`) don't offer them as installable skills.

## 9. Quality Gates

Run these before PR:

```bash
pnpm --filter ./cli validate:all
pnpm audit:skills
pnpm audit:sdlc
pnpm check-alignment
pnpm docs:capabilities:check
pnpm freshness:audit
pnpm test
pnpm build
```

`pnpm check-alignment` checks lexical eval alignment (that eval `contains` anchors exist in the skill body); it is not export parity, native capability or runtime-success proof. Capability-table drift is checked separately by `pnpm docs:capabilities:check`, and generated mirrors must come from `pnpm generate-indices` rather than manual edits.


`pnpm freshness:check` is the weekly upstream drift job (`.github/workflows/skill-freshness.yml`), not a PR gate: it needs a `GITHUB_TOKEN` (up to ~110 GitHub requests) and exits 1 whenever any upstream has shipped a new major, regardless of your change. Run it locally only when reviewing pins; see `docs/FRESHNESS.md`.

For changes to the architecture-diagram pipeline, also run its stdlib Python suite, offline export verification, and a real render:

```bash
python3 -m unittest discover -s skills/common/common-architecture-diagramming/scripts -p 'test_*.py'
python3 skills/common/common-architecture-diagramming/scripts/validate_manifest.py skills/common/common-architecture-diagramming/assets/fixtures/view-manifest.json
python3 skills/common/common-architecture-diagramming/scripts/render_drawio.py skills/common/common-architecture-diagramming/assets/fixtures/component.spec.json -o /tmp/component.drawio --strict
python3 skills/common/common-architecture-diagramming/scripts/export_html.py skills/common/common-architecture-diagramming/assets/fixtures/component.spec.json --output-dir /tmp/component-package/
```

Inspect the rendered image in draw.io and open `/tmp/component-package/index.html` locally to visually inspect both light and dark themes at 100% zoom, not only XML or geometry checks. Refresh golden files only after an intentional renderer change (`UPDATE_GOLDEN=1 python3 -m unittest test_fixtures` from the scripts directory), then verify without the update flag. Never acknowledge overwriting a manually edited diagram without first reconciling its semantic changes into the spec. Detailed offline bundle specifications and security boundaries are documented in `skills/common/common-architecture-diagramming/references/offline-export.md`.

For database query performance and N+1 query amplification changes, run the stdlib Python regression suite and real SQLite smoke fixture:

```bash
python3 -m unittest discover -s skills/database/database-query-performance/scripts -p 'test_*.py' -v
python3 skills/database/database-query-performance/scripts/nplus1_smoke.py --json
```

The fixture verifies runtime statement counting ($1 + N$ queries), bounded batch remediation ($Q_{base} + \lceil N / B \rceil$, yielding 2 SELECTs even under high fan-out with 250 child relations), pagination, tenant isolation, and aggregate projection on real local SQLite without requiring external database services or packages. Conceptual distinctions (already-batched queries, slow constant-count routines, and N+1 spare-instance redundancy) belong to guidance and held-out model evaluation, documented in `skills/database/database-query-performance/references/nplus1-diagnosis.md`.
For live-eval or eval-definition changes, also run:

```bash
pnpm evals:audit
pnpm evals:baseline -- --plan
pnpm evals:verify -- --all
pnpm evals:report
pnpm evals:queue -- --run <runId>
```

For routine maintenance, `pnpm evals:baseline` is the single starting command.
It selects the latest complete immutable reference and creates a selective run
only for changed skills; it reuses only source-compatible transcripts. Do not
replace it with a full `--all` run unless the protocol, model, or generation
environment changed.

When evaluating release trustworthiness after broad remediation, use a fresh
aggregate manifest and execute it with one pinned model/reasoning configuration.
The release gate is per skill: with-skill case pass must be strictly above 85%,
assertion pass must be at least 85%, delta must be non-negative, and trigger
recall/specificity must each be at least 90%. A composite or reused run may be
kept as historical evidence but cannot be promoted as release proof.

Never hand-edit `results.json` or historical transcripts. New runs must be complete, must contain immutable `inputs.json`, and must use the canonical `.agents/workflows/evals-run.md` workflow; regenerate exported workflow copies from the canonical source.

For system-design evaluations, lexical assertions check presence or routing only; they do not judge mechanism correctness or prove runtime behavior. A body-only comparison is not whole-package evidence: references, workflow guidance, package resources, and generated exports may change behavior. Report source scope and evidence kind separately, and require fresh applicable package-bound evidence before claiming release efficacy. Model execution remains subject to its separately authorized route and approval gate.


For release candidates, also run:

```bash
pnpm check-alignment --threshold 90
pnpm benchmark:report
```

Guardrail-oriented skill changes should also verify that the benchmark report shows behavior coverage for the edited skills.

### Isolated Stage Generation & Check-Only Pre-Commit

> [!NOTE]
> **Candidate Tooling (Verified This Candidate / Revision):** Isolated stage generation and pre-commit check tooling are verified for this candidate revision (95 outputs applied + verified check PASS; SDD evidence intact). Scoped adoption remains strictly bounded and requires explicit authority with matching tracked base and prior producer output. The candidate remains unreleased; example commands and plan approval do not themselves authorize future execution, publication, or release. No host enforcement, Node 20 runtime, model efficacy, or benchmark uplift is claimed.

To prevent clobbering active worktree evidence (such as `.agent/sdd`) or drifting destination files during generation, index and capability generation is executed in an isolated stage:

```bash
# Verify prepared generation outputs (check-only pre-commit hook)
node --import tsx scripts/generation/index.ts --check

# Run generation in an isolated stage and copy back verified changes
node --import tsx scripts/generation/index.ts
```

Pre-commit hooks are strictly check-only; they must never actively generate files or run git staging. The isolated stage records pre-generation digests and halts if concurrent edits or foreign paths are detected.

The public `pnpm generate-indices` command uses the candidate coordinator. Run
`pnpm generate-indices --check` to verify prepared outputs and
`pnpm generate-indices` to apply them. The coordinator invokes the internal
`scripts/generate-indices.ts` child directly in its isolated stage to avoid
recursion.
By default, unchanged existing outputs may be checked without creating an
ownership manifest; differing outputs without trusted ownership are refused.
For declared CLI-managed outputs, `pnpm generate-indices` accepts provenance
when destination bytes match their recorded ownership digest or equal the
repository `HEAD` blob, persisting refreshed digests into `.skills-lock.json`
during publication. A committed edit to a generated mirror no longer blocks
generation publication, while an uncommitted working-tree edit that differs
from both `HEAD` and resolved stage bytes still refuses.
Do not use adoption as a routine override. An authorized bounded adoption uses
`pnpm generate-indices --adopt-base <full-commit-sha>` and requires the current
files to match both that tracked base and the prior producer's output. Adoption
evidence is archived under the run receipt before publication.
`--check` never adopts or changes ownership.

Historical provenance for the config-independent repository-generation outputs
is recorded by a separate, authority-gated operator action —
`pnpm generate-indices --recover-provenance <full-commit-sha>` — and never as a
routine repair. Its scope is strictly `skills/index.json`,
`skills/metadata.json`, `skills/README.md` and canonical
`skills/<category>/_INDEX.md` files, and it is all-or-nothing: any other
requested path (host mirrors, workflow or specialist exports, rule files, host
indices, `AGENTS.md`, root `README.md`, `cli/README.md`) refuses the whole run
with no destination, index or lock effect. The named commit must be a full SHA
that is an ancestor of `HEAD`; `HEAD` equality alone is never accepted as
provenance. Before publication the run must show, per requested path, that the
Git index entry and working-tree bytes both match that base commit, that the
historical producer archived at that commit reproduces those exact bytes, and
that `skills/metadata.json` matches on its `token_metrics` scope and index mode.
A runtime differential closes the config gap: the pinned-base producer is rerun
under the current configuration, and any byte difference refuses the run. The
configuration files are captured with worktree, index and base digests, must be
regular non-symlink files, at least one must exist in both the base tree and
the worktree, and those digests are reasserted before each publish effect.
`--recover-provenance` is mutually exclusive with `--adopt-base` and `--check`,
and it never heals outputs through `HEAD` blob equality. Evidence is retained
under the run's `artifacts/generation-logs/<attempt>/` receipt: `adoption/before`
snapshots, `adoption/proof.json` extended with `mode: "recover"`, base and
`HEAD`, ancestry, the requested set, configuration digests and the per-path
differential result, plus `recoveredFiles` in `receipt.json`. Any failed
precondition fails closed without partial recovery: non-full or unresolved SHA,
non-ancestor base, non-recoverable path, provenance or metadata drift, a failed
historical producer phase, a configuration-dependent result, concurrent edits,
or a symlink in the archived snapshot. This capability is unreleased and
unverified: the paragraph documents the candidate contract only, and no
recovery run, test result, lock mutation or publication is claimed.

The ownership manifest keeps CLI-managed entries separate from the
repository-generation ledger. Publication updates only changed, verified
outputs; unchanged unowned files are not claimed. The `skills/metadata.json`
generation entry records both its full-byte digest and a scoped digest over
each category's `token_metrics` value (including whether that field is absent).
The token producer may change that scope only; authored fields outside
`token_metrics` remain active. A metric-changing refresh requires the active
metadata file to use two-space JSON serialization with a final newline, then
updates only `token_metrics` while preserving the other fields. Unsupported
serialization or nonmetric producer changes fail closed rather than
reformatting authored data.

Before publication, the coordinator validates configured category/index
coverage, host mirrors and transformed outputs, workflow and specialist
surfaces, and the capabilities document against its producer's exact render.
It snapshots source, destination, manifest, and Git invocation state; archives
before-bytes outside those inputs; revalidates before each publish effect; and
publishes the ownership ledger last. Keep the Task 1 review gate above: this
contract does not authorize root generation or release by itself.

### Truthful Layered Verification & Host Boundaries

Verification tracks layered acceptance states independently based on approved task and release scope applicability (not requiring universal human sign-off on every unit iteration):
1. **Source-ready**: complete source delivery at recorded Git SHA + dirty identity, with build, lint, and typecheck recorded independently (`PASS`, `FAIL`, `NOT RUN`, or `NOT APPLICABLE`).
2. **Focused checks**: unit and boundary contract suites; test count and membership derived directly from raw output, rejecting zero-exit or no-listener runs.
3. **Consumer-smoke**: real producer→consumer integration proof scoped to actual changed entrypoints and outward side effects, not universal regression coverage.
4. **Independent review**: unbiased inspection by separate reviewers per approved scope.
5. **Human acceptance**: explicit authorized sign-off when mandated by release scope.

Pre-implementation RED must be recorded as `NOT RUN` if not actually observed prior to code edits; never fabricate historical RED by modifying guards or asserting simulated failures. Finite eval oracles verify bounded assertion contracts; they do not prove whole-answer semantic safety, model uplift, or production efficacy.

Host-level actor-scoped tool authorization, task/turn ownership, process management, and telemetry collectors (H01–H05) are external host responsibilities (e.g., OMP/Paseo). In this checkout, host-only slices remain explicitly blocked by user decision; repository rules must never be misrepresented as live host enforcement, auto-approval, or denial bypass. Do not claim model efficacy, benchmark uplift, or deployed host security enforcement without qualified evidence from an authorized live environment.

## 9. Release Process

We use specialized scripts for releasing components independently:

- `pnpm release-cli`: Bumps `cli/package.json` and updates `CHANGELOG.md`.
- `pnpm release-all-skills`: Syncs and pushes git tags for newly bumped versions in `skills/metadata.json` (`categories` and `releases`).
- `pnpm release-server`: Releases the backend component.
- `pnpm release:manifest --tag <tag> [--out <file>]`: Rebuilds the deterministic `MANIFEST.json` locally for any release tag.

When `.agents/workflows/**` changes, bump `releases.workflows.version` in `skills/metadata.json`. Every registry release publishes a `MANIFEST.json` containing sha256 checksums of all released files along with a GitHub build-provenance attestation.

Ensure you update `CHANGELOG.md` manually before running release scripts if significant features were added.

## 10. Delegation, capability and evaluation evidence

These rules bind contributors changing delegation or model-capability guidance. They describe repository contracts; they do not activate a host default, enforce permissions or establish savings.

1. **One placement contract.** `skills/common/common-subagent-driven-development/SKILL.md` §1 owns the context-benefit placement decision. Link it from workflows and references; never add a second decision table. Placement is a preparation decision on the existing dispatch receipt, not an eighth lifecycle operation, host API or schema field. A specialist label, workflow stage, file count or plan length is not a delegation benefit, host requirements win, and an independent reviewer is required regardless of placement.
2. **One capability contract.** `skills/common/common-task-complexity-routing/references/routing-table.md#capability-and-effort-resolution` owns capability versus effort guidance, host-owned resolution, dispatch-receipt fields, recovery routes and cost vocabulary. Link the heading instead of restating fields. Do not add a model-resolver service, pricing API, telemetry store or mandatory assignment-schema field.
3. **Hints are not authority.** `fast|standard|strong` and low/medium/high effort are advisory. Eligibility, approved profiles, supported effort and fallback come from host/project configuration; explicit configured settings are never silently replaced. Offline/synthetic fixtures never promote a native support claim.
4. **Honest accounting.** Count the accepted task including parent, workers, independent reviews, repairs and failed or cancelled attempts. Keep tokens, billed money, subscription/quota consumption and elapsed time distinct. Unknown price or quota stays `unknown`; claim no monetary saving without complete comparable actor coverage.
5. **Offline versus live.** Scorer, lexical and fixture runs are routing/assertion evidence only. Do not describe them as live model efficacy, measured savings, host activation or sandbox enforcement. Preserve earlier failures as dated history rather than rewriting them into passes.
6. **No unauthorized spend.** Live comparative runs require separately recorded provider/account eligibility, exact model and effort, run cap, spend or usage ceiling, expiry and human approval. Without it, finish the protocol and offline checks, record live runs as `not_run`, and activate nothing.
7. **Protocol.** Follow `docs/validation/context-aware-delegation-protocol.md` for any proposed delegation or capability comparison: all ten scenarios, three matched repetitions per scenario per arm, unchanged-variable controls, per-case regressions, synthetic fixtures for dangerous or provider-failure cases, and reuse of existing eval infrastructure rather than a new benchmarking platform.
8. **Generated surfaces and evidence.** Never hand-edit generated mirrors or native exports; regenerate through the documented generator flow and preserve `.agent/sdd` evidence, immutably archived under `artifacts/<slug>/evidence/` with a manifest. A green generator run is not export parity.