coding-agent-skills 0.2.8

package/examples/command-policies/git-preflight.json

@@ -0,0 +1,44 @@
+{
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "parserPolicy": {
+    "inspectEverySegment": true,
+    "inspectScriptBodies": true,
+    "rejectUnknownExecutables": true,
+    "rejectShellWrappers": true,
+    "rejectHeredocs": true,
+    "rejectRedirection": true,
+    "providerSpecificNpx": true,
+    "authenticatedCurlRequiresApproval": true,
+    "boundedReadsRequired": true,
+    "allowedComposition": "read-only"
+  },
+  "allowedFamilies": [
+    {
+      "name": "git-read-only",
+      "executables": ["git"],
+      "argumentPolicy": {
+        "strategy": "exact",
+        "allowedPatterns": ["rev-parse, remote -v, branch, bounded log, status, diff, ls-files, and show"],
+        "deniedPatterns": ["configuration, index, worktree, history, tag, and remote mutation"]
+      },
+      "constraints": [
+        "Allow rev-parse, remote -v, branch --show-current, bounded log, status, and diff inspection.",
+        "Reject configuration changes and every worktree, index, history, or remote mutation."
+      ]
+    }
+  ],
+  "restrictedCategories": [
+    "file-write",
+    "package-install",
+    "deployment",
+    "git-mutation",
+    "unrestricted-scan",
+    "secret-read",
+    "process-mutation",
+    "service-mutation",
+    "migration-apply",
+    "privileged-api"
+  ],
+  "approvalExceptions": []
+}

package/examples/command-policies/llm-drift-control.json

@@ -0,0 +1,45 @@
+{
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "parserPolicy": {
+    "inspectEverySegment": true,
+    "inspectScriptBodies": true,
+    "rejectUnknownExecutables": true,
+    "rejectShellWrappers": true,
+    "rejectHeredocs": true,
+    "rejectRedirection": true,
+    "providerSpecificNpx": true,
+    "authenticatedCurlRequiresApproval": true,
+    "boundedReadsRequired": true,
+    "allowedComposition": "read-only"
+  },
+  "allowedFamilies": [
+    {
+      "name": "bounded-evidence-read",
+      "executables": ["rg", "sed", "head", "jq", "git"],
+      "argumentPolicy": {
+        "strategy": "pattern",
+        "allowedPatterns": ["bounded documentation, source, test, and read-only Git evidence"],
+        "deniedPatterns": ["writes, generated rewrites, secrets, runtime mutation, and publication"]
+      },
+      "constraints": [
+        "Read only declared documentation, source, tests, and Git evidence.",
+        "Inspect repository drift scripts before running them.",
+        "Reject any script that writes or changes external state."
+      ]
+    }
+  ],
+  "restrictedCategories": [
+    "file-write",
+    "package-install",
+    "deployment",
+    "git-mutation",
+    "unrestricted-scan",
+    "secret-read",
+    "process-mutation",
+    "service-mutation",
+    "migration-apply",
+    "privileged-api"
+  ],
+  "approvalExceptions": []
+}

package/examples/command-policies/repo-map.json

@@ -0,0 +1,59 @@
+{
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "parserPolicy": {
+    "inspectEverySegment": true,
+    "inspectScriptBodies": true,
+    "rejectUnknownExecutables": true,
+    "rejectShellWrappers": true,
+    "rejectHeredocs": true,
+    "rejectRedirection": true,
+    "providerSpecificNpx": true,
+    "authenticatedCurlRequiresApproval": true,
+    "boundedReadsRequired": true,
+    "allowedComposition": "read-only"
+  },
+  "allowedFamilies": [
+    {
+      "name": "bounded-file-inspection",
+      "executables": ["pwd", "ls", "rg", "find", "sed", "head"],
+      "argumentPolicy": {
+        "strategy": "pattern",
+        "allowedPatterns": ["bounded repository-local inspection"],
+        "deniedPatterns": ["absolute home paths, secret files, and unbounded traversal"]
+      },
+      "constraints": [
+        "Remain inside the declared repository scope.",
+        "Bound traversal depth and output.",
+        "Exclude secret-bearing and generated directories."
+      ]
+    },
+    {
+      "name": "git-identity-inspection",
+      "executables": ["git"],
+      "argumentPolicy": {
+        "strategy": "exact",
+        "allowedPatterns": ["rev-parse, remote -v, and status --short --branch"],
+        "deniedPatterns": ["all Git mutation and publication subcommands"]
+      },
+      "constraints": [
+        "Allow only rev-parse, remote -v, and status --short --branch."
+      ]
+    }
+  ],
+  "restrictedCategories": [
+    "file-write",
+    "package-install",
+    "deployment",
+    "git-mutation",
+    "unrestricted-scan",
+    "secret-read",
+    "process-mutation",
+    "service-mutation",
+    "migration-apply",
+    "privileged-api"
+  ],
+  "approvalExceptions": [
+    "A named-file approval may permit one otherwise excluded non-mutating read."
+  ]
+}

package/examples/command-policies/runtime-truth.json

@@ -0,0 +1,59 @@
+{
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "parserPolicy": {
+    "inspectEverySegment": true,
+    "inspectScriptBodies": true,
+    "rejectUnknownExecutables": true,
+    "rejectShellWrappers": true,
+    "rejectHeredocs": true,
+    "rejectRedirection": true,
+    "providerSpecificNpx": true,
+    "authenticatedCurlRequiresApproval": true,
+    "boundedReadsRequired": true,
+    "allowedComposition": "read-only"
+  },
+  "allowedFamilies": [
+    {
+      "name": "runtime-status",
+      "executables": ["ps", "ss", "systemctl", "pm2", "docker"],
+      "argumentPolicy": {
+        "strategy": "status-only",
+        "allowedPatterns": ["bounded process, listener, service, manager, and container status"],
+        "deniedPatterns": ["start, stop, restart, reload, enable, disable, signals, and unbounded logs"]
+      },
+      "constraints": [
+        "Use status and inspection forms only.",
+        "Filter output to the named process, service, container, or port."
+      ]
+    },
+    {
+      "name": "safe-health-check",
+      "executables": ["curl"],
+      "argumentPolicy": {
+        "strategy": "pattern",
+        "allowedPatterns": ["unauthenticated HTTP GET to localhost health paths"],
+        "deniedPatterns": ["authorization, credentials, request bodies, uploads, and non-health endpoints"]
+      },
+      "constraints": [
+        "Use only unauthenticated local or explicitly approved public health endpoints.",
+        "Do not send credentials, cookies, or mutation methods."
+      ]
+    }
+  ],
+  "restrictedCategories": [
+    "file-write",
+    "package-install",
+    "deployment",
+    "git-mutation",
+    "unrestricted-scan",
+    "secret-read",
+    "process-mutation",
+    "service-mutation",
+    "migration-apply",
+    "privileged-api"
+  ],
+  "approvalExceptions": [
+    "A named public health endpoint or bounded non-secret log may be approved."
+  ]
+}

package/examples/evidence-packs/README.md

@@ -0,0 +1,3 @@
+# Evidence-Pack Examples
+
+The directory contains four audit-only results and one controlled local-validation result.

package/examples/evidence-packs/build-verify.json

@@ -0,0 +1,68 @@
+{
+  "contractVersion": "1.0.0",
+  "skill": {"name": "build-verify", "version": "0.2.3"},
+  "invocation": {
+    "id": "example-build-verify",
+    "startedAt": "2026-06-12T11:00:00Z",
+    "endedAt": "2026-06-12T11:04:00Z"
+  },
+  "repository": {
+    "root": "/workspace/example-project",
+    "branch": "feature/example",
+    "head": "1234567890abcdef",
+    "workingTreeState": "dirty"
+  },
+  "userIntent": "Run the project's existing local validation checks.",
+  "declaredScope": ["src/", "test/"],
+  "projectAdapter": null,
+  "environmentSummary": {"platform": "linux", "runtime": "node"},
+  "status": "complete",
+  "confidence": {
+    "level": "high",
+    "reason": "All required discovered checks completed successfully."
+  },
+  "commands": [
+    {
+      "command": "npm run typecheck",
+      "family": "project-native-validation",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-06-12T11:00:30Z",
+      "endedAt": "2026-06-12T11:01:10Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Validate static types.",
+      "outputSummary": "Typecheck completed successfully."
+    },
+    {
+      "command": "npm run test",
+      "family": "project-native-validation",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-06-12T11:01:20Z",
+      "endedAt": "2026-06-12T11:03:40Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Run the project's existing test suite.",
+      "outputSummary": "All tests passed."
+    }
+  ],
+  "skippedChecks": [],
+  "findings": [
+    {
+      "summary": "Required local validation passed.",
+      "evidence": ["typecheck exit 0", "test exit 0"]
+    }
+  ],
+  "risks": [],
+  "failures": [],
+  "unresolvedQuestions": [],
+  "changedState": {
+    "changed": false,
+    "summary": "Validation produced no observed tracked or untracked file changes."
+  },
+  "handoffSummary": "The changed scope passed required local validation.",
+  "recommendedNextAction": "Run Git preflight before handoff."
+}

package/examples/evidence-packs/git-preflight.json

@@ -0,0 +1,55 @@
+{
+  "contractVersion": "1.0.0",
+  "skill": {"name": "git-preflight", "version": "0.2.3"},
+  "invocation": {
+    "id": "example-git-preflight",
+    "startedAt": "2026-06-12T12:00:00Z",
+    "endedAt": "2026-06-12T12:01:00Z"
+  },
+  "repository": {
+    "root": "/workspace/example-project",
+    "branch": "feature/example",
+    "head": "2345678901abcdef",
+    "workingTreeState": "dirty"
+  },
+  "userIntent": "Assess whether the working tree is ready for handoff.",
+  "declaredScope": ["src/example.js", "test/example.test.js"],
+  "projectAdapter": null,
+  "environmentSummary": {"platform": "linux", "git": "available"},
+  "status": "complete",
+  "confidence": {
+    "level": "high",
+    "reason": "Branch, HEAD, staged state, file scope, and whitespace were inspected."
+  },
+  "commands": [
+    {
+      "command": "git diff --check",
+      "family": "git-read-only",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-06-12T12:00:20Z",
+      "endedAt": "2026-06-12T12:00:21Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Check whitespace and patch formatting.",
+      "outputSummary": "No whitespace errors."
+    }
+  ],
+  "skippedChecks": [],
+  "findings": [
+    {
+      "summary": "Observed files match the declared task scope.",
+      "evidence": ["src/example.js", "test/example.test.js"]
+    }
+  ],
+  "risks": [],
+  "failures": [],
+  "unresolvedQuestions": [],
+  "changedState": {
+    "changed": false,
+    "summary": "No Git or working-tree state changed."
+  },
+  "handoffSummary": "Git state is understood and no scope mismatch was found.",
+  "recommendedNextAction": "Proceed to a separately approved handoff workflow."
+}

package/examples/evidence-packs/llm-drift-control.json

@@ -0,0 +1,55 @@
+{
+  "contractVersion": "1.0.0",
+  "skill": {"name": "llm-drift-control", "version": "0.2.3"},
+  "invocation": {
+    "id": "example-llm-drift-control",
+    "startedAt": "2026-06-12T14:00:00Z",
+    "endedAt": "2026-06-12T14:03:00Z"
+  },
+  "repository": {
+    "root": "/workspace/example-project",
+    "branch": "main",
+    "head": "4567890123abcdef",
+    "workingTreeState": "clean"
+  },
+  "userIntent": "Verify the claim that the API capability is implemented.",
+  "declaredScope": ["README.md", "src/api/", "test/api/"],
+  "projectAdapter": null,
+  "environmentSummary": {"platform": "linux", "evidenceWindow": "current branch"},
+  "status": "complete",
+  "confidence": {
+    "level": "high",
+    "reason": "Documentation, source, and tests consistently support the classified claim."
+  },
+  "commands": [
+    {
+      "command": "rg -n \"exampleCapability\" README.md src test",
+      "family": "bounded-evidence-read",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-06-12T14:00:30Z",
+      "endedAt": "2026-06-12T14:00:31Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Locate claim evidence in documentation, source, and tests.",
+      "outputSummary": "The capability appears in all three source types."
+    }
+  ],
+  "skippedChecks": [],
+  "findings": [
+    {
+      "summary": "Claim classified as confirmed.",
+      "evidence": ["README.md", "src/api/example.js", "test/api/example.test.js"]
+    }
+  ],
+  "risks": [],
+  "failures": [],
+  "unresolvedQuestions": [],
+  "changedState": {
+    "changed": false,
+    "summary": "No documentation, source, test, Git, runtime, or remote state changed."
+  },
+  "handoffSummary": "The scoped capability claim is confirmed on the current branch.",
+  "recommendedNextAction": null
+}

package/examples/evidence-packs/repo-map.json

@@ -0,0 +1,55 @@
+{
+  "contractVersion": "1.0.0",
+  "skill": {"name": "repo-map", "version": "0.2.3"},
+  "invocation": {
+    "id": "example-repo-map",
+    "startedAt": "2026-06-12T10:00:00Z",
+    "endedAt": "2026-06-12T10:02:00Z"
+  },
+  "repository": {
+    "root": "/workspace/example-project",
+    "branch": "main",
+    "head": "0123456789abcdef",
+    "workingTreeState": "clean"
+  },
+  "userIntent": "Map the repository before planning an API change.",
+  "declaredScope": ["/workspace/example-project"],
+  "projectAdapter": null,
+  "environmentSummary": {"platform": "linux", "shell": "bash"},
+  "status": "complete",
+  "confidence": {
+    "level": "high",
+    "reason": "Repository identity, structure, manifests, tests, CI, and documentation were inspected."
+  },
+  "commands": [
+    {
+      "command": "git status --short --branch",
+      "family": "git-identity-inspection",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-06-12T10:00:20Z",
+      "endedAt": "2026-06-12T10:00:21Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Record branch and working-tree state.",
+      "outputSummary": "Branch main; working tree clean."
+    }
+  ],
+  "skippedChecks": [],
+  "findings": [
+    {
+      "summary": "The project has separate application, test, and documentation areas.",
+      "evidence": ["package.json", "src/", "test/", "docs/"]
+    }
+  ],
+  "risks": [],
+  "failures": [],
+  "unresolvedQuestions": [],
+  "changedState": {
+    "changed": false,
+    "summary": "No project, Git, dependency, runtime, or remote state changed."
+  },
+  "handoffSummary": "Repository identity and major structural boundaries are mapped.",
+  "recommendedNextAction": "Trace the affected API route before editing."
+}

package/examples/evidence-packs/runtime-truth.json

@@ -0,0 +1,55 @@
+{
+  "contractVersion": "1.0.0",
+  "skill": {"name": "runtime-truth", "version": "0.2.3"},
+  "invocation": {
+    "id": "example-runtime-truth",
+    "startedAt": "2026-06-12T13:00:00Z",
+    "endedAt": "2026-06-12T13:01:30Z"
+  },
+  "repository": {
+    "root": "/workspace/example-project",
+    "branch": "main",
+    "head": "3456789012abcdef",
+    "workingTreeState": "clean"
+  },
+  "userIntent": "Determine whether the local service is running and healthy.",
+  "declaredScope": ["local process", "TCP port 3000", "local health endpoint"],
+  "projectAdapter": null,
+  "environmentSummary": {"platform": "linux", "environment": "local"},
+  "status": "complete",
+  "confidence": {
+    "level": "high",
+    "reason": "Process, listener, and unauthenticated health evidence agreed."
+  },
+  "commands": [
+    {
+      "command": "curl -sS http://127.0.0.1:3000/health",
+      "family": "safe-health-check",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-06-12T13:00:50Z",
+      "endedAt": "2026-06-12T13:00:51Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Check the unauthenticated local health endpoint.",
+      "outputSummary": "Endpoint returned a healthy status."
+    }
+  ],
+  "skippedChecks": [],
+  "findings": [
+    {
+      "summary": "The intended process owns the expected listener and reports healthy.",
+      "evidence": ["process inspection", "listener inspection", "local health response"]
+    }
+  ],
+  "risks": [],
+  "failures": [],
+  "unresolvedQuestions": [],
+  "changedState": {
+    "changed": false,
+    "summary": "No process, service, secret, repository, or remote state changed."
+  },
+  "handoffSummary": "The local service is running, reachable, and healthy.",
+  "recommendedNextAction": null
+}

package/examples/manifests/README.md

@@ -0,0 +1,3 @@
+# Manifest Examples
+
+One schema-valid manifest is provided for each approved pilot skill.

package/examples/manifests/build-verify.json

@@ -0,0 +1,14 @@
+{
+  "name": "build-verify",
+  "version": "0.2.3",
+  "mode": "action-capable",
+  "evidenceContract": "../../contracts/evidence-pack/evidence-pack.schema.json",
+  "commandPolicy": "../command-policies/build-verify.json",
+  "adapterSchema": "../../schemas/project-adapter.schema.json",
+  "adapterCompatibility": {
+    "contractVersion": "1.0.0",
+    "compatibleAdapterVersions": ["1.0.0"]
+  },
+  "adapterInterface": "../../skills/build-verify/adapter-interface.md",
+  "description": "Run discovered project-native local validation commands."
+}

package/examples/manifests/git-preflight.json

@@ -0,0 +1,14 @@
+{
+  "name": "git-preflight",
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "evidenceContract": "../../contracts/evidence-pack/evidence-pack.schema.json",
+  "commandPolicy": "../command-policies/git-preflight.json",
+  "adapterSchema": "../../schemas/project-adapter.schema.json",
+  "adapterCompatibility": {
+    "contractVersion": "1.0.0",
+    "compatibleAdapterVersions": ["1.0.0"]
+  },
+  "adapterInterface": "../../skills/git-preflight/adapter-interface.md",
+  "description": "Inspect Git handoff readiness without changing Git state."
+}

package/examples/manifests/llm-drift-control.json

@@ -0,0 +1,14 @@
+{
+  "name": "llm-drift-control",
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "evidenceContract": "../../contracts/evidence-pack/evidence-pack.schema.json",
+  "commandPolicy": "../command-policies/llm-drift-control.json",
+  "adapterSchema": "../../schemas/project-adapter.schema.json",
+  "adapterCompatibility": {
+    "contractVersion": "1.0.0",
+    "compatibleAdapterVersions": ["1.0.0"]
+  },
+  "adapterInterface": "../../skills/llm-drift-control/adapter-interface.md",
+  "description": "Classify project claims against bounded repository evidence."
+}

package/examples/manifests/repo-map.json

@@ -0,0 +1,14 @@
+{
+  "name": "repo-map",
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "evidenceContract": "../../contracts/evidence-pack/evidence-pack.schema.json",
+  "commandPolicy": "../command-policies/repo-map.json",
+  "adapterSchema": "../../schemas/project-adapter.schema.json",
+  "adapterCompatibility": {
+    "contractVersion": "1.0.0",
+    "compatibleAdapterVersions": ["1.0.0"]
+  },
+  "adapterInterface": "../../skills/repo-map/adapter-interface.md",
+  "description": "Map repository identity and structure without mutation."
+}

package/examples/manifests/runtime-truth.json

@@ -0,0 +1,14 @@
+{
+  "name": "runtime-truth",
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "evidenceContract": "../../contracts/evidence-pack/evidence-pack.schema.json",
+  "commandPolicy": "../command-policies/runtime-truth.json",
+  "adapterSchema": "../../schemas/project-adapter.schema.json",
+  "adapterCompatibility": {
+    "contractVersion": "1.0.0",
+    "compatibleAdapterVersions": ["1.0.0"]
+  },
+  "adapterInterface": "../../skills/runtime-truth/adapter-interface.md",
+  "description": "Correlate process, listener, and unauthenticated health evidence."
+}

package/examples/upgrade-evidence/README.md

@@ -0,0 +1,14 @@
+# Upgrade Evidence Examples
+
+These records are synthetic examples of the
+[adapter upgrade evidence contract](../../schemas/adapter-upgrade-evidence.schema.json).
+
+- `valid-upgrade.evidence.json`: accepted adjacent upgrade.
+- `stale-pin.evidence.json`: stale exact pin rejected.
+- `unsafe-upgrade.evidence.json`: restriction weakening rejected.
+- `chain-pass.evidence.json`: three compatible revisions accepted.
+- `chain-fail.evidence.json`: a chain containing policy weakening rejected.
+
+The Markdown files demonstrate safe human summaries. JSON is authoritative for schema
+validation. Examples contain no filesystem paths, project IDs, credentials, or real
+repository details, and every `changedState.changed` value is `false`.