coding-agent-skills 0.2.8

package/contracts/evidence-pack/evidence-pack.example.json

@@ -0,0 +1,60 @@
+{
+  "contractVersion": "1.0.0",
+  "skill": {"name": "repo-map", "version": "0.2.3"},
+  "invocation": {
+    "id": "example-repo-map-001",
+    "startedAt": "2026-01-01T12:00:00Z",
+    "endedAt": "2026-01-01T12:02:00Z"
+  },
+  "repository": {
+    "root": "/workspace/example-project",
+    "branch": "main",
+    "head": "0123456789abcdef",
+    "workingTreeState": "dirty"
+  },
+  "userIntent": "Map the repository before changing its API layer.",
+  "declaredScope": ["/workspace/example-project"],
+  "projectAdapter": null,
+  "environmentSummary": {"shell": "bash", "platform": "linux"},
+  "status": "complete",
+  "confidence": {
+    "level": "high",
+    "reason": "Repository identity, manifests, entry points, tests, CI, and documentation were inspected."
+  },
+  "commands": [
+    {
+      "command": "git status --short --branch",
+      "family": "git-status",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-01-01T12:00:10Z",
+      "endedAt": "2026-01-01T12:00:11Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Record branch and working-tree state.",
+      "outputSummary": "Branch main; existing user changes present."
+    }
+  ],
+  "skippedChecks": [],
+  "findings": [
+    {
+      "summary": "The repository contains separate web and API packages.",
+      "evidence": ["package.json", "apps/web/package.json", "apps/api/package.json"]
+    }
+  ],
+  "risks": [
+    {
+      "summary": "The working tree contains pre-existing changes.",
+      "evidence": ["git status --short --branch"]
+    }
+  ],
+  "failures": [],
+  "unresolvedQuestions": [],
+  "changedState": {
+    "changed": false,
+    "summary": "The audit-only skill made no intentional project, Git, runtime, or remote changes."
+  },
+  "handoffSummary": "Repository boundaries and primary validation entry points are mapped.",
+  "recommendedNextAction": "Trace the requested API route before editing."
+}

package/contracts/evidence-pack/evidence-pack.example.md

@@ -0,0 +1,49 @@
+# Evidence Pack
+
+## Scope
+
+- Skill: `repo-map` `0.2.3`
+- Intent: Map the repository before changing its API layer.
+- Scope: `/workspace/example-project`
+- Status: `complete`
+- Confidence: High; repository identity and required structural areas were inspected.
+
+## Repository Identity
+
+- Root: `/workspace/example-project`
+- Branch: `main`
+- HEAD: `0123456789abcdef`
+- Working tree: Dirty with pre-existing user changes
+
+## Checks Performed
+
+| Check | Result | Evidence |
+|---|---|---|
+| Repository identity | Passed | Git root, branch, remote, and HEAD |
+| Structure | Passed | Package and application directories |
+| Tests and CI | Passed | Package scripts and workflow files |
+
+## Skipped Checks
+
+None.
+
+## Findings
+
+- Separate web and API packages exist.
+- Project changes were already present before inspection.
+
+## Risks And Failures
+
+- Preserve the existing working-tree changes.
+
+## Unresolved Questions
+
+None.
+
+## State Change
+
+No intentional project, Git, runtime, dependency, or remote state changed.
+
+## Handoff
+
+The repository is mapped. Trace the requested API route before editing.

package/contracts/evidence-pack/evidence-pack.schema.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coding-agent-skills.local/schemas/evidence-pack.schema.json",
+  "title": "Coding Agent Evidence Pack",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "skill",
+    "invocation",
+    "repository",
+    "userIntent",
+    "declaredScope",
+    "projectAdapter",
+    "environmentSummary",
+    "status",
+    "confidence",
+    "commands",
+    "skippedChecks",
+    "findings",
+    "risks",
+    "failures",
+    "unresolvedQuestions",
+    "changedState",
+    "handoffSummary",
+    "recommendedNextAction"
+  ],
+  "properties": {
+    "contractVersion": {"type": "string", "const": "1.0.0"},
+    "skill": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"}
+      }
+    },
+    "invocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "startedAt", "endedAt"],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "startedAt": {"type": "string", "format": "date-time"},
+        "endedAt": {"type": "string", "format": "date-time"}
+      }
+    },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root", "branch", "head", "workingTreeState"],
+      "properties": {
+        "root": {"type": ["string", "null"]},
+        "branch": {"type": ["string", "null"]},
+        "head": {"type": ["string", "null"]},
+        "workingTreeState": {
+          "type": "string",
+          "enum": ["clean", "dirty", "not-git", "unknown"]
+        }
+      }
+    },
+    "userIntent": {"type": "string", "minLength": 1},
+    "declaredScope": {"type": "array", "items": {"type": "string"}},
+    "projectAdapter": {"type": ["string", "null"]},
+    "environmentSummary": {"type": "object"},
+    "status": {
+      "type": "string",
+      "enum": ["complete", "partial", "failed", "blocked"]
+    },
+    "confidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "reason"],
+      "properties": {
+        "level": {"type": "string", "enum": ["high", "medium", "low"]},
+        "reason": {"type": "string", "minLength": 1}
+      }
+    },
+    "commands": {"type": "array", "items": {"$ref": "#/$defs/commandRecord"}},
+    "skippedChecks": {"type": "array", "items": {"$ref": "#/$defs/skippedCheck"}},
+    "findings": {"type": "array", "items": {"$ref": "#/$defs/note"}},
+    "risks": {"type": "array", "items": {"$ref": "#/$defs/note"}},
+    "failures": {"type": "array", "items": {"$ref": "#/$defs/note"}},
+    "unresolvedQuestions": {"type": "array", "items": {"type": "string"}},
+    "changedState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["changed", "summary"],
+      "properties": {
+        "changed": {"type": "boolean"},
+        "summary": {"type": "string", "minLength": 1}
+      }
+    },
+    "handoffSummary": {"type": "string"},
+    "recommendedNextAction": {"type": ["string", "null"]}
+  },
+  "$defs": {
+    "commandRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "command",
+        "family",
+        "workingDirectory",
+        "startedAt",
+        "endedAt",
+        "exitStatus",
+        "resultStatus",
+        "safetyClass",
+        "approvalReference",
+        "purpose",
+        "outputSummary"
+      ],
+      "properties": {
+        "command": {"type": "string"},
+        "family": {"type": "string"},
+        "workingDirectory": {"type": "string"},
+        "startedAt": {"type": "string", "format": "date-time"},
+        "endedAt": {"type": "string", "format": "date-time"},
+        "exitStatus": {"type": ["integer", "null"]},
+        "resultStatus": {
+          "type": "string",
+          "enum": ["success", "failure", "running", "unknown"]
+        },
+        "safetyClass": {
+          "type": "string",
+          "enum": ["allowed", "approved-exception", "rejected"]
+        },
+        "approvalReference": {"type": ["string", "null"]},
+        "purpose": {"type": "string"},
+        "outputSummary": {"type": "string"}
+      }
+    },
+    "skippedCheck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "reason", "consequence", "completionPermitted"],
+      "properties": {
+        "name": {"type": "string"},
+        "reason": {"type": "string"},
+        "consequence": {"type": "string"},
+        "completionPermitted": {"type": "boolean"}
+      }
+    },
+    "note": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["summary", "evidence"],
+      "properties": {
+        "summary": {"type": "string"},
+        "evidence": {"type": "array", "items": {"type": "string"}}
+      }
+    }
+  }
+}

package/docs/adapters/README.md

@@ -0,0 +1,82 @@
+# Project Adapters
+
+Project-specific adapters live in their owning project repositories, not this shared repository.
+They add bounded project context to a compatible shared skill. They are data, not executable plugins.
+
+Every adapter must validate against [the project-adapter schema](../../schemas/project-adapter.schema.json).
+
+## Convention And Discovery
+
+External discovery is opt-in and bounded to three project-relative locations. Each adapter
+uses the exact manifest name `adapter.json`. See [the discovery convention](discovery.md)
+for path and symlink rules, [external validation](external-adapters.md) for manifest-only
+CLI behavior, and [project installation](project-installation.md) for declaration and
+version-pinning rules. Use [upgrade checks](upgrades.md) to compare two declared revisions
+or a multi-step compatibility chain before changing a real project. The
+[upgrade evidence contract](upgrade-evidence.md) defines sanitized review output. The
+[real project adoption gate](real-project-adoption.md) defines the approval and evidence
+requirements that must be met before any real project adapter is created.
+
+Discovery validates schema, skill compatibility, command policy, and inherited restrictions
+before accepting any extension. It never executes adapter commands.
+
+## Adapter-Aware Repo Map Consumption
+
+The shared pack can consume a validated project-owned adapter as agent context for
+`repo-map` orientation:
+
+```bash
+node scripts/render-adapter-repo-map.mjs <project-root>
+```
+
+The renderer validates the project declaration first, confirms that `repo-map` is enabled,
+then reports only adapter-declared metadata: documentation precedence, safe read paths,
+ignored paths, required evidence, package-manager hints, repository bounds, and sanitized
+Git branch state. It does not read target project file contents, run project tests or
+builds, install packages, perform runtime checks, deploy, migrate, or read `.env` files.
+
+This is agent context for safer repository understanding. It is not target-application
+product behavior.
+
+## What Adapters May Do
+
+- Add bounded relative read paths and ignored paths.
+- Declare project-root markers and a bounded detection depth.
+- Add documentation precedence and package-manager hints.
+- Add command aliases that already satisfy the shared command policy.
+- Add status-only runtime commands and manager hints.
+- Require additional evidence or named approval for exceptional reads.
+
+## What Adapters Must Never Do
+
+- Remove inherited denied-operation categories.
+- Change an audit-only skill into an action-capable skill.
+- Permit deployment, Git publication, installation, migration, or service mutation.
+- Expose secrets or add secret-bearing paths.
+- Suppress failures, contradictions, dirty state, or required evidence.
+- Redefine completion semantics.
+- Expand scanning outside the declared project root without named approval.
+
+## Compatibility And Inheritance
+
+Skill manifests declare the adapter contract and compatible adapter versions. An adapter separately declares supported skill IDs, compatible skill versions, and the unchanged skill mode.
+
+Compatibility requires both declarations to agree. Exact pilot versions and the `0.2.x`
+compatibility form are supported in v0.2.3. Upgrade comparisons also preserve adapter
+identity, inherited restrictions, and required evidence across revisions.
+
+The `inheritance` object is mandatory. Shared restrictions always win, and every permission-like safety flag is fixed to `false`.
+
+The shared skill repository stores only synthetic fixture roots. The first external
+project-owned adapter was adopted in `/home/oneclickwebsitedesignfactory/tax-lien-platform`
+at candidate commit `c548b1a6cbb3455a70b89d0e301e22435bfccac9`. That adapter is
+`repo-map` only, docs/metadata-only, and contains no commands, runtime checks,
+build/test/package behavior, platform behavior, deployment behavior, or secret-aware
+behavior.
+
+During publication, the candidate repository's normal pre-push hook attempted package
+operations, including install, audit, and typecheck. The run was interrupted to preserve
+the approved boundary, validation was kept to the shared adapter validators and safe
+checks, and publication completed with hook verification bypass. Future real-project
+adapter adoption must decide explicitly whether repository hooks are allowed or must be
+bypassed to preserve a no-install/no-build/no-test boundary.

package/docs/adapters/discovery.md

@@ -0,0 +1,50 @@
+# External Adapter Discovery
+
+External adapters are extension-only JSON data stored outside this shared skill repository.
+The discovery harness accepts a confirmed project or fixture root and inspects only these
+relative locations:
+
+```text
+.coding-agent/adapters/
+coding-agent/adapters/
+adapters/coding-agent/
+```
+
+Each immediate child directory represents one adapter and must contain the exact manifest
+filename `adapter.json`. Discovery does not recursively scan the rest of the project.
+
+## Discovery Rules
+
+1. Resolve the supplied root without accepting `..` path traversal.
+2. Inspect only the three declared adapter locations.
+3. Reject adapter containers, directories, or manifests that are symlinks.
+4. Accept only regular `adapter.json` files no larger than the harness limit.
+5. Parse JSON without returning source snippets in errors.
+6. Reject secret-like content before semantic validation.
+7. Validate against adapter schema version `1.0.0`.
+8. Confirm skill ID, skill version, declared mode, command policy, and manifest compatibility.
+9. Apply shared restrictions before every adapter extension.
+10. Return a nonzero exit code when any discovered adapter or container is invalid.
+
+An empty root is valid and reports that zero adapters were discovered. A missing root,
+malformed manifest, unexpected container entry, or mixed valid and invalid root fails.
+
+## Inheritance
+
+Adapters may add bounded read paths, documentation precedence, safe aliases, status-only
+runtime hints, package-manager hints, approvals, and evidence requirements. They remain
+extension-only: shared denied operations, skill modes, evidence requirements, failure
+reporting, completion semantics, secret handling, and scope approval rules always win.
+
+Symlink escapes and path traversal are rejected even when their target would otherwise
+contain a structurally valid adapter.
+
+Project repositories may later reference a versioned checkout or installed copy of this
+shared core. That integration must run the core validator against the project root; it must
+not copy or redefine shared restrictions locally.
+
+The [project installation contract](project-installation.md) defines the declaration and
+version pin required before a project-owned adapter can be considered installed.
+
+No real project adapters are added in v0.2.3. The committed roots are disposable synthetic
+fixtures only.

package/docs/adapters/external-adapters.md

@@ -0,0 +1,42 @@
+# Validating External Adapters
+
+Run the dependency-free validator from the shared core repository:
+
+```bash
+node scripts/validate-adapters.mjs <adapter-root>
+```
+
+The argument is the project or fixture root beneath which the declared discovery locations
+may exist. The validator reads only core schemas and policies plus discovered `adapter.json`
+files. It does not read `.env`, install dependencies, run adapter commands, or change the
+target project.
+
+## Results
+
+- Exit `0`: every discovered adapter is accepted, including the explicit zero-adapter case.
+- Exit `1`: a root, container, manifest, schema, compatibility, inheritance, or path-safety
+  rejection occurred.
+- Exit `2`: the command is missing its required root argument.
+
+Output contains counts, public pilot skill IDs for accepted adapters, and stable rejection
+codes. It does not echo adapter IDs, commands, paths from manifest values, parse snippets,
+or secret-like values.
+
+Common rejection categories include unsupported adapter or skill versions, unsupported
+skill IDs, mode override, restriction weakening, unsafe command alias, secret exposure,
+failure suppression, completion override, required-evidence removal, scope expansion,
+unsafe path, malformed JSON, missing manifest, and symlink escape.
+
+## Fixture Model
+
+Synthetic fixture roots under `tests/fixtures/external-adapters/` exercise all three
+locations, valid adapters, isolated invalid adapters, mixed roots, empty roots, malformed
+input, traversal, and temporary symlink escapes. Fixtures contain no real project details.
+
+Real project adapters remain deferred. When approved later, they should be owned by their
+project repository, declare compatibility with a released shared core, and pass this
+validator without changing shared restrictions.
+
+Manifest-only validation does not prove that a project has declared or pinned the shared
+core. Use the [project installation validator](project-installation.md) for that stronger
+workflow.

package/docs/adapters/project-installation.md

@@ -0,0 +1,135 @@
+# Project-Owned Adapter Installation
+
+A future project repository owns its adapter manifests while the shared repository owns
+schemas, skill manifests, command policies, completion rules, and validators. Installation
+means declaring and validating that relationship; it does not copy or execute adapter code.
+
+## Required Layout
+
+Choose one supported adapter root:
+
+```text
+.coding-agent/adapters/
+coding-agent/adapters/
+adapters/coding-agent/
+```
+
+Each immediate child directory contains one `adapter.json`. The project must also contain
+exactly one declaration:
+
+```text
+.coding-agent/skills.json
+coding-agent.skills.json
+```
+
+Two declarations are ambiguous and fail validation.
+
+## Declaration Contract
+
+The declaration validates against
+[`project-adapter-installation.schema.json`](../../schemas/project-adapter-installation.schema.json).
+It records:
+
+- Declaration and adapter schema versions.
+- Project ID and one supported adapter root.
+- Expected shared core version and an exact pin or compatible range.
+- Compatible pilot skill IDs.
+- Every installed adapter ID, adapter version, and skill set.
+- The validation command template.
+- A repository-relative evidence output location.
+- A repository-relative approval policy reference.
+- An explicit `noSecrets: true` guarantee.
+
+The validation command is declared as:
+
+```text
+node <shared-core>/scripts/validate-project-adapters.mjs <project-root>
+```
+
+The validator checks this field; it does not execute it.
+
+## Version Pinning
+
+Two version pin forms are supported:
+
+```text
+0.2.3
+>=0.2.2 <0.3.0
+```
+
+The expected version must equal the running shared core version. The pin must contain both
+that version and the declared expected version. Missing versions, prefixes, wildcards,
+caret ranges, unsupported old or future versions, and malformed comparators fail closed.
+
+Adapter schema version `1.0.0` and every declared adapter version must match the discovered
+manifest. Skill IDs and modes must remain compatible with the shared pilot manifests.
+
+## Validation Flow
+
+Run:
+
+```bash
+node scripts/validate-project-adapters.mjs <project-root>
+```
+
+The dependency-free validator:
+
+1. Finds exactly one project declaration.
+2. Validates declaration structure and safe relative paths.
+3. Checks the current core version against the exact pin or compatible range.
+4. Runs bounded external adapter discovery.
+5. Matches project ID, adapter root, adapter IDs, versions, and skill IDs.
+6. Applies shared schema, command-policy, inheritance, and path-safety checks.
+7. Returns counts and stable rejection codes without echoing declaration values.
+
+Exit `0` means the project declaration and all installed adapters are compatible. Exit `1`
+means validation failed. Exit `2` means the project-root argument is missing.
+
+## Repo-Map Consumption
+
+After validation passes, a project-owned adapter can be consumed as read-only `repo-map`
+context:
+
+```bash
+node scripts/render-adapter-repo-map.mjs <project-root>
+```
+
+The renderer uses the same project declaration and adapter validation path before it reads
+adapter metadata. It requires `repo-map` compatibility and then renders:
+
+- Documentation precedence.
+- Safe read paths.
+- Ignored paths.
+- Required evidence.
+- Root markers, declared scope, and detection depth.
+- Package-manager hints.
+- Sanitized Git branch state and warnings.
+
+The renderer is metadata-only. It does not read target project file contents, run target
+project tests, run builds, install packages, perform runtime checks, deploy, migrate, read
+`.env` files, or modify project state.
+
+## Safety Boundary
+
+Project adapters are extension-only. They cannot remove denied operations, change an
+audit-only mode, add deployment or publication, suppress failures, redefine completion,
+remove evidence, expose secrets, expand scope without approval, or escape through symlinks
+or traversal.
+
+The validator reads only the declaration, discovered `adapter.json` files, and shared core
+metadata. It ignores unrelated `.env` files and never installs packages, runs adapter
+commands, deploys, migrates, or changes project state.
+
+Use [the upgrade checker](upgrades.md) to compare a current declaration with a proposed
+revision and detect stale pins or compatibility drift before adoption.
+
+Before any real project adapter is created, use the
+[real project adoption gate](real-project-adoption.md) to confirm candidate criteria,
+required evidence, approval gates, stop conditions, and rollback boundaries.
+
+All committed project roots in this shared repository remain disposable synthetic fixtures.
+The first external project-owned adapter was adopted in
+`/home/oneclickwebsitedesignfactory/tax-lien-platform` at candidate commit
+`c548b1a6cbb3455a70b89d0e301e22435bfccac9`. The shared repository still owns the schemas,
+completion rules, command policy, and validators; the project repository owns its adapter
+manifest and declaration.