coding-agent-skills 0.2.8

package/docs/adapters/real-project-adoption.md

@@ -0,0 +1,193 @@
+# Real Project Adapter Adoption Gate
+
+This document defines the planning gate for a future first real project adapter. It does
+not approve creating that adapter, modifying a project repository, or changing the shared
+skill pack's safety model.
+
+The shared repository is ready to evaluate a candidate because it already has bounded
+adapter discovery, project-owned installation declarations, version pinning, upgrade
+checks, compatibility-chain checks, evidence contracts, and release validation. That
+readiness is a gate, not implementation permission.
+
+## Candidate Selection Criteria
+
+A first real project adapter candidate must satisfy all of these conditions before any
+project repository is touched:
+
+- The project owner explicitly approves an adapter-planning review for that repository.
+- The project has a stable repository root and an identifiable owning project.
+- The project can use one supported adapter location:
+  `.coding-agent/adapters/`, `coding-agent/adapters/`, or `adapters/coding-agent/`.
+- The project can declare exactly one installation file: `.coding-agent/skills.json` or
+  `coding-agent.skills.json`.
+- The adapter need is bounded to existing pilot skills: `repo-map`, `build-verify`,
+  `git-preflight`, `runtime-truth`, or `llm-drift-control`.
+- The adapter can narrow context with relative paths, documentation precedence, safe
+  aliases, status-only hints, or extra evidence requirements.
+- The adapter does not require deployment, migration, package installation, Git
+  publication, service mutation, billing, platform credentials, or secret reads.
+- The project has enough public or non-sensitive documentation to justify the adapter
+  without storing raw secrets, private evidence, or local environment values.
+
+If any condition is missing, the candidate remains deferred.
+
+## Required Evidence Before Touching A Real Project
+
+Before creating files in a real project repository, the operator must gather and report
+sanitized evidence from this shared repository only:
+
+- Current shared skill-pack version and tag.
+- Clean or intentionally documented Git state for the shared repository.
+- Candidate project name or approved placeholder, without secrets or local-only paths.
+- Proposed adapter root and declaration-file location.
+- Pilot skill IDs the adapter would support.
+- Proposed extension type, such as read paths, documentation precedence, package-manager
+  hints, status-only runtime hints, or additional evidence.
+- Explicit statement that no new skill, platform workflow, deployment, migration, package
+  publication, or global CLI flow is part of the adoption.
+- Approval record naming whether the next step is read-only review, project-file
+  scaffolding, or implementation.
+
+This evidence must not include `.env` contents, credentials, raw command output with
+private values, or private project internals.
+
+## Required Validator Commands
+
+Before adoption planning can move from this shared repository into a real project, the
+shared pack must pass:
+
+```bash
+node scripts/validate-pack.mjs .
+node scripts/test-pack.mjs
+node scripts/validate-maintainer-loop.mjs .
+node scripts/validate-adapters.mjs tests/fixtures/external-adapters/valid-basic
+node scripts/validate-project-adapters.mjs tests/fixtures/project-adapter-installation/valid-exact-pin
+node scripts/check-adapter-upgrade.mjs tests/fixtures/project-adapter-upgrades/valid-upgrade/before tests/fixtures/project-adapter-upgrades/valid-upgrade/after
+node scripts/check-adapter-upgrade-chain.mjs tests/fixtures/project-adapter-upgrade-chains/valid-chain
+node --test
+```
+
+After a separately approved real adapter is created in its owning project repository, run
+the same shared-pack validation plus the project-specific declaration validation against
+the approved project root. If an existing adapter is being changed, also run the upgrade
+or compatibility-chain check against sanitized before and after revisions.
+
+## Safety Boundaries
+
+Project adapters remain extension-only data. They must never:
+
+- Remove inherited denied-operation categories.
+- Change an audit-only skill into an action-capable skill.
+- Permit deployment, Git publication, installation, migration, service mutation, or
+  privileged API calls.
+- Expose secrets or add secret-bearing paths.
+- Suppress failures, contradictions, dirty state, required evidence, or skipped-check
+  consequences.
+- Redefine completion semantics.
+- Expand scanning outside the approved project root.
+- Read or print `.env` files.
+- Copy shared restrictions into a project in a way that allows local weakening.
+
+The shared core remains authoritative for schemas, command policy, completion rules,
+evidence contracts, and validator behavior.
+
+## Approval Gates
+
+The following approvals are separate:
+
+1. Approve selecting a candidate project for adapter planning.
+2. Approve read-only evidence gathering in that project.
+3. Approve creating project-owned adapter files in that project.
+4. Approve validating the project declaration with the shared core.
+5. Approve committing or publishing project-repository adapter changes.
+6. Approve changing the shared core if adoption reveals a missing generic validator rule.
+
+Approval for one gate does not imply approval for the next gate.
+
+## Stop Conditions
+
+Stop immediately and report if:
+
+- The candidate requires a new skill or platform-specific workflow.
+- The candidate needs deployment, migration, package installation, Git publication, or
+  service mutation.
+- The candidate requires reading or exposing secrets.
+- The project cannot use a supported adapter location or declaration file.
+- The shared validation matrix fails.
+- The adapter would weaken shared restrictions, evidence rules, command policy, or
+  completion semantics.
+- The project owner has not explicitly approved the current gate.
+- The work would require touching a real project repository without separate approval.
+
+## Rollback Conditions
+
+If a separately approved project adapter later fails validation, the operator must stop
+and preserve evidence. Rollback means removing or reverting the project-owned adapter
+change in that project repository under that repository's approval process. This shared
+repository must not silently loosen schemas, validators, or safety rules to make a real
+adapter pass.
+
+## Still Forbidden Until Separately Approved
+
+- New skills.
+- Real project adapter creation.
+- Real project repository modification.
+- Platform or deployment skills.
+- Package publication or root package setup.
+- Global CLI installation flow.
+- Deployments, migrations, service mutations, or privileged API calls.
+- Commit, push, tag, or release publication.
+- Reading or printing `.env` contents.
+
+## First Adoption Evidence
+
+The first external project-owned adapter adoption has completed for
+`/home/oneclickwebsitedesignfactory/tax-lien-platform` at candidate commit
+`c548b1a6cbb3455a70b89d0e301e22435bfccac9`.
+
+The adopted adapter scope is intentionally narrow:
+
+- `repo-map` only.
+- Docs/metadata-only.
+- No commands.
+- No runtime checks.
+- No build, test, or package behavior.
+- No platform, deployment, migration, or service behavior.
+- No secret-aware behavior.
+
+Validation evidence:
+
+- Shared pack validation passed.
+- Shared release tests passed.
+- Maintainer-loop validation passed.
+- Project adapter validation accepted one adapter and one skill with the core pin accepted.
+- Built-in Node tests passed.
+- Shared and candidate whitespace checks passed.
+- Candidate adapter JSON parsed successfully.
+
+Publication caveat: the candidate repository's normal pre-push hook attempted package
+operations, including install, audit, and typecheck. The run was interrupted to preserve
+the approved no-install/no-build/no-test boundary. Publication then completed with hook
+verification bypass after the shared adapter validator and safe checks passed.
+
+Future adoption runs must explicitly decide whether repository hooks are allowed or whether
+hook bypass is required to preserve the approved boundary. Hook bypass does not replace
+adapter validation; it only prevents unapproved project-native package operations.
+
+Remaining approval boundaries:
+
+- Expanding the adapter beyond `repo-map`.
+- Enabling command aliases, build verification, runtime truth, or status checks.
+- Running candidate project package scripts.
+- Inspecting Docker, database, worker, SMTP, migration, deployment, billing, platform, or
+  secret-bearing surfaces.
+- Changing shared schemas, validators, command policy, or completion rules.
+- Creating additional real project adapters.
+
+Next safe milestone options:
+
+- Document the project-hook publication policy for real adapter adoption.
+- Add synthetic fixture coverage for hook-triggered publication caveats without adding
+  real project details.
+- Plan a second read-only candidate qualification audit.
+- Plan a `repo-map` adapter upgrade evidence review for the adopted project adapter.

package/docs/adapters/upgrade-evidence.md

@@ -0,0 +1,67 @@
+# Adapter Upgrade Evidence
+
+The machine-readable contract is
+[`adapter-upgrade-evidence.schema.json`](../../schemas/adapter-upgrade-evidence.schema.json).
+It records a pair or chain review without storing raw project paths, project identifiers,
+environment values, credentials, or upgrade mutations.
+
+## Contract Contents
+
+Every record includes:
+
+- Contract, validator, invocation, and timestamp identity.
+- Sanitized before and after project summaries.
+- Core, adapter, schema, skill, compatibility, and pin information.
+- Restriction inheritance and approval requirements.
+- Risks, failures, warnings, confidence, and recommended action.
+- Final `pass`, `warn`, `fail`, or `blocked` status.
+- An explicit `changedState.changed: false` declaration.
+
+Chain records additionally include a synthetic chain ID and ordinal transition summaries.
+Revision labels such as `revision-1` are evidence-safe placeholders, not directory names.
+
+## Pair Output
+
+Print sanitized JSON:
+
+```bash
+node scripts/check-adapter-upgrade.mjs <before> <after> --json
+```
+
+Write one new JSON evidence file:
+
+```bash
+node scripts/check-adapter-upgrade.mjs <before> <after> --output validation-output/upgrade.json
+```
+
+## Chain Output
+
+Print sanitized JSON:
+
+```bash
+node scripts/check-adapter-upgrade-chain.mjs <chain-root> --json
+```
+
+Write one new JSON evidence file:
+
+```bash
+node scripts/check-adapter-upgrade-chain.mjs <chain-root> --output validation-output/chain.json
+```
+
+Output paths must be relative, end in `.json`, remain beneath the current working directory,
+have an existing non-symlink parent, avoid `.env` components, and identify a file that does
+not already exist. Evidence output never overwrites a file.
+
+The optional report write does not apply an adapter upgrade. The changed-state declaration
+refers to project, adapter, Git, runtime, service, database, and remote state, all of which
+remain unchanged.
+
+## Status Policy
+
+A stale exact pin or stale compatible range is blocking and produces `fail`. So do
+unsupported cores, schema or skill drift, restriction weakening, evidence removal, failure
+suppression, completion override, mode escalation, secret exposure, scope expansion, and
+unsafe paths.
+
+`warn` is reserved for compatible reviews carrying non-blocking approval requirements.
+Passing evidence remains advisory and requires human approval before real-project adoption.

package/docs/adapters/upgrades.md

@@ -0,0 +1,83 @@
+# Adapter Upgrade Checks
+
+Project-owned adapter upgrades are compared as two complete, disposable project revisions:
+
+```bash
+node scripts/check-adapter-upgrade.mjs <before-project-root> <after-project-root>
+```
+
+The command is advisory and read-only. It validates each revision with the existing project
+adapter validator, compares the declarations and accepted manifests, and reports stable
+rejection codes. It does not update pins, copy adapters, install packages, or approve an
+upgrade.
+
+## Revision Convention
+
+Both roots must use the project installation convention in
+[project-installation.md](project-installation.md). The before revision declares its current
+core compatibility. The after revision declares the proposed target compatibility.
+
+For a direct `0.2.3` check, `0.2.2` is the supported upgrade source and `0.2.3` is the target.
+Older sources and future targets fail closed.
+
+## Compatibility Chains
+
+An ordered chain uses contiguous directory names such as:
+
+```text
+01-current/
+02-upgrade/
+03-upgrade/
+```
+
+Run:
+
+```bash
+node scripts/check-adapter-upgrade-chain.mjs <chain-root>
+```
+
+Every revision validates against its declared core. Every adjacent transition reuses the
+pair validator with that transition's target version. Patch versions must advance by one,
+and the final revision must target the running `0.2.3` core. Repeated versions are stale;
+gaps, reversals, old sources, and future targets fail.
+
+## Stale Pins
+
+- A **stale exact pin** still fixes the after revision to an older core.
+- A **stale compatible range** does not include the running core, or leaves the expected
+  version behind while using a range.
+
+The after declaration must set `expectedVersion` to the running core and its `versionPin`
+must contain that version. Exact pins and bounded ranges remain distinct in evidence.
+
+## Safe Upgrade Rules
+
+A safe upgrade must:
+
+- Preserve project and adapter identity.
+- Use the supported adapter schema.
+- Preserve every inherited denied operation.
+- Preserve audit-only modes, failure reporting, completion rules, and secret protections.
+- Retain all previously required evidence; adding evidence is allowed.
+- Declare only approved pilot skills and compatible skill versions.
+- Keep all declaration and manifest paths inside their project revision.
+
+Schema drift, skill compatibility drift, adapter downgrade, restriction weakening, mode
+escalation, evidence removal, failure suppression, completion override, secret exposure,
+scope expansion, traversal, and symlink escape reject the upgrade.
+
+## Evidence And Exit Codes
+
+Exit `0` means the pair or chain validated and preserved the shared boundary. Exit `1`
+means validation was rejected. Exit `2` means usage, output safety, or an internal boundary
+failed. Summaries contain counts and rejection codes only; manifest values are not echoed.
+
+Use `--json` for sanitized machine-readable evidence or `--output <relative-file.json>` to
+write a new evidence artifact. See [upgrade evidence](upgrade-evidence.md) for the
+non-overwriting output policy.
+
+A passing result is evidence that the disposable comparison passed. Applying the same
+upgrade to a real project still requires explicit approval and fresh project evidence.
+
+All committed revisions and chains in this milestone are synthetic fixtures. No real project adapter
+or project repository is read or modified.

package/docs/architecture/README.md

@@ -0,0 +1,23 @@
+# Architecture
+
+The library uses a hybrid model:
+
+- This standalone repository owns general shared skills, contracts, and schemas.
+- Project repositories may own narrow adapters that add local manifests, documentation precedence, ignored paths, or safe detection rules.
+
+Skills consume the evidence-pack contract but do not depend on hidden state. Audit-only and action-capable behavior remain separate. Adapters may only narrow permissions or enrich evidence; shared restrictions and completion rules take precedence.
+
+## Pilot Skills
+
+Audit-only:
+
+- `repo-map`
+- `git-preflight`
+- `runtime-truth`
+- `llm-drift-control`
+
+Controlled local validation:
+
+- `build-verify`
+
+The evidence pack is a shared output contract, not an executable skill. Route tracing, environment and secret audits, deployment preflight, GitHub handoff, provider operations, and project adapters remain separate future work.

package/docs/authoring/README.md

@@ -0,0 +1,54 @@
+# Authoring
+
+New skills must:
+
+1. Define precise trigger conditions in YAML frontmatter.
+2. State whether they are audit-only or action-capable.
+3. Define command families, argument policy, parser invariants, and restricted categories.
+4. Use the shared evidence-pack contract.
+5. Prevent `complete` when required evidence failed or was skipped without an acceptable consequence.
+6. Keep provider and project behavior in explicit adapters.
+7. Include tests for trigger behavior, command policy, mutation prevention, privacy, adapters, and false completion.
+8. Keep `SKILL.md` concise and link directly to detailed companion references.
+9. Use imperative procedures and explicit status transitions.
+10. Validate `agents/openai.yaml` whenever trigger wording changes.
+11. Declare `adapterSchema` and `adapterCompatibility` in the skill manifest.
+12. Add exact and generated property-style command-policy cases.
+
+Do not copy commands from restricted evidence into procedures. Use placeholders instead of private paths, domains, identifiers, or credentials.
+
+Project adapters must validate against `schemas/project-adapter.schema.json`. They may add known paths, script aliases, source precedence, status-only commands, and evidence requirements. They may not weaken restrictions, hide failures, change skill mode, or redefine completion.
+
+Future skills must declare the adapter contract version and compatible adapter versions in their manifest. Adapter compatibility is bidirectional: the manifest must accept the adapter version, and the adapter must accept the skill ID, version, and original mode.
+
+External adapters must use one documented discovery location and an immediate child
+directory containing `adapter.json`. Keep manifests synthetic during shared-core testing.
+Run `node scripts/validate-adapters.mjs <adapter-root>` before proposing a real project
+adapter. Passing schema validation alone is insufficient; compatibility, path safety,
+command aliases, evidence additions, and inherited restrictions must also pass.
+
+A future project adoption must also add exactly one supported skills declaration, pin the
+released shared core, list every adapter ID/version/skill set, retain `noSecrets: true`, and
+pass `node scripts/validate-project-adapters.mjs <project-root>`. A project declaration may
+narrow compatibility but cannot replace the shared schema, policy, mode, or completion rules.
+
+Before proposing an adapter upgrade, retain separate before and after project revisions and
+run `node scripts/check-adapter-upgrade.mjs <before-project-root> <after-project-root>`.
+Update the expected core, pin, and skill compatibility together. Preserve adapter identity,
+all denied categories, and every existing evidence requirement. A passing advisory check
+does not approve modification of a real project.
+
+For multiple revisions, use contiguous ordinal directories and run
+`node scripts/check-adapter-upgrade-chain.mjs <chain-root>`. Produce sanitized evidence with
+`--json` or an explicitly requested relative `--output` file. Validate evidence against
+`schemas/adapter-upgrade-evidence.schema.json`, keep `changedState.changed` false, and never
+store raw project paths, project IDs, `.env` values, credentials, or applied changes.
+
+Evidence bundles must declare retention, expiry-advisory, provenance, archive-index, and
+archive policy metadata. Use `node scripts/verify-evidence-bundle.mjs <bundle-file>` before
+claiming replay or regression success, and use
+`node scripts/render-evidence-archive-report.mjs <bundle-file>` when a sanitized archive
+summary is needed. Do not inline signatures, raw evidence bodies, command output, local
+paths, or secret-like values into archive indexes or reports. Detached-signature
+verification planning is metadata only until a future milestone explicitly approves real
+verification infrastructure.

package/docs/evidence-bundles/README.md

@@ -0,0 +1,94 @@
+# Evidence Bundles
+
+Evidence bundles group already-produced evidence files into a deterministic, read-only
+verification unit.
+
+## What The Harness Verifies
+
+- The bundle matches `schemas/evidence-bundle.schema.json`.
+- The bundle declares a retention policy with a bounded review window, storage class,
+  and redaction rule.
+- The retention policy includes an expiry advisory. The advisory may report `retained`,
+  `review-soon`, or `expired-review-required`, but it is manual-review-only and never
+  deletes or moves evidence.
+- The bundle declares provenance for the producing harness and target tag.
+- The provenance section follows the detached-signature design. Synthetic fixtures may
+  remain unsigned, but non-fixture bundles cannot use that shortcut.
+- The detached-signature section includes a verification plan with required future
+  artifacts. The harness validates the plan but does not perform cryptographic signing or
+  signature verification.
+- The archive policy allows only sanitized JSON summaries, never raw evidence bodies or
+  secret values.
+- The archive policy may link to a synthetic sanitized archive index that records entry
+  identifiers, hashes, retention summary, and provenance summary.
+- Every entry path is relative, local to the bundle, non-symlinked, and not a local
+  environment-file path.
+- Every entry hash matches the declared SHA-256 digest.
+- Evidence-pack entries validate against the shared evidence-pack contract.
+- Adapter-upgrade entries validate against the adapter-upgrade evidence contract.
+- Entry statuses match their declared expected status.
+- Evidence does not claim state mutation.
+- Replay produces the same canonical report hash inside a single verification run.
+- The target release preserves all declared baseline entries without status regression.
+
+## Retention And Provenance
+
+Retention metadata is advisory evidence, not a deletion scheduler. The verifier checks that
+the declared review window is long enough for synthetic fixtures or maintainer release
+evidence and that `retainUntil` is after `generatedAt` by at least the declared minimum
+days. Expiry status is reported as advisory evidence for human review only. It is not a
+deletion system and it does not change retention state.
+
+Provenance is a signed-provenance design contract. The pilot does not create real
+signatures or publish release attestations. It does require the bundle to name the
+producer, source commit, target release tag, canonicalization strategy, digest algorithm,
+and detached-signature policy so future signing can be added without changing the safety
+model. The verification plan names the canonical bundle JSON, detached signature, and
+public verification identity that a future verifier would require. `validatesSignatureNow`
+must remain `false` in this milestone.
+
+## Archive Indexes
+
+Archive indexes are synthetic sanitized fixtures validated against
+`schemas/archive-index.schema.json`. They are metadata-only indexes for bundle review. An
+index may list bundle entry IDs, expected statuses, hashes, retention advisory status, and
+signature-plan status, but it must not contain raw evidence bodies, command output, local
+paths, credentials, or secret-like values.
+
+The verifier checks that the index belongs to the bundle, matches the current entry set,
+preserves entry hashes, links to retention metadata, and declares no state change.
+
+## Archive Reports
+
+Archive reports are sanitized summaries derived from a verified bundle. They include
+bundle identity, entry identifiers, replay hash, regression status, retention metadata,
+retention-expiry advisory status, provenance metadata, detached-signature verification
+planning metadata, and archive-index status. They do not include raw evidence bodies,
+command output, local home paths, credentials, or secret-like values.
+
+```bash
+node scripts/render-evidence-archive-report.mjs tests/fixtures/evidence-bundles/valid-bundle/evidence-bundle.json
+```
+
+Use `--json` to print the structured sanitized report to stdout. The command does not
+write archive files; storing a report remains a separate approval boundary.
+
+## Command
+
+```bash
+node scripts/verify-evidence-bundle.mjs tests/fixtures/evidence-bundles/valid-bundle/evidence-bundle.json
+```
+
+Use `--json` when a caller needs the structured report. The report is sanitized and does
+not include raw evidence bodies or secret values.
+
+## Boundaries
+
+The verifier is an evidence harness only. It does not create skills, install packages,
+write project files, apply upgrades, touch real project repositories, run deployments, run
+migrations, mutate services, read local environment files, or publish releases.
+
+The archive-report renderer follows the same read-only boundary. It renders sanitized
+stdout only and does not create or update archive destinations.
+
+Real project evidence bundles remain deferred until separately approved.

package/docs/privacy/README.md

@@ -0,0 +1,26 @@
+# Evidence Retention And Privacy
+
+## Collection
+
+Collect only evidence required to justify the skill result. Prefer concise summaries and references over raw output.
+
+## Sanitization
+
+Never retain token values, cookies, private keys, authenticated headers, connection strings, private tenant identifiers, or secret-file contents. Replace private paths, domains, emails, and IDs when they are not necessary to understand the result.
+
+## Retention
+
+- Ephemeral command output should remain in the active task unless retention is explicitly required.
+- Persisted evidence packs must be sanitized before writing.
+- Evidence bundles must declare retention, expiry-advisory, archive-index, provenance, and
+  redaction metadata before archive reports are treated as reviewable release evidence.
+- Archive indexes and reports must be sanitized summaries; they must not retain raw
+  evidence bodies, command output, local home paths, credentials, or secret-like values.
+- Validation output belongs in ignored `validation-output/` or `test-results/` directories.
+- Delete temporary authentication helpers immediately after use.
+
+## Local Credentials
+
+Local `.env` files may supply credentials for separately approved operations. Load them without shell tracing, reference environment variables, avoid credential-bearing output, and never commit them.
+
+Recommend credential rotation only when evidence shows printing, copying, committing, pushing, or external exposure.

package/docs/release/README.md

@@ -0,0 +1,42 @@
+# Release Process
+
+## Checklist
+
+1. Confirm only approved skills exist.
+2. Run `node scripts/validate-pack.mjs .`.
+3. Run `node scripts/test-pack.mjs`.
+4. Run `node scripts/validate-maintainer-loop.mjs .`.
+5. Run `node scripts/verify-evidence-bundle.mjs tests/fixtures/evidence-bundles/valid-bundle/evidence-bundle.json`.
+6. Run `node scripts/render-evidence-archive-report.mjs tests/fixtures/evidence-bundles/valid-bundle/evidence-bundle.json`.
+   Confirm the sanitized report includes archive-index status, retention-expiry advisory
+   status, and detached-signature verification planning metadata without raw evidence.
+7. Run `node --test`.
+8. Parse every JSON file.
+9. Run a secret-pattern scan without printing values.
+10. Run `git diff --check`.
+11. Run `npm publish --dry-run --access public --registry=https://registry.npmjs.org/`.
+12. Create a tarball with `npm pack` into a temporary directory.
+13. Inspect tarball contents for local-only files, credentials, `.env` files, dependency
+    folders, generated output, and unrelated repositories.
+14. Install the tarball into a temporary npm prefix and smoke-test the installed CLI.
+15. Review changelog, ledger, run evidence, and versioning impact.
+16. Commit with approved identity.
+17. Push `main` using credential-free remotes.
+18. Confirm a clean synchronized worktree.
+19. Create and push the annotated version tag.
+20. Publish with `npm publish --access public --registry=https://registry.npmjs.org/`.
+21. Install the published package into a temporary prefix and smoke-test the installed CLI.
+22. Create the GitHub Release for the pushed tag.
+
+Deployments, migrations, runtime mutation, platform actions, and target-project builds or
+tests remain outside this release process unless separately approved.
+
+The [npm package release guide](npm-package.md) documents the public package shape,
+dry-run inspection, publication checks, and safety boundaries.
+
+## Maintainer-Loop Boundary
+
+The maintainer loop may run release preflight when `release-preflight` is explicitly
+allowed. The `commit`, `tag`, and `push` permissions represent separate human approval
+boundaries; the initial runner records and stops at those gates rather than publishing
+silently.

package/docs/release/npm-package.md

@@ -0,0 +1,85 @@
+# Npm Package Release
+
+The package is prepared for public npm distribution as a dependency-free CLI wrapper
+around the existing validated scripts. Publication does not change the shared skill
+safety model.
+
+## Current Package Shape
+
+- Package name: `coding-agent-skills`.
+- Package version: `0.2.8`.
+- CLI bin: `coding-agent-skills` mapped to `bin/coding-agent-skills`.
+- Module type: `module`.
+- Dependencies: none.
+- Publication mode: public package on the public npm registry.
+- License metadata: `MIT`.
+- Node requirement: `>=20`.
+
+Install globally with:
+
+```bash
+npm install -g coding-agent-skills
+```
+
+The supported installed commands are:
+
+```bash
+coding-agent-skills validate-pack
+coding-agent-skills validate-project /path/to/project
+coding-agent-skills repo-map /path/to/project
+coding-agent-skills validate-adapters /path/to/adapter-root
+```
+
+The package can also be executed without a repo-local install:
+
+```bash
+npx coding-agent-skills validate-pack
+```
+
+Adapter compatibility remains controlled by the existing shared core and
+project-adapter validators.
+
+`coding-agent-skills validate-pack` is package-aware. In a source checkout, it keeps
+source-only checks such as `.gitignore` validation. In an installed package tree, where
+`.gitignore` is not packaged, it validates the package metadata, strict `files`
+allowlist, dependency-free shape, bin mapping, required packaged files, and absence of
+environment files instead of silently skipping safety checks.
+
+## Included Files
+
+The package uses a strict `files` allowlist. It includes the local command wrapper,
+scripts, skills, schemas, contracts, docs, examples, tests, and governance files needed
+for `coding-agent-skills validate-pack` to work after packaging.
+
+The allowlist intentionally excludes local environment files, Git internals, generated
+validation output, dependency folders, and project-specific adapters.
+
+## Dry-Run And Publish Checks
+
+Before publication, run the dry-run package inspection:
+
+```bash
+npm pack --dry-run
+npm publish --dry-run --access public --registry=https://registry.npmjs.org/
+```
+
+The dry-run output must be reviewed for accidental secrets, local-only files, environment
+files, dependency folders, build artifacts, generated validation output, or unrelated
+project files. It must also confirm that the bin wrapper and validation inputs are
+included.
+
+## Safety Boundaries
+
+The public CLI remains read-only for target projects unless a specific underlying skill
+already permits a bounded local validation action. The installed `repo-map` and adapter
+flows do not:
+
+- deploy
+- run migrations
+- mutate runtime services or processes
+- read `.env` or secret files
+- run target project builds or tests
+- grant adapters additional power
+
+Project adapters narrow context for safer repository understanding; they do not weaken
+shared restrictions or authorize additional command families.