coding-agent-skills 0.2.8

package/skills/runtime-truth/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: runtime-truth
+description: Audit what is actually running by correlating process-manager status, process identity, network listeners, and unauthenticated health endpoints. Use when configured, deployed, running, reachable, and healthy states may differ; never start, stop, restart, enable, kill, deploy, load secrets, or call authenticated or privileged APIs.
+---
+
+# Runtime Truth
+
+Distinguish configuration from observed runtime state. Remain audit-only.
+
+## Purpose And Use
+
+Use when configured, deployed, running, listening, reachable, and healthy may differ. Do not use to start, repair, restart, deploy, authenticate, or administer the runtime.
+
+## Inputs
+
+Require the service or process hint and intended environment. Optionally accept expected port, local unauthenticated health URL, process manager, expected executable, and project adapter.
+
+Do not assume a configured service is running, a running process owns the expected port, a listener is healthy, or a successful HTTP response came from the intended build.
+
+## Command Policy
+
+Permit bounded status inspection:
+
+- process listings filtered to the named service
+- listener inspection for expected ports
+- `systemctl status` or `systemctl --user status`
+- `pm2 list` or equivalent status-only views
+- container status inspection without lifecycle changes
+- unauthenticated `http://127.0.0.1` or explicitly approved public health checks
+
+Do not start, stop, restart, reload, enable, disable, kill, signal, deploy, tail unbounded logs, source `.env`, print environment values, or call authenticated or privileged endpoints.
+
+This is audit-only behavior. A status tool is allowed only in its non-mutating form.
+
+## Procedure
+
+1. Record expected service, manager, executable, port, and health endpoint.
+2. Inspect configured status without changing manager state.
+3. Inspect matching processes and start times.
+4. Inspect expected listeners and owning processes.
+5. Call only safe unauthenticated health endpoints.
+6. Correlate manager, process, listener, and HTTP evidence.
+7. Classify configured, stopped, running, listening, reachable, healthy, degraded, conflicting, or unverifiable state.
+8. Emit the shared evidence pack.
+
+Use [checklist.md](checklist.md), [failure-modes.md](failure-modes.md), [adapter-interface.md](adapter-interface.md), [examples.md](examples.md), and [evidence-template.md](evidence-template.md).
+
+## Evidence, Recovery, And Dependencies
+
+Emit manager, process, listener, health, timestamp, contradiction, inaccessible-layer, confidence, and changed-state evidence. Recover from unavailable managers, permissions, ownership ambiguity, or authentication requirements by checking remaining read-only layers and lowering confidence; never mutate or load secrets.
+
+Depend on repository/runtime identity inputs and the evidence-pack contract; `repo-map` evidence is useful but optional. Adapters may add status-only commands and safe health endpoints but cannot add lifecycle actions. Safe usage checks a local health endpoint and listener; unsafe usage restarts a service or loads credentials.
+
+## Approval Boundary
+
+Named approval may allow one non-secret log or public health location. It does not permit service mutation, secret loading, authenticated APIs, or process signals.
+
+## Completion
+
+Claim `complete` only when all applicable runtime layers were checked or safely declared unavailable, contradictions are reported, and no state changed. Otherwise use `partial`, `failed`, or `blocked`.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/runtime-truth/adapter-interface.md

@@ -0,0 +1,7 @@
+# Project Adapter Interface
+
+Validate adapters against `../../schemas/project-adapter.schema.json` and confirm manifest compatibility before applying them.
+
+An adapter may declare service names, status-only manager commands, expected executables, ports, safe unauthenticated health endpoints, bounded non-secret log locations, and state-classification hints.
+
+It cannot permit lifecycle commands, signals, deployments, secret loading, authenticated APIs, or suppression of contradictory evidence.

package/skills/runtime-truth/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Runtime Truth"
+  short_description: "Verify process, listener, and health state without mutation"
+  default_prompt: "Inspect process managers, listeners, and unauthenticated health endpoints to report what is actually running without changing runtime state."

package/skills/runtime-truth/checklist.md

@@ -0,0 +1,11 @@
+# Runtime Truth Checklist
+
+- [ ] Record expected service, manager, executable, port, and health endpoint.
+- [ ] Inspect manager status without mutation.
+- [ ] Inspect matching processes and start times.
+- [ ] Inspect expected listeners and owners.
+- [ ] Call only unauthenticated safe health endpoints.
+- [ ] Correlate configuration, manager, process, listener, and HTTP evidence.
+- [ ] Report conflicts and stale processes.
+- [ ] Confirm no process, service, secret, or remote state changed.
+- [ ] Emit timestamped runtime evidence.

package/skills/runtime-truth/evidence-template.md

@@ -0,0 +1,12 @@
+# Runtime Truth Evidence
+
+Include:
+
+- Expected runtime identity and environment.
+- Manager status.
+- Matching process identity and start time.
+- Listener and owning-process evidence.
+- Health request status and concise response summary.
+- Correlated state classification.
+- Contradictions, inaccessible layers, confidence, and collection timestamp.
+- Mutation declaration.

package/skills/runtime-truth/examples.md

@@ -0,0 +1,20 @@
+# Examples
+
+## Safe
+
+- "Is the local API actually running and healthy?"
+- `ss -lntp`
+- `systemctl --user status <service> --no-pager`
+- `pm2 list`
+- `curl -sS http://127.0.0.1:<port>/health`
+
+Use filters and bounded output whenever possible.
+
+## Unsafe
+
+- "Restart it if unhealthy."
+- "Load `.env` and call the admin endpoint."
+- "Kill the old process and redeploy."
+- "Enable the service at boot."
+
+Report the required action without performing it.

package/skills/runtime-truth/failure-modes.md

@@ -0,0 +1,13 @@
+# Failure Modes
+
+| Failure | Recovery |
+|---|---|
+| Manager is unavailable | Inspect process/listener layers and lower confidence |
+| Permission denied | Do not escalate automatically; record inaccessible evidence |
+| Expected port has another owner | Report conflict without terminating it |
+| Health endpoint requires authentication | Skip it; do not load secrets |
+| HTTP succeeds but process identity is unclear | Classify reachable but ownership unverifiable |
+| Manager says running but no listener exists | Classify degraded or contradictory |
+| Endpoint times out | Record failure and preserve other layer evidence |
+
+Recovery never changes runtime state.

package/tests/README.md

@@ -0,0 +1,44 @@
+# Tests
+
+Run the dependency-free release suite with:
+
+`node scripts/test-pack.mjs`
+
+The current suite verifies 63 release conditions, including:
+
+- The exact approved five-skill inventory.
+- Manifest, command-policy, and evidence-pack schema validity.
+- Manifest reference resolution and mode agreement.
+- The single action-capable skill boundary.
+- Complete restricted-category coverage.
+- Audit-only no-change evidence.
+- Semantic rejection of false `complete` claims.
+- Adapter extension without restriction weakening.
+- Audit-only agent prompt boundaries.
+- Restricted-operation rejection in executable examples.
+- A synthetic dependency-free repository fixture.
+- Required `.gitignore` protections.
+- Positive, negative, and wrong-skill trigger classification.
+- Obvious shell-policy bypasses without claiming full POSIX parsing.
+- Audit-only documentation mutation checks and content snapshots.
+- Synthetic sensitive-shape detection and redaction.
+- Adapter permission, failure, completion, secret, and mode overrides.
+- Formal adapter schema and bidirectional compatibility.
+- External adapter discovery across all supported locations.
+- Mixed, empty, missing, malformed, traversal, symlink, and secret-file behavior.
+- Stable adapter CLI exit codes and safe summaries.
+- Project declaration schema, exact pins, compatible ranges, and multiple adapters.
+- Project installation rejection for stale versions, mismatches, unsafe paths, and weakening.
+- Project `.env` avoidance, declaration symlink rejection, and secret-safe summaries.
+- Safe adapter upgrades and distinct stale exact-pin and compatible-range detection.
+- Upgrade rejection for core, schema, skill, mode, policy, evidence, secret, and path drift.
+- Machine-readable upgrade evidence schema validity and no-change declarations.
+- Safe JSON and explicit non-overwriting evidence output.
+- Multi-step chain acceptance, stale pins, compatibility gaps, policy weakening, and privacy.
+- Evidence-bundle archive indexes, retention-expiry advisories, and signature-plan checks.
+- Property-generated command-policy bypass combinations.
+- A matrix of schema-valid but semantically false completion claims.
+
+`node scripts/validate-pack.mjs .` adds structural, link, secret-pattern, CI, and release-file checks.
+
+`node --test` exercises built-in Node fixtures. See the [harness guide](../docs/testing/README.md) for design boundaries.

package/tests/adapters/README.md

@@ -0,0 +1,15 @@
+# Adapter Tests
+
+Test that adapters can add safe manifests, check aliases, documentation precedence, status-only runtime commands, and evidence requirements.
+
+Reject adapters that widen scope, permit restricted operations, hide dirty state or failures, access secrets, or redefine completion. Shared policy must win deterministically.
+
+Executable fixtures validate the formal adapter schema and cover valid narrowing, documentation precedence, deployment permission, Git push permission, failure suppression, completion override, secret exposure, restriction removal, stale compatibility, evidence removal, scope expansion, and audit-only mode override.
+
+External fixture roots additionally test bounded location discovery, exact manifest naming,
+valid and invalid mixed roots, empty and missing roots, malformed JSON, traversal, symlink
+escape, adapter and skill versions, unsupported skill IDs, and safe CLI summaries.
+
+Project installation fixtures add declaration discovery, exact and ranged core pins,
+adapter-record matching, multiple installed adapters, unsupported core versions, invalid
+locations, inherited-policy weakening, `.env` avoidance, and secret-safe summaries.

package/tests/completion/README.md

@@ -0,0 +1,15 @@
+# Completion Tests
+
+Verify that no skill reports `complete` when:
+
+- A required check failed.
+- A required check was skipped and `completionPermitted` is false.
+- Repository or runtime identity remains ambiguous.
+- A material claim is unclassified.
+- An audit-only skill changed state.
+- A validation command produced an unreviewed mutation.
+- Required evidence fields are missing.
+
+Passing a subset of checks must not imply overall success.
+
+The executable matrix additionally rejects missing skipped-check consequences, command failures, material unresolved risks, unknown state-change status, blank confidence reasons, absent repository identity, and unsupported final status.

package/tests/evidence/README.md

@@ -0,0 +1,15 @@
+# Evidence Tests
+
+The release suite validates all five example evidence packs against the shared schema and applies semantic completion rules.
+
+Current checks confirm:
+
+- Required identity and invocation fields exist.
+- Command records satisfy the contract.
+- Skipped checks include consequences and completion permission.
+- Failures and unresolved questions prevent unsupported completion.
+- `changedState.changed` remains `false` for every audit-only skill.
+- Confidence includes a reason.
+- A schema-valid fixture with a completion-blocking skipped check cannot claim `complete`.
+
+Future invocation tests should verify artifact reporting for `build-verify`, handoff wording, and end-to-end output sanitization.

package/tests/fixtures/README.md

@@ -0,0 +1,23 @@
+# Fixtures
+
+Current synthetic fixtures include:
+
+- `sample-repo`: a dependency-free Node.js project with source, test, docs, and `.env.example`.
+- `triggers/cases.json`: positive, negative, and wrong-skill prompt cases.
+- `policy/commands.json`: explicit safe and restricted shell-shape cases.
+- `policy/properties.json`: generated composition, argument, wrapper, provider, and script-body cases.
+- `mutation/`: denied-category documents and a stable snapshot target.
+- `privacy/cases.json`: split synthetic sensitive shapes.
+- `adapters/`: valid contract fixtures plus distinct schema and compatibility failures.
+- `external-adapters/`: disposable project roots for bounded discovery and rejection tests.
+- `project-adapter-installation/`: disposable repositories with declarations and version pins.
+- `project-adapter-upgrades/`: paired disposable revisions for safe upgrades and drift rejection.
+- `project-adapter-upgrade-chains/`: ordered disposable revisions for chain-level compatibility.
+- `evidence-bundles/`: disposable evidence bundles for hash, replay, regression,
+  retention, retention-expiry advisory, provenance, archive index, archive report,
+  signature-plan, and path checks.
+- `completion/`: single and matrix-style schema-valid false completions.
+
+Future fixtures may cover dirty monorepos, non-Git projects, nested repositories, malformed manifests, bounded large trees, and secret-like filenames.
+
+Fixtures must contain synthetic values only.

package/tests/fixtures/adapters/allow-deploy.json

@@ -0,0 +1,60 @@
+{
+  "adapterId": "fixture-allow-deploy",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-project",
+    "detection": {
+      "rootMarkers": [{"kind": "file", "path": "package.json"}],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "repo-map",
+      "compatibleVersions": ["0.2.3"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md"],
+    "ignoredPaths": [],
+    "documentationPrecedence": [],
+    "commandAliases": [
+      {
+        "alias": "deploy-project",
+        "skillId": "repo-map",
+        "family": "unsafe-deployment",
+        "command": "wrangler deploy"
+      }
+    ],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["repository root"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["npm"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}

package/tests/fixtures/adapters/allow-git-push.json

@@ -0,0 +1,60 @@
+{
+  "adapterId": "fixture-allow-git-push",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-project",
+    "detection": {
+      "rootMarkers": [{"kind": "directory", "path": ".git"}],
+      "maximumDepth": 0,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "git-preflight",
+      "compatibleVersions": ["0.2.3"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md"],
+    "ignoredPaths": [],
+    "documentationPrecedence": [],
+    "commandAliases": [
+      {
+        "alias": "publish-main",
+        "skillId": "git-preflight",
+        "family": "unsafe-git-publication",
+        "command": "git push origin main"
+      }
+    ],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["Git status"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["none"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}

package/tests/fixtures/adapters/expand-scope.json

@@ -0,0 +1,53 @@
+{
+  "adapterId": "fixture-expand-scope",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-project",
+    "detection": {
+      "rootMarkers": [{"kind": "file", "path": "package.json"}],
+      "maximumDepth": 8,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": false
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "repo-map",
+      "compatibleVersions": ["0.2.3"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md"],
+    "ignoredPaths": [],
+    "documentationPrecedence": [],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["repository root"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["none"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": true
+  }
+}

package/tests/fixtures/adapters/expose-secrets.json

@@ -0,0 +1,53 @@
+{
+  "adapterId": "fixture-expose-secrets",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-project",
+    "detection": {
+      "rootMarkers": [{"kind": "file", "path": "package.json"}],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "repo-map",
+      "compatibleVersions": ["0.2.3"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md"],
+    "ignoredPaths": [],
+    "documentationPrecedence": [],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["repository root"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["none"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": true,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}

package/tests/fixtures/adapters/incompatible-version.json

@@ -0,0 +1,53 @@
+{
+  "adapterId": "fixture-incompatible-version",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-project",
+    "detection": {
+      "rootMarkers": [{"kind": "file", "path": "package.json"}],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "repo-map",
+      "compatibleVersions": ["0.1.0"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md"],
+    "ignoredPaths": [],
+    "documentationPrecedence": [],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["repository root"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["none"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}

package/tests/fixtures/adapters/override-audit-only.json

@@ -0,0 +1,53 @@
+{
+  "adapterId": "fixture-override-mode",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-project",
+    "detection": {
+      "rootMarkers": [{"kind": "file", "path": "package.json"}],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "runtime-truth",
+      "compatibleVersions": ["0.2.3"],
+      "declaredMode": "action-capable"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md"],
+    "ignoredPaths": [],
+    "documentationPrecedence": [],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["manager status"],
+    "expectedRuntimeManagers": ["systemd-user"],
+    "expectedPackageManagers": ["none"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}

package/tests/fixtures/adapters/redefine-completion.json

@@ -0,0 +1,53 @@
+{
+  "adapterId": "fixture-redefine-completion",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-project",
+    "detection": {
+      "rootMarkers": [{"kind": "file", "path": "package.json"}],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "repo-map",
+      "compatibleVersions": ["0.2.3"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md"],
+    "ignoredPaths": [],
+    "documentationPrecedence": [],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["repository root"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["none"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": true,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}