coding-agent-skills 0.2.8

package/AGENTS.md

@@ -0,0 +1,44 @@
+# Agent Operating Contract
+
+This repository contains shared coding-agent skills, safety contracts, validators, and disposable harness fixtures.
+
+## Scope
+
+Agents working here may maintain the shared skill pack, validators, documentation, examples, and synthetic fixtures. They must not add new skills, real project adapters, platform integrations, deployment procedures, or project-specific behavior unless a human explicitly approves that milestone.
+
+## Maintainer Loop
+
+Use `./scripts/run-next --allow <permission>` to inspect the repository, validate the current pack, read the roadmap/changelog/work ledger, and decide the next bounded action. The loop is intentionally conservative: it selects and evidences work, then stops at approval boundaries.
+
+Supported permission flags are:
+
+- `harness-hardening`
+- `docs-hardening`
+- `test-hardening`
+- `adapter-harness`
+- `evidence-harness`
+- `release-preflight`
+- `commit`
+- `tag`
+- `push`
+
+Unknown flags must fail closed. Permission flags do not weaken skill restrictions.
+
+## Safety Boundaries
+
+Agents must not:
+
+- create new skills without explicit approval
+- modify real project repositories
+- add real project adapters
+- run platform publication or infrastructure commands
+- apply database changes
+- mutate local services or background processes
+- read local environment files
+- print secrets or credentials
+- use destructive Git operations
+- weaken shared safety policies, command policies, evidence requirements, or adapter inheritance
+
+## Evidence Standard
+
+Every maintainer-loop run must leave evidence in `runs/skill-runs.md` or an approved report. Evidence must include the command used, granted permissions, files changed, validation commands, validation result, release status, next state, and unresolved approval gates.

package/CHANGELOG.md

@@ -0,0 +1,205 @@
+# Changelog
+
+All notable changes follow [Semantic Versioning](docs/versioning/README.md).
+
+## [0.2.8] - 2026-06-19
+
+### Added
+
+- Public npm package metadata for `coding-agent-skills`.
+- MIT license file with approved OneClickPostFactory copyright.
+- Public npm install documentation for the supported CLI commands.
+
+### Changed
+
+- Package validation now requires public npm metadata, MIT license, repository metadata,
+  public registry configuration, strict package allowlist, dependency-free shape, and
+  installed-package safety checks.
+- Release tests now cover the public package contract and installed `validate-pack`
+  behavior.
+- Release documentation now includes npm publish dry-run, tarball inspection, temporary
+  install smoke tests, registry verification, and GitHub Release expectations.
+
+## [0.2.3] - 2026-06-17
+
+### Added
+
+- Synthetic evidence archive index schema and fixture files linked from evidence bundles.
+- Retention-expiry advisory metadata and report output with manual-review-only semantics.
+- Detached-signature verification planning metadata that records required future artifacts
+  without running signing or verification infrastructure.
+- Disposable advisory, archive-index, and signature-plan fixtures for safe acceptance and
+  rejection coverage.
+
+### Changed
+
+- Evidence-bundle verification now validates archive indexes, reports retention-expiry
+  advisory status, and rejects unsafe signature-verification plans.
+- Archive reports now include archive-index summary, retention advisory status, and
+  detached-signature verification planning metadata.
+- Current synthetic examples and fixtures now target `0.2.3` with `0.2.2` as the previous
+  release boundary.
+
+## [0.2.2] - 2026-06-16
+
+### Added
+
+- Evidence-bundle retention metadata for bounded review windows, storage class, and
+  redaction policy.
+- Provenance metadata for producer, source commit, target tag, canonicalization, digest
+  algorithm, and detached-signature design.
+- Sanitized evidence archive report schema and read-only renderer.
+- Disposable invalid fixtures for retention-window, provenance-tag, and archive-policy
+  rejection.
+
+### Changed
+
+- Evidence-bundle verification now rejects unsafe retention, provenance, and archive
+  declarations before claiming replay or regression success.
+- CI, pack validation, release tests, safety docs, privacy docs, authoring docs, and
+  testing docs now include archive-report rendering.
+- Current synthetic examples and fixtures now target `0.2.2` with `0.2.1` as the previous
+  release boundary.
+
+## [0.2.1] - 2026-06-16
+
+### Added
+
+- Evidence-bundle JSON Schema and dependency-free verifier.
+- Deterministic replay through canonical report hashing.
+- Cross-release compatibility regression checks for baseline entry coverage and status
+  preservation.
+- Disposable valid and invalid evidence-bundle fixtures for hash mismatch, missing entry,
+  path traversal, and regression failures.
+
+### Changed
+
+- CI, pack validation, release tests, safety docs, testing docs, roadmap, and ledger now
+  include evidence-bundle verification.
+- Current synthetic examples and fixtures now target `0.2.1` with `0.2.0` as the previous
+  release boundary.
+
+## [0.2.0] - 2026-06-15
+
+### Added
+
+- Root agent contract, maintainer runbook, explicit work ledger, and append-only run log.
+- Dependency-free `scripts/run-next` coordinator with fail-closed permission gates.
+- Dedicated maintainer-loop validator covering required files, ledger shape, executable
+  mode, permission declarations, unsafe-command absence, docs, and CI integration.
+
+### Changed
+
+- CI and the release harness now validate the maintainer loop.
+- README, roadmap, contribution, release, testing, and safety documentation now define
+  autonomous milestone selection and human approval stop boundaries.
+- Evidence-bundle verification remains queued in the ledger and is not implemented.
+
+## [0.1.6] - 2026-06-14
+
+### Added
+
+- Machine-readable adapter-upgrade evidence schema with sanitized pair and chain examples.
+- Dependency-free compatibility-chain validator for ordered simulated project revisions.
+- Optional safe `--json` and non-overwriting `--output` evidence modes.
+- Disposable chain fixtures for valid progression, stale pins, core and skill
+  incompatibility, schema drift, and restriction weakening.
+- Chain-level privacy, path, symlink, mutation, and unsafe-policy tests.
+
+### Changed
+
+- Pair validation can target an adjacent historical core when used inside a chain while the
+  final chain revision must match the running core.
+- Release validation and CI now validate a complete three-revision compatibility chain.
+- Adapter, evidence, versioning, safety, authoring, testing, and roadmap documentation now
+  define structured read-only upgrade review.
+
+## [0.1.5] - 2026-06-14
+
+### Added
+
+- Dependency-free adapter upgrade comparison command for paired project revisions.
+- Distinct stale exact-pin and stale compatible-range detection.
+- Disposable revision fixtures for safe upgrades, old and future cores, schema and skill
+  drift, restriction weakening, mode escalation, and evidence removal.
+- Dynamic rejection coverage for failure suppression, completion override, unknown skills,
+  secret exposure, and traversal.
+
+### Changed
+
+- Project validation can evaluate an immutable source revision against its declared core
+  while upgrade acceptance remains pinned to the running shared core.
+- Release validation and CI now exercise the safe adapter upgrade path.
+- Adapter, versioning, safety, authoring, and testing documentation now define upgrade
+  evidence and drift rejection.
+
+## [0.1.4] - 2026-06-13
+
+### Added
+
+- Project-owned adapter installation declaration schema and dependency-free validator.
+- Exact core pins and compatible comparator ranges without a semver dependency.
+- Disposable project fixtures for valid installation, version mismatch, unsafe location,
+  policy weakening, secret exposure, scope expansion, and traversal.
+- Bidirectional matching of project ID, adapter root, adapter ID/version, and pilot skill IDs.
+
+### Changed
+
+- Release validation and CI now exercise a declared project-owned adapter installation.
+- Adapter, testing, safety, authoring, and versioning documentation now define safe adoption.
+
+## [0.1.3] - 2026-06-13
+
+### Added
+
+- Dependency-free external adapter discovery and validation CLI.
+- Disposable fixture roots for all supported locations, compatibility failures, policy
+  weakening, malformed input, mixed roots, traversal, and symlink escapes.
+- Safe public rejection codes and explicit empty-root behavior.
+
+### Changed
+
+- Release validation and CI now exercise an external adapter root.
+- Adapter documentation now defines exact manifest naming, extension-only inheritance, path
+  safety, and future project-owned integration.
+
+## [0.1.2] - 2026-06-13
+
+### Added
+
+- Formal project-adapter JSON Schema and three valid synthetic examples.
+- Bidirectional adapter skill/version/mode compatibility tests.
+- Property-style command-policy generation across composition and bypass families.
+- Provider-specific `npx`, bounded-read, authenticated-health approval, and package-script-body checks.
+
+### Changed
+
+- Skill manifests now declare adapter contract compatibility.
+- Command policies now declare parser invariants and argument strategies.
+- Validator enforcement now covers valid and invalid adapters plus command-policy invariants.
+
+## [0.1.1] - 2026-06-13
+
+### Added
+
+- Trigger-classification fixtures for positive, negative, and wrong-skill cases.
+- Command-parser coverage for composition, wrappers, heredocs, package tools, Git, curl, and unsafe arguments.
+- Mutation snapshots and audit-only documentation enforcement.
+- Split synthetic privacy fixtures with in-memory detection and redaction tests.
+- Adapter-weakening and evidence false-completion matrices.
+
+### Changed
+
+- CI now runs structural validation, the complete harness, and built-in Node tests.
+- Shared policy rules and release validation enforce the v0.1.x harness boundaries.
+
+## [0.1.0] - 2026-06-12
+
+### Added
+
+- Shared evidence-pack contract and schemas.
+- Five pilot skills: `repo-map`, `build-verify`, `git-preflight`, `runtime-truth`, and `llm-drift-control`.
+- Concrete manifests, command policies, evidence packs, and workflow examples.
+- Dependency-free pack validation and executable release tests.
+- Synthetic fixtures and safe GitHub Actions validation.
+- Release, privacy, adapter, usage, contribution, and roadmap documentation.

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+## Before Adding A Skill
+
+1. Establish repeated, safe, generalizable evidence.
+2. Classify the skill as audit-only or action-capable.
+3. Define approval boundaries before command procedures.
+4. Keep platform and project behavior outside general skills.
+5. Obtain explicit scope approval.
+
+## Required Skill Shape
+
+Initialize skills with the official skill creator and include:
+
+- `SKILL.md`
+- `agents/openai.yaml`
+- `checklist.md`
+- `examples.md`
+- `failure-modes.md`
+- `adapter-interface.md`
+- `evidence-template.md`
+
+Add a manifest example, command-policy example, evidence-pack example, workflow example, and executable tests.
+
+## Safety Rules
+
+- Never copy restricted evidence into reusable procedures.
+- Never commit secrets or local `.env` files.
+- Audit-only skills cannot gain mutation through adapters or approval.
+- Action-capable skills must enumerate permitted local actions and reject everything else.
+- Failed or skipped required checks cannot produce `complete`.
+
+## Validation
+
+Run:
+
+```bash
+node scripts/validate-pack.mjs .
+node scripts/test-pack.mjs
+node scripts/validate-maintainer-loop.mjs .
+node --test
+```
+
+Update the changelog and roadmap when behavior or scope changes.
+
+## Maintainer Loop
+
+`./scripts/run-next --allow <permission>` may inspect local repository state, validate the
+pack, select the next ledger milestone, and append bounded run evidence. It must start from
+a clean worktree and fails closed for missing, unknown, or mismatched permissions.
+
+The loop does not replace human approval for scope changes, new skills, real adapters,
+release publication, dependencies, or weakened safety rules. Update `work-ledger.md` when
+the approved next milestone or its stop conditions change.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OneClickPostFactory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# Coding Agent Skills
+
+Shared, versioned workflows for evidence-driven coding agents.
+
+The pilot pack contains:
+
+- Shared evidence-pack contract.
+- `repo-map`: audit-only repository orientation.
+- `build-verify`: controlled local validation using existing project commands.
+- `git-preflight`: audit-only Git readiness inspection.
+- `runtime-truth`: audit-only runtime evidence collection.
+- `llm-drift-control`: audit-only claim reconciliation.
+
+It does not contain deployment, package installation, Git publication, runtime mutation, migration, privileged API, platform-specific, or project-specific skills.
+
+Project-specific adapters will live in their owning repositories and may narrow, but never weaken, shared safety rules.
+
+## Principles
+
+- Inspect before acting.
+- Separate audit-only skills from action-capable skills.
+- Preserve user work and external state.
+- Treat restricted historical evidence as warnings, not reusable commands.
+- Produce evidence before claiming completion.
+- Report skipped, failed, and unverifiable checks honestly.
+
+See [architecture](docs/architecture/README.md), [safety](docs/safety/README.md), and [authoring](docs/authoring/README.md).
+
+## Completion Standard
+
+Every skill emits the evidence-pack contract. A command being attempted is never enough to claim success. Required checks, skipped checks, failures, confidence, unresolved questions, and state changes must all be represented.
+
+## Use And Validate
+
+- Read [usage guidance](docs/usage/README.md) before selecting a skill.
+- Browse [safe examples](examples/README.md) for manifests, policies, evidence packs, and workflows.
+- Install the public CLI with `npm install -g coding-agent-skills`.
+- Run `coding-agent-skills validate-pack` to validate the installed pack.
+- Run `npx coding-agent-skills validate-pack` when a one-off npm execution is preferred.
+- From a clone, the same wrapper is available as `bin/coding-agent-skills validate-pack`.
+- Validate project adapters against [the formal adapter schema](schemas/project-adapter.schema.json).
+- Review [external adapter discovery](docs/adapters/discovery.md).
+- Run `node scripts/validate-adapters.mjs <adapter-root>` for a disposable external root.
+- Review [project-owned installation and pinning](docs/adapters/project-installation.md).
+- Run `node scripts/validate-project-adapters.mjs <project-root>` for a declared project root.
+- Render adapter-aware `repo-map` orientation with
+  `node scripts/render-adapter-repo-map.mjs <project-root>`.
+- Review [adapter upgrade checks](docs/adapters/upgrades.md).
+- Run `node scripts/check-adapter-upgrade.mjs <before-project-root> <after-project-root>`
+  for disposable project revisions.
+- Validate ordered revisions with
+  `node scripts/check-adapter-upgrade-chain.mjs <chain-root>`.
+- Review the [upgrade evidence contract](docs/adapters/upgrade-evidence.md) before using
+  `--json` or explicit `--output` evidence.
+- Review [evidence bundle verification](docs/evidence-bundles/README.md).
+- Run `node scripts/verify-evidence-bundle.mjs <bundle-file>` for deterministic
+  evidence-bundle replay and regression checks.
+- Run `node scripts/render-evidence-archive-report.mjs <bundle-file>` for a sanitized,
+  read-only archive report summary.
+- Review the [npm package release guide](docs/release/npm-package.md) before running
+  package dry-run or publication checks.
+- Run `node scripts/validate-pack.mjs .` for structural validation.
+- Run `node scripts/test-pack.mjs` for executable release tests.
+- Run `node --test` for built-in Node fixture tests.
+
+Governance lives in [CONTRIBUTING.md](CONTRIBUTING.md), [ROADMAP.md](ROADMAP.md), and the [release policy](docs/release/README.md).
+The [harness guide](docs/testing/README.md) explains trigger, command, mutation, privacy, adapter, and completion checks.
+
+## Autonomous Maintainer Loop
+
+The local maintainer loop reads Git tags, `ROADMAP.md`, `CHANGELOG.md`, and
+`work-ledger.md`, validates the pack, then selects the next bounded milestone. It fails
+closed unless the required action is named explicitly:
+
+```bash
+./scripts/run-next --allow evidence-harness
+```
+
+Supported permissions are `harness-hardening`, `docs-hardening`, `test-hardening`,
+`adapter-harness`, `evidence-harness`, `release-preflight`, `commit`, `tag`, and `push`.
+These flags are approval gates, not permission to weaken shared restrictions.
+
+The runner may update `work-ledger.md` and `runs/skill-runs.md` after a successful bounded
+run. It stops before implementing an unapproved milestone or performing release
+publication. See [the runbook](RUNBOOK.md) and [agent contract](AGENTS.md).

package/ROADMAP.md

@@ -0,0 +1,87 @@
+# Roadmap
+
+The pilot release remains limited to five approved skills. Future work requires separate design and approval.
+
+## Released Harness Milestones
+
+- `v0.1.0`: schemas, examples, dependency-free validation, CI, and governance.
+- `v0.1.1`: trigger, command-policy, mutation, privacy, adapter, and false-completion harnesses.
+- `v0.1.2`: formal adapter contract, compatibility enforcement, and property-style command-policy coverage.
+- `v0.1.3`: bounded external-adapter discovery, validation, fixture roots, and path-safety enforcement.
+- `v0.1.4`: project-owned installation declarations, version pins, and disposable adoption fixtures.
+- `v0.1.5`: paired adapter upgrade checks, stale-pin detection, and compatibility-drift rejection.
+- `v0.1.6`: structured upgrade evidence and multi-step compatibility-chain validation.
+- `v0.2.0`: fail-closed local maintainer loop with an explicit work ledger, run evidence,
+  permission gates, and approval stop boundaries.
+- `v0.2.1`: evidence-bundle verification, deterministic replay hash, and cross-release
+  compatibility regression reporting over disposable evidence fixtures.
+- `v0.2.2`: evidence-bundle retention policy, detached-signature provenance design, and
+  sanitized archive-report rendering.
+- `v0.2.3`: synthetic evidence-bundle archive indexes, retention-expiry advisory
+  reporting, and detached-signature verification planning.
+- `v0.2.4`: adapter-aware `repo-map` renderer that consumes validated project-owned
+  adapters.
+- `v0.2.5`: local `coding-agent-skills` command surface for validated scripts.
+- `v0.2.6`: npm package readiness scaffold with dependency-free package metadata.
+- `v0.2.7`: package-installed `validate-pack` support for tarball/global installs.
+- `v0.2.8`: first public npm release with MIT license, public metadata, and registry
+  install smoke coverage.
+
+The next milestone is recorded in [work-ledger.md](work-ledger.md). The
+[maintainer loop](RUNBOOK.md) may select and evidence that milestone, but it must stop
+before implementation until the relevant human approval is granted.
+
+No evidence-harness milestone is queued after `v0.2.3`. Additional real project adapters,
+new skills, platform work, deployment/preflight work, and signing infrastructure remain
+separately gated. The public npm package exposes the existing read-only CLI surface; it
+does not approve new skills or target-project mutation.
+
+## Planning Gates
+
+- Real-project adapter adoption readiness is documented as a planning-only gate. It
+  defines candidate selection criteria, required pre-adoption evidence, validator commands,
+  safety boundaries, approval gates, stop conditions, rollback conditions, and forbidden
+  work before any real project adapter may be created.
+
+## Real Project Adapter Adoption Evidence
+
+- First external project-owned adapter adoption completed for
+  `/home/oneclickwebsitedesignfactory/tax-lien-platform` at candidate commit
+  `c548b1a6cbb3455a70b89d0e301e22435bfccac9`.
+- Adopted scope: `repo-map` only, docs/metadata-only, no commands, no runtime checks, no
+  build/test/package behavior, no platform/deployment behavior, and no secret-aware
+  behavior.
+- The shared repository still contains only shared schemas, validators, docs, examples,
+  and synthetic fixtures. The real adapter lives in its owning project repository.
+- Publication caveat: the candidate repository's normal pre-push hook attempted package
+  operations. The run was interrupted to preserve the approved boundary, and publication
+  completed with hook verification bypass after shared adapter validation and safe checks
+  passed.
+
+Next safe milestone options:
+
+- Document a project-hook publication policy for future real adapter adoption.
+- Add synthetic fixture coverage for hook-triggered publication caveats.
+- Run a read-only qualification audit for a second candidate.
+- Plan adapter-upgrade evidence review for the adopted `tax-lien-platform` adapter.
+
+| Candidate | Scope | Mode | Current gate |
+|---|---|---|---|
+| `route-trace-skill` | General | Audit-only | Needs design review |
+| `env-audit-skill` | General | Audit-only | Needs more evidence |
+| `secret-audit-skill` | General | Audit-only | Blocked on privacy and approval model |
+| `deployment-preflight-skill` | General | Audit-only | Needs design review |
+| `cloudflare-preflight-skill` | Platform-specific | Audit-only | Needs more evidence |
+| `cloudflare-deploy-skill` | Platform-specific | Action-capable | Blocked on approval model |
+| `supabase-rls-audit-skill` | Platform-specific | Audit-only | Needs more evidence |
+| `migration-review-skill` | General with platform adapters | Audit-only | Needs design review |
+| `api-contract-audit-skill` | General | Audit-only | Needs design review |
+| `repo-knowledge-sync-skill` | General | Action-capable | Blocked on write approval model |
+| `security-hardening-review-skill` | General coordinator | Audit-only | Needs more evidence |
+| `worker-queue-debug-skill` | General core with project adapters | Audit-only first | Needs more evidence |
+| `devvit-ingest-debug-skill` | Project-specific | Audit-only | Needs project evidence |
+| `github-handoff-skill` | Platform-specific | Action-capable | Blocked on approval model |
+| `session-extractor-skill` | General tooling | Action-capable | Blocked on privacy policy and more evidence |
+| `command-redaction-skill` | General tooling | Action-capable | Needs more evidence |
+
+No roadmap item is implicitly approved for implementation.

package/RUNBOOK.md

@@ -0,0 +1,47 @@
+# Maintainer Loop Runbook
+
+The maintainer loop helps an agent choose the next bounded repository milestone from local evidence instead of waiting for a freshly written prompt after every release.
+
+## Normal Flow
+
+1. Start from a clean synchronized `main`.
+2. Read `AGENTS.md`, `ROADMAP.md`, `CHANGELOG.md`, and `work-ledger.md`.
+3. Run the local validation suite.
+4. Ask `./scripts/run-next` to select the next bounded action with an explicit permission flag.
+5. Review the runner evidence in `runs/skill-runs.md`.
+6. Stop at any approval boundary before implementation, release publication, or scope expansion.
+
+## Current Safe Command
+
+```bash
+./scripts/run-next --allow evidence-harness
+```
+
+This command is expected to validate the pack, identify the recommended evidence-harness milestone, write local run evidence, and stop before implementing that milestone.
+
+## Release Validation
+
+Before releasing maintainer-loop changes, run:
+
+```bash
+node scripts/validate-pack.mjs .
+node scripts/test-pack.mjs
+node scripts/validate-maintainer-loop.mjs .
+node --test
+jq empty $(find . -name '*.json' -type f | sort)
+git diff --check
+```
+
+## Stop Boundaries
+
+Stop and request human approval before:
+
+- adding or changing skills
+- creating real project adapters
+- touching real project repositories
+- publishing release artifacts
+- changing credential handling
+- adding package dependencies
+- weakening safety, evidence, completion, or adapter rules
+
+The loop is a decision aid and evidence writer, not a general automation daemon.

package/bin/coding-agent-skills

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const commands = {
+  "validate-pack": {
+    script: "scripts/validate-pack.mjs",
+    args: () => ["."],
+    usage: "coding-agent-skills validate-pack",
+  },
+  "validate-project": {
+    script: "scripts/validate-project-adapters.mjs",
+    args: ([projectRoot]) => [projectRoot],
+    usage: "coding-agent-skills validate-project <project-root>",
+    requiredArgs: 1,
+  },
+  "repo-map": {
+    script: "scripts/render-adapter-repo-map.mjs",
+    args: ([projectRoot]) => [projectRoot],
+    usage: "coding-agent-skills repo-map <project-root>",
+    requiredArgs: 1,
+  },
+  "validate-adapters": {
+    script: "scripts/validate-adapters.mjs",
+    args: ([adapterRoot]) => [adapterRoot],
+    usage: "coding-agent-skills validate-adapters <adapter-root>",
+    requiredArgs: 1,
+  },
+};
+
+function usage(exitCode = 0) {
+  const lines = [
+    "usage: coding-agent-skills <command> [args]",
+    "",
+    "commands:",
+    "  validate-pack",
+    "  validate-project <project-root>",
+    "  repo-map <project-root>",
+    "  validate-adapters <adapter-root>",
+    "",
+    "local-only wrapper; no npm package or global install is implied",
+  ];
+  const stream = exitCode === 0 ? process.stdout : process.stderr;
+  stream.write(`${lines.join("\n")}\n`);
+  process.exitCode = exitCode;
+}
+
+const [commandName, ...args] = process.argv.slice(2);
+if (!commandName || commandName === "help" || commandName === "--help" || commandName === "-h") {
+  usage(commandName ? 0 : 2);
+} else if (!Object.hasOwn(commands, commandName)) {
+  process.stderr.write(`unknown command: ${commandName}\n`);
+  usage(2);
+} else {
+  const command = commands[commandName];
+  if ((command.requiredArgs ?? 0) !== args.length) {
+    process.stderr.write(`usage: ${command.usage}\n`);
+    process.exitCode = 2;
+  } else {
+    const result = spawnSync(
+      process.execPath,
+      [path.join(repoRoot, command.script), ...command.args(args)],
+      {
+        cwd: repoRoot,
+        encoding: "utf8",
+        stdio: "inherit",
+        shell: false,
+      },
+    );
+    process.exitCode = result.status ?? 1;
+  }
+}

package/contracts/evidence-pack/README.md

@@ -0,0 +1,22 @@
+# Evidence-Pack Contract
+
+The evidence pack records what a skill intended to do, what it actually inspected or executed, what changed, and why its final status is justified.
+
+Every invocation emits repository and invocation identity, intent and scope, adapter and environment context, sanitized command records, skipped checks, findings, risks, failures, unresolved questions, an explicit changed-state declaration, status and confidence, and a handoff.
+
+Valid statuses are `complete`, `partial`, `failed`, and `blocked`. Claim `complete` only when all required checks passed or were safely deemed not applicable, no unresolved issue invalidates the objective, and the changed-state declaration is accurate.
+
+Use [evidence-pack.schema.json](evidence-pack.schema.json) for machine validation. The JSON and Markdown examples show equivalent representations.
+
+## Minimum Completion Evidence
+
+- Skill, invocation, and repository identity.
+- Declared scope and adapter.
+- All required command or inspection records.
+- Skipped checks with consequences.
+- Findings, risks, failures, and unresolved questions.
+- Accurate changed-state declaration.
+- Status and confidence reason.
+- Handoff summary and next action.
+
+Audit-only skills must set `changedState.changed` to `false` unless an unexpected mutation is detected; an unexpected mutation prevents `complete`.