diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7fefaa2..82fb59e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-marketplace.json", "name": "codetruss", "description": "Verify the acceptance contract for coding-agent changes locally", - "version": "0.1.2", + "version": "0.1.3", "owner": { "name": "CodeTruss", "email": "zack@codetruss.com" diff --git a/README.md b/README.md index e5fe39f..5262b03 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ installation, provider-backed `--llm` review, authentication, or receipt - Git - Node.js 20.9 or newer -- The free CodeTruss CLI from +- CodeTruss CLI v0.2.24 or newer from The skill can explain the official installer when the CLI is missing, but it must not install software without the developer's confirmation. @@ -40,10 +40,26 @@ codex plugin add codetruss@codetruss The owned marketplace is live now. CodeTruss is not currently listed in OpenAI's public Plugin Directory. +## Agent Skills clients + +Install the same canonical skill for both Claude Code and Codex with the public +Agent Skills installer: + +```bash +npx --yes skills add DeliriumPulse/codetruss-plugins \ + --skill codetruss --agent claude-code codex -y +``` + +The skill is indexed at +. Review the skill +before use; it can invoke the separately installed CLI with the agent's local +permissions. + ## What the skill does - proposes a narrow repository allow/deny policy and verification commands; -- runs `codetruss init` only after the developer confirms the boundary; +- runs guided `codetruss setup` only after the developer confirms the boundary, + hook target, and exact verification-command trust; - installs and diagnoses the existing Claude Code or Codex lifecycle hook; - reviews working-tree or staged changes and interprets the resulting receipt; - treats exit codes 1 and 2 as product verdicts with valid evidence, not generic diff --git a/package.json b/package.json index d02faf3..8025c91 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codetruss-agent-plugins", - "version": "0.1.2", + "version": "0.1.3", "private": true, "description": "Open Claude Code, Codex, and Agent Skills wrappers for the CodeTruss CLI", "license": "MIT", diff --git a/plugins/codetruss-claude/.claude-plugin/plugin.json b/plugins/codetruss-claude/.claude-plugin/plugin.json index 25ef789..20fe8fe 100644 --- a/plugins/codetruss-claude/.claude-plugin/plugin.json +++ b/plugins/codetruss-claude/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "codetruss", - "version": "0.1.2", + "version": "0.1.3", "description": "Verify coding-agent changes locally with the separately installed free CodeTruss CLI.", "author": { "name": "CodeTruss", diff --git a/plugins/codetruss-claude/README.md b/plugins/codetruss-claude/README.md index b8f930e..649f0a8 100644 --- a/plugins/codetruss-claude/README.md +++ b/plugins/codetruss-claude/README.md @@ -7,7 +7,7 @@ Prerequisites: - Git - Node.js 20.9 or newer -- CodeTruss CLI v0.2.14 or newer from +- CodeTruss CLI v0.2.24 or newer from The plugin contains no analyzer, bundled hook, MCP server, background service, or upload path. It delegates hook installation to the tested CLI after developer @@ -17,7 +17,9 @@ authentication, and receipt sync require separate explicit developer actions. Troubleshooting: - Run `codetruss --version`; install or upgrade from the CLI page when it is - missing or older than v0.2.14. + missing or older than v0.2.24. +- Run `codetruss setup` for the guided local policy, verification-fingerprint, + and hook flow. Do not replace it with hand-edited setup steps. - Run `codetruss hooks status claude` and `codetruss hooks doctor claude` before changing or reinstalling Claude settings. - Exit 1 means `REVIEW_REQUIRED`, exit 2 means `FAILED`, and both still produce diff --git a/plugins/codetruss-claude/skills/codetruss/SKILL.md b/plugins/codetruss-claude/skills/codetruss/SKILL.md index 4e7d8ae..cfea1ca 100644 --- a/plugins/codetruss-claude/skills/codetruss/SKILL.md +++ b/plugins/codetruss-claude/skills/codetruss/SKILL.md @@ -13,8 +13,9 @@ agent. - Work inside the developer's Git repository and inspect existing policy before proposing changes. -- Run `codetruss --version` first. If it is missing, explain the prerequisite - and obtain explicit consent before downloading or installing software. +- Run `codetruss --version` first. This skill targets v0.2.24 or newer. If the + CLI is missing or older, explain the prerequisite, then + obtain explicit consent before downloading or installing software, including an upgrade. - Offer only the official install paths from `https://codetruss.com/cli`. Let the developer inspect a downloaded installer instead of piping it when they prefer an inspect-first flow. @@ -24,9 +25,10 @@ agent. - Do not broaden `allow`, remove `deny`, add `--no-verify`, or edit a receipt to manufacture a green verdict. Fix the change or ask the developer to approve a genuine policy change. -- Treat exit `0` as `PASS`, exit `1` as `REVIEW_REQUIRED`, exit `2` as `FAILED`, - and exit `3` as a usage or environment failure. Exits 1 and 2 still produce - receipts; inspect them instead of reporting a generic shell failure. +- For `codetruss run` and `codetruss review`, treat exit `0` as `PASS`, exit `1` + as `REVIEW_REQUIRED`, exit `2` as `FAILED`, and exit `3` as a usage or + environment failure. Exits 1 and 2 still produce receipts; other commands + may use nonzero exits differently, so read their output. - Describe a valid signature as post-generation integrity evidence. Do not call it trusted execution, proof of authorship, or automatic compliance evidence. @@ -36,22 +38,41 @@ agent. attribution matters. 2. Inspect tracked paths, task context, existing `.codetruss.yml`, package scripts, and the repository's normal lint, typecheck, test, or build commands. -3. Propose the smallest useful `allow` globs. Keep secrets, generated output, - production infrastructure, and unrelated migrations denied when appropriate. - Do not default to `**/*`. -4. Ask the developer to confirm the proposed boundary and verification commands. -5. Run `codetruss init` with the confirmed repeated `--allow` and `--deny` - flags. Add confirmed verification commands to `.codetruss.yml` without - disturbing unrelated configuration. -6. When running in Claude Code, run `codetruss hooks install claude`; when - running in Codex, run `codetruss hooks install codex`. If the host is - ambiguous, ask rather than installing both. -7. Run `codetruss hooks doctor claude` or `codetruss hooks doctor codex`. - Remind Codex users to open `/hooks` and approve the exact repository hook - definition when the doctor reports the manual trust step. +3. Propose the smallest useful `allow` globs, appropriate `deny` globs, the + exact verification commands CodeTruss is expected to detect, and one hook + target. Keep secrets, generated output, production infrastructure, and + unrelated migrations denied when appropriate. Show which tracked paths each + glob matches, and flag empty or overly broad matches. Do not default to `**/*`. +4. Ask the developer to confirm the exact boundary, hook target, verification + command list, and whether to trust that list for automatic execution. +5. After confirmation, use `codetruss setup` as the single guided setup path, + with the approved repeated `--allow` and `--deny` values and one + `--hooks claude|codex|pre-commit|all` value. Prefer its interactive trust + prompt so the commands it actually prints can be compared with the approved + list before answering `trust`. Use `--yes` only after every choice is + explicit and the inspected repository state is unchanged. Include + `--trust-verify` only after the developer approves the exact detected list, + so fingerprint trust is completed. Do not replace guided initial setup with + ad hoc config editing or separate hook installation. +6. Read the setup output and verify the expected policy, hook health, and + local-only privacy reminder. When commands were detected, require their + full verification fingerprint and trusted result, then run + `codetruss verify-policy status` and require exit 0 with the same fingerprint + and command list. Otherwise confirm that setup reports no detected commands. + If setup pauses before trust, show the exact commands and fingerprint, obtain + approval, then rerun the same setup path with `--trust-verify`. +7. Remind Codex users to open `/hooks` and approve the exact repository hook + definition when setup reports that one-time host trust step. The CLI's hook installer is idempotent and preserves supported existing hook -configuration. Do not replace it with plugin-bundled hook logic. +configuration. An existing `.codetruss.yml` remains authoritative: if setup +reports a policy mismatch, stop instead of overwriting or weakening it, and +treat any policy change as a separate developer decision. If the developer +approves the exact policy diff, make only that reviewed edit and rerun setup +without conflicting policy flags. A setup hook target installs or checks that +target; it does not remove other existing hooks. Never uninstall another hook +without an explicit removal request. Do not replace the installer with +plugin-bundled hook logic. ## Review changes diff --git a/plugins/codetruss/.codex-plugin/plugin.json b/plugins/codetruss/.codex-plugin/plugin.json index e3391cb..3d4a2e5 100644 --- a/plugins/codetruss/.codex-plugin/plugin.json +++ b/plugins/codetruss/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "codetruss", - "version": "0.1.2", + "version": "0.1.3", "description": "Verify the acceptance contract for coding-agent changes locally.", "author": { "name": "CodeTruss", diff --git a/plugins/codetruss/README.md b/plugins/codetruss/README.md index 3fa891f..a6a4969 100644 --- a/plugins/codetruss/README.md +++ b/plugins/codetruss/README.md @@ -7,7 +7,7 @@ Prerequisites: - Git - Node.js 20.9 or newer -- CodeTruss CLI v0.2.14 or newer from +- CodeTruss CLI v0.2.24 or newer from The plugin contains no analyzer, MCP server, background service, or upload path. Deterministic checks stay local. Provider-backed review, authentication, and @@ -16,7 +16,9 @@ receipt sync require separate explicit developer actions. Troubleshooting: - Run `codetruss --version`; install or upgrade from the CLI page when it is - missing or older than v0.2.14. + missing or older than v0.2.24. +- Run `codetruss setup` for the guided local policy, verification-fingerprint, + and hook flow. Do not replace it with hand-edited setup steps. - Run `codetruss hooks status codex` and `codetruss hooks doctor codex` before changing hook configuration. Codex may require approval of the exact hook in `/hooks`. diff --git a/plugins/codetruss/skills/codetruss/SKILL.md b/plugins/codetruss/skills/codetruss/SKILL.md index 4e7d8ae..cfea1ca 100644 --- a/plugins/codetruss/skills/codetruss/SKILL.md +++ b/plugins/codetruss/skills/codetruss/SKILL.md @@ -13,8 +13,9 @@ agent. - Work inside the developer's Git repository and inspect existing policy before proposing changes. -- Run `codetruss --version` first. If it is missing, explain the prerequisite - and obtain explicit consent before downloading or installing software. +- Run `codetruss --version` first. This skill targets v0.2.24 or newer. If the + CLI is missing or older, explain the prerequisite, then + obtain explicit consent before downloading or installing software, including an upgrade. - Offer only the official install paths from `https://codetruss.com/cli`. Let the developer inspect a downloaded installer instead of piping it when they prefer an inspect-first flow. @@ -24,9 +25,10 @@ agent. - Do not broaden `allow`, remove `deny`, add `--no-verify`, or edit a receipt to manufacture a green verdict. Fix the change or ask the developer to approve a genuine policy change. -- Treat exit `0` as `PASS`, exit `1` as `REVIEW_REQUIRED`, exit `2` as `FAILED`, - and exit `3` as a usage or environment failure. Exits 1 and 2 still produce - receipts; inspect them instead of reporting a generic shell failure. +- For `codetruss run` and `codetruss review`, treat exit `0` as `PASS`, exit `1` + as `REVIEW_REQUIRED`, exit `2` as `FAILED`, and exit `3` as a usage or + environment failure. Exits 1 and 2 still produce receipts; other commands + may use nonzero exits differently, so read their output. - Describe a valid signature as post-generation integrity evidence. Do not call it trusted execution, proof of authorship, or automatic compliance evidence. @@ -36,22 +38,41 @@ agent. attribution matters. 2. Inspect tracked paths, task context, existing `.codetruss.yml`, package scripts, and the repository's normal lint, typecheck, test, or build commands. -3. Propose the smallest useful `allow` globs. Keep secrets, generated output, - production infrastructure, and unrelated migrations denied when appropriate. - Do not default to `**/*`. -4. Ask the developer to confirm the proposed boundary and verification commands. -5. Run `codetruss init` with the confirmed repeated `--allow` and `--deny` - flags. Add confirmed verification commands to `.codetruss.yml` without - disturbing unrelated configuration. -6. When running in Claude Code, run `codetruss hooks install claude`; when - running in Codex, run `codetruss hooks install codex`. If the host is - ambiguous, ask rather than installing both. -7. Run `codetruss hooks doctor claude` or `codetruss hooks doctor codex`. - Remind Codex users to open `/hooks` and approve the exact repository hook - definition when the doctor reports the manual trust step. +3. Propose the smallest useful `allow` globs, appropriate `deny` globs, the + exact verification commands CodeTruss is expected to detect, and one hook + target. Keep secrets, generated output, production infrastructure, and + unrelated migrations denied when appropriate. Show which tracked paths each + glob matches, and flag empty or overly broad matches. Do not default to `**/*`. +4. Ask the developer to confirm the exact boundary, hook target, verification + command list, and whether to trust that list for automatic execution. +5. After confirmation, use `codetruss setup` as the single guided setup path, + with the approved repeated `--allow` and `--deny` values and one + `--hooks claude|codex|pre-commit|all` value. Prefer its interactive trust + prompt so the commands it actually prints can be compared with the approved + list before answering `trust`. Use `--yes` only after every choice is + explicit and the inspected repository state is unchanged. Include + `--trust-verify` only after the developer approves the exact detected list, + so fingerprint trust is completed. Do not replace guided initial setup with + ad hoc config editing or separate hook installation. +6. Read the setup output and verify the expected policy, hook health, and + local-only privacy reminder. When commands were detected, require their + full verification fingerprint and trusted result, then run + `codetruss verify-policy status` and require exit 0 with the same fingerprint + and command list. Otherwise confirm that setup reports no detected commands. + If setup pauses before trust, show the exact commands and fingerprint, obtain + approval, then rerun the same setup path with `--trust-verify`. +7. Remind Codex users to open `/hooks` and approve the exact repository hook + definition when setup reports that one-time host trust step. The CLI's hook installer is idempotent and preserves supported existing hook -configuration. Do not replace it with plugin-bundled hook logic. +configuration. An existing `.codetruss.yml` remains authoritative: if setup +reports a policy mismatch, stop instead of overwriting or weakening it, and +treat any policy change as a separate developer decision. If the developer +approves the exact policy diff, make only that reviewed edit and rerun setup +without conflicting policy flags. A setup hook target installs or checks that +target; it does not remove other existing hooks. Never uninstall another hook +without an explicit removal request. Do not replace the installer with +plugin-bundled hook logic. ## Review changes diff --git a/scripts/validate.mjs b/scripts/validate.mjs index ed1b293..9b074fa 100644 --- a/scripts/validate.mjs +++ b/scripts/validate.mjs @@ -19,13 +19,20 @@ assert.match(canonicalSkill, /^---\nname: codetruss\ndescription: .{80,1024}\n-- for (const required of [ 'obtain explicit consent before downloading or installing software', + 'This skill targets v0.2.24 or newer.', + 'use `codetruss setup` as the single guided setup path', + '`codetruss verify-policy status` and require exit 0 with the same fingerprint', + 'An existing `.codetruss.yml` remains authoritative', 'Do not run `--llm`, `codetruss auth login`, or `codetruss sync` unless', 'Do not broaden `allow`, remove `deny`, add `--no-verify`', - 'exit `1` as `REVIEW_REQUIRED`', + 'For `codetruss run` and `codetruss review`, treat exit `0` as `PASS`', 'post-generation integrity evidence', ]) { assert.ok(canonicalSkill.includes(required), `missing trust-boundary rule: ${required}`) } +assert.match(canonicalSkill, /exit `1`\s+as `REVIEW_REQUIRED`/) +assert.match(canonicalSkill, /exit `2` as `FAILED`/) +assert.match(canonicalSkill, /Never uninstall another hook\s+without an explicit removal request/) const canonicalOpenAi = await read('skills/codetruss/agents/openai.yaml') assert.equal( @@ -82,8 +89,19 @@ assert.deepEqual(codexMarketplace.plugins[0].policy, { }) const readme = await read('README.md') +assert.match(readme, /CodeTruss CLI v0\.2\.24 or newer/) +assert.match(readme, /--skill codetruss --agent claude-code codex -y/) assert.doesNotMatch(readme, /official listing remains pending review/) assert.match(readme, /not currently listed in\s+Anthropic's reviewed community catalog/) assert.match(readme, /not currently listed in\s+OpenAI's public Plugin Directory/) +for (const path of [ + 'plugins/codetruss/README.md', + 'plugins/codetruss-claude/README.md', +]) { + const pluginReadme = await read(path) + assert.match(pluginReadme, /CodeTruss CLI v0\.2\.24 or newer/) + assert.match(pluginReadme, /Run `codetruss setup` for the guided local policy/) +} + process.stdout.write('CodeTruss Claude, Codex, and Agent Skills packages validated.\n') diff --git a/skills/codetruss/SKILL.md b/skills/codetruss/SKILL.md index 4e7d8ae..cfea1ca 100644 --- a/skills/codetruss/SKILL.md +++ b/skills/codetruss/SKILL.md @@ -13,8 +13,9 @@ agent. - Work inside the developer's Git repository and inspect existing policy before proposing changes. -- Run `codetruss --version` first. If it is missing, explain the prerequisite - and obtain explicit consent before downloading or installing software. +- Run `codetruss --version` first. This skill targets v0.2.24 or newer. If the + CLI is missing or older, explain the prerequisite, then + obtain explicit consent before downloading or installing software, including an upgrade. - Offer only the official install paths from `https://codetruss.com/cli`. Let the developer inspect a downloaded installer instead of piping it when they prefer an inspect-first flow. @@ -24,9 +25,10 @@ agent. - Do not broaden `allow`, remove `deny`, add `--no-verify`, or edit a receipt to manufacture a green verdict. Fix the change or ask the developer to approve a genuine policy change. -- Treat exit `0` as `PASS`, exit `1` as `REVIEW_REQUIRED`, exit `2` as `FAILED`, - and exit `3` as a usage or environment failure. Exits 1 and 2 still produce - receipts; inspect them instead of reporting a generic shell failure. +- For `codetruss run` and `codetruss review`, treat exit `0` as `PASS`, exit `1` + as `REVIEW_REQUIRED`, exit `2` as `FAILED`, and exit `3` as a usage or + environment failure. Exits 1 and 2 still produce receipts; other commands + may use nonzero exits differently, so read their output. - Describe a valid signature as post-generation integrity evidence. Do not call it trusted execution, proof of authorship, or automatic compliance evidence. @@ -36,22 +38,41 @@ agent. attribution matters. 2. Inspect tracked paths, task context, existing `.codetruss.yml`, package scripts, and the repository's normal lint, typecheck, test, or build commands. -3. Propose the smallest useful `allow` globs. Keep secrets, generated output, - production infrastructure, and unrelated migrations denied when appropriate. - Do not default to `**/*`. -4. Ask the developer to confirm the proposed boundary and verification commands. -5. Run `codetruss init` with the confirmed repeated `--allow` and `--deny` - flags. Add confirmed verification commands to `.codetruss.yml` without - disturbing unrelated configuration. -6. When running in Claude Code, run `codetruss hooks install claude`; when - running in Codex, run `codetruss hooks install codex`. If the host is - ambiguous, ask rather than installing both. -7. Run `codetruss hooks doctor claude` or `codetruss hooks doctor codex`. - Remind Codex users to open `/hooks` and approve the exact repository hook - definition when the doctor reports the manual trust step. +3. Propose the smallest useful `allow` globs, appropriate `deny` globs, the + exact verification commands CodeTruss is expected to detect, and one hook + target. Keep secrets, generated output, production infrastructure, and + unrelated migrations denied when appropriate. Show which tracked paths each + glob matches, and flag empty or overly broad matches. Do not default to `**/*`. +4. Ask the developer to confirm the exact boundary, hook target, verification + command list, and whether to trust that list for automatic execution. +5. After confirmation, use `codetruss setup` as the single guided setup path, + with the approved repeated `--allow` and `--deny` values and one + `--hooks claude|codex|pre-commit|all` value. Prefer its interactive trust + prompt so the commands it actually prints can be compared with the approved + list before answering `trust`. Use `--yes` only after every choice is + explicit and the inspected repository state is unchanged. Include + `--trust-verify` only after the developer approves the exact detected list, + so fingerprint trust is completed. Do not replace guided initial setup with + ad hoc config editing or separate hook installation. +6. Read the setup output and verify the expected policy, hook health, and + local-only privacy reminder. When commands were detected, require their + full verification fingerprint and trusted result, then run + `codetruss verify-policy status` and require exit 0 with the same fingerprint + and command list. Otherwise confirm that setup reports no detected commands. + If setup pauses before trust, show the exact commands and fingerprint, obtain + approval, then rerun the same setup path with `--trust-verify`. +7. Remind Codex users to open `/hooks` and approve the exact repository hook + definition when setup reports that one-time host trust step. The CLI's hook installer is idempotent and preserves supported existing hook -configuration. Do not replace it with plugin-bundled hook logic. +configuration. An existing `.codetruss.yml` remains authoritative: if setup +reports a policy mismatch, stop instead of overwriting or weakening it, and +treat any policy change as a separate developer decision. If the developer +approves the exact policy diff, make only that reviewed edit and rerun setup +without conflicting policy flags. A setup hook target installs or checks that +target; it does not remove other existing hooks. Never uninstall another hook +without an explicit removal request. Do not replace the installer with +plugin-bundled hook logic. ## Review changes