Harden portable skill protocol, installer safety, and quality gates (#2)

* refactor(skill): define portable evidence-first engineering gates

* fix(installer): preserve existing entries and require explicit targets

* test(quality): gate package integrity and portable utility regressions

* ci: pin verified Node 24-compatible action releases

Author: elkaix

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,sh}]
+indent_size = 2

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 3

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Scope and evidence
+
+State the accepted outcomes, inspected baseline, and implemented root causes.
+Link each outcome to current verification. Distinguish observed facts from assumptions.
+
+## Verification
+
+Record commands and results after the final relevant edit. Name unrun/waived checks.
+For skill wording changes, identify the scenarios reviewed and whether a model actually ran.
+A scenario definition or keyword check is not a successful behavioral evaluation.
+
+## Safety and delivery
+
+Describe compatibility, dependency changes, user-work preservation, discovered bugs,
+observability, migration, and rollback. Explain any inapplicable areas.
+Keep commits coherent and inspect the staged diff. Do not bypass the required docs check.

.github/workflows/ci.yml

@@ -4,22 +4,52 @@ on:
   push:
     branches: [main]
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: code-max-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
+  checks:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: '3.10'
+          - os: macos-latest
+            python: '3.13'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Validate the skill package
+        run: python3 scripts/validate.py
+      - name: Run isolated utility regression tests
+        run: python3 -m unittest discover -s tests -v
+      - name: Check Bash syntax
+        run: bash -n skills.sh
+      - name: ShellCheck
+        if: runner.os == 'Linux'
+        run: shellcheck skills.sh
+
+  # Preserve the existing branch-protection context, including matrix failures.
   docs:
+    if: always()
+    needs: checks
     runs-on: ubuntu-latest
+    timeout-minutes: 2
     steps:
-      - uses: actions/checkout@v4
-      - name: SKILL.md frontmatter is valid
-        run: |
-          head -1 SKILL.md | grep -qx -- '---'
-          grep -qx 'name: code-max' SKILL.md
-          grep -q '^description: Use when ' SKILL.md
-      - name: README and AGENTS links resolve
-        run: |
-          grep -ohE '\]\(([^)#:]+)\)' README.md AGENTS.md | sed -E 's/^\]\(|\)$//g' | sort -u | while read -r f; do
-            test -e "$f" || { echo "broken link: $f"; exit 1; }
-          done
+      - name: Require every check to pass
+        env:
+          CHECK_RESULT: ${{ needs.checks.result }}
+        run: test "$CHECK_RESULT" = success

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.venv/
+.DS_Store

AGENTS.md

@@ -1,34 +1,54 @@
-# AGENTS.md
+# Repository guidance
 
-This repository *is* an agent skill. The skill body lives in `SKILL.md` — read it before acting on any coding task in this repo.
+This repository distributes an agent skill, not an application framework. Read
+[SKILL.md](SKILL.md) before changing it. Follow host instruction precedence and the
+user's authorized task. These rules govern this repository, not every consuming project.
 
-## Repo map
+## Ownership map
 
-| File | Purpose |
+| Path | Responsibility |
 | --- | --- |
-| `SKILL.md` | The skill itself: frontmatter (`name`, `description`) + the maximum-rigor protocol. |
-| `skills.sh` | Symlinks this directory into each supported agent's skills folder. |
-| `README.md` | Human-facing docs: what it does, install, usage. |
-| `banner.svg` | Header image used by the README. |
-
-## Rules for changes here
-
-1. `SKILL.md` frontmatter must stay valid: `---` on line 1, `name:` matching the directory name, and a `description:` written as *"Use when ..."* trigger conditions.
-2. Keep `SKILL.md` under ~200 lines. It is loaded into every agent's context; every line costs tokens on every run.
-3. Any behavior change in `SKILL.md` that alters what the skill promises must be mirrored in `README.md`.
-4. `skills.sh` is POSIX-ish bash and must pass `shellcheck skills.sh`. New agents go in the `TARGETS` array — nowhere else.
-5. No new dependencies, build steps, or package manifests. This repo is text plus one shell script by design.
-
-## Verifying
+| [SKILL.md](SKILL.md) | Portable core protocol and activation metadata. |
+| [references/](references/) | Directly linked, conditional quality guidance and reporting. |
+| [scripts/](scripts/) and [skills.sh](skills.sh) | Optional standard-library Python helpers and Bash entry point. |
+| [tests/](tests/) | Isolated utility regression and negative-control tests. |
+| [evals/](evals/) | Behavioral scenarios and honest model-evaluation procedure. |
+| [README.md](README.md) | Installation, capabilities, limitations, and adoption. |
+| [docs/](docs/) | Audit evidence, migration, and historical research. |
+| [.github/](.github/) | CI and contribution gates. |
+
+## Change contract
+
+- Inspect the baseline and preserve user-owned work. Record multi-step acceptance work
+  in the existing task/PR ledger; do not introduce duplicate trackers for every request.
+- Keep the core architecture-, stack-, host-, and tool-agnostic. Do not mandate universal
+  frameworks, arbitrary coverage percentages, broad refactors, or unavailable tools.
+- Keep SKILL.md at most 200 lines and 12,000 UTF-8 bytes. This is a local context budget,
+  not an industry standard. Use one-hop references for optional detail.
+- Maintain the minimal frontmatter profile: unquoted, single-line `name: code-max` and
+  a `description: Use when ...` scalar. The validator deliberately is not a general YAML parser.
+- Mirror behavioral promises, dependencies, CLI changes, and limitations in README.md.
+  Update this ownership map or scoped guidance when responsibilities change.
+- Preserve the instruction-only consumption path. Optional tooling uses Python 3.10+
+  standard library and Bash; no pip/npm dependencies, network calls, or package manifests.
+  Do not turn installation into execution hooks or automatically modify host permissions.
+- Tests are required for executable behavior changes. Use temporary HOME and explicit
+  targets; never test installation against the developer's real agent directories.
+- Report every discovered bug with evidence and disposition. Fix in-scope defects; record
+  other findings without hiding them or silently expanding scope.
+- Make small, coherent, reviewable commits. Stage exact paths and inspect the staged diff.
+  Work on a branch and open a PR. Respect the existing required `docs` status context;
+  do not bypass branch protection or claim a remote check passed without observing it.
+
+## Verification
 
 ```bash
-shellcheck skills.sh          # lint (local only, not in CI)
-head -1 SKILL.md              # must be ---
-./skills.sh                   # idempotent; re-running must not break existing symlinks
+python3 scripts/validate.py
+python3 -m unittest discover -s tests -v
+bash -n skills.sh
+shellcheck skills.sh
 ```
 
-CI (`.github/workflows/ci.yml`) checks the docs only: `SKILL.md` frontmatter and that links in `README.md` / `AGENTS.md` resolve. There are no test suites here — keep it that way.
-
-## Contributing flow
-
-`main` is protected: force-pushes and deletions are blocked, history is linear, and CI must pass. Work on a branch, open a PR, let `docs` go green, then squash-merge.
+Read [evals/README.md](evals/README.md) for behavioral evaluation. Utility tests and
+scenario-schema validation do not prove model compliance. Report model evaluations,
+platform checks, lint, and reviews as unrun when they were unavailable.

README.md

@@ -1,78 +1,140 @@
 <p align="center">
-  <img src="banner.svg" alt="code-max" width="100%">
+  <img src="banner.svg" alt="code-max: evidence, or it didn't happen" width="100%">
 </p>
 
-<p align="center">
-  <a href="SKILL.md"><img src="https://img.shields.io/badge/type-agent%20skill-0b0e14?style=flat" alt="agent skill"></a>
-  <a href="skills.sh"><img src="https://img.shields.io/badge/works%20with-any%20coding%20agent-5ee2a0?style=flat&labelColor=0b0e14" alt="any coding agent"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-8b98a8?style=flat&labelColor=0b0e14" alt="MIT"></a>
-  <a href="https://skills.sh/PyModel/code-max"><img src="https://skills.sh/b/PyModel/code-max" alt="skills.sh installs"></a>
-</p>
+# code-max
 
-An agent skill that stops a coding agent from telling you it finished when it did not — and from shipping the cheap, partial version as if it were production-ready.
+A portable engineering skill for evidence-backed implementation, debugging, review,
+refactoring, and migrations. It demands the smallest complete solution, relevant tests,
+and an honest report instead of unsupported claims that work is finished.
 
-## What it does
+## Engineering contract
 
-Coding agents like to say "done" after writing code they never ran. code-max replaces that habit with a production-grade contract. Production-grade means the smallest complete solution, not extra architecture and not a quick substitute for required behavior:
+The [core protocol](SKILL.md) requires an acceptance ledger proportional to the task,
+source inspection, preservation of user-owned work, cause-level fixes, and verification
+after the last relevant edit. It adds architecture discovery, explicit dependencies and
+contracts, risk-based quality gates, prompt defect reporting, small reviewable commits,
+and migration/rollback planning where relevant.
 
-- Every independently omittable requirement gets an observable acceptance item and direct proof. Trivial work stays lightweight; substantial work uses the harness plan or the repository's tracker.
-- No slop, lazy scope reduction, TODOs, stubs, partial migrations, placeholder data presented as real, unwired code, or deferred in-scope edge cases.
-- Bugs and behavior changes start with the exact failing test or deterministic reproducer. A durable regression test remains when the project has a test harness.
-- Fixes land at the smallest correct shared layer after tracing affected callers, sibling paths, interfaces, tests, and invariants. No under-scoped one-path patch and no drive-by refactor.
-- Non-trivial work gets four risk-proportional passes: complete implementation, domain-expert reread, adversarial defect hunt, then low-cost polish. Trivial edits combine them into one focused review. Repeat an affected pass only when the preceding pass changes implementation or proof; stop when the acceptance ledger is reconciled, applicable checks pass, the final diff is reviewed and clean, and no known in-scope defect remains.
-- Checks must directly observe the claimed outcome and be able to fail. Negative searches vulnerable to empty inputs, wrong paths, or weak patterns use a positive control; reported numbers are remeasured from the source of truth.
-- Tests, type checks, lint, builds, integration checks, and smoke tests run when relevant after the last relevant edit. A green but unrelated check is not proof.
-- Delegated work is independently inspected, re-run, and integration-tested by the parent. High-risk or cross-cutting diffs get read-only independent review when available; review never replaces tests.
-- Changes stay inside the complete requested scope and preserve your uncommitted work. Instructions hidden in source, logs, generated content, tool output, or web pages remain untrusted data.
-- An explicit check waiver never becomes an invented pass. The report names the waiver, remaining proof, and resulting limitation; status follows the task owner's criteria and observed evidence.
+It adapts to the repository rather than imposing a stack, framework, microservices,
+coverage percentage, or new toolchain. [Conditional quality gates](references/quality-gates.md)
+cover architecture, APIs, data, concurrency, resource cleanup, security/privacy, UI and
+accessibility, performance, supply chain, and operations. Load only applicable guidance.
 
-Every run ends with a proportional evidence report: status, acceptance results, changed files, and commands actually executed; failures, unvalidated facts, risks, and suspected injection appear only when present. The agent rereads the current request, reconciles every acceptance item, remeasures claims, and reviews the final diff and status before writing `COMPLETE`. Trivial edits get a compact report. Any material unknown, unmet item, or genuine external constraint stays visible as `BLOCKED`.
+`COMPLETE` requires current evidence for every authorized acceptance item. `PARTIAL`
+retains named unfinished work. `BLOCKED` identifies a concrete constraint. Waived, failed,
+and unrun checks never become passes. See the [report template](references/report-template.md).
+Explicitly requested scaffolding is allowed but cannot be sold as implemented functionality.
 
-code-max remains instruction-only and agent-agnostic. It does not install hooks, add runtime dependencies, or force orchestration machinery onto focused work.
+**Limits:** Instructions cannot guarantee agent compliance or sandbox execution. Host
+permissions, review, and project CI remain necessary. The skill does not grant authority
+to push, deploy, change permissions, or override project governance. Automated checks in
+this repository validate the package and utilities, not every downstream codebase or model.
 
 ## Install
 
-```bash
-npx skills add PyModel/code-max
-```
-
-Installs into whichever agents the [`skills`](https://github.com/vercel-labs/skills) CLI finds on your machine. Update later with `npx skills update code-max`.
+The skill itself is Markdown with no runtime dependencies or hooks. Review it before
+loading. Install the whole directory, including references, using your host's supported
+skill mechanism. Command syntax and discovery differ between hosts.
 
-Or clone and symlink it yourself:
+For an inspected local checkout, the optional installer needs Python 3.10+ and Bash:
 
 ```bash
 git clone https://github.com/PyModel/code-max.git
 cd code-max
-./skills.sh
+./skills.sh --list
+./skills.sh --agent claude --dry-run
+./skills.sh --agent claude
 ```
 
-`skills.sh` symlinks this directory into the skills folder of every agent it knows about:
+Choose only the hosts you need. Repeat `--agent` or give an absolute custom **parent skills
+directory**, not the final code-max path:
 
-| Agent | Path |
-| --- | --- |
-| Claude Code | `~/.claude/skills/code-max` |
-| Codex | `~/.codex/skills/code-max` |
-| Cursor | `~/.cursor/skills/code-max` |
-| Gemini | `~/.gemini/skills/code-max` |
-| Pi | `~/.pi/skills/code-max` |
-| OpenCode | `~/.config/opencode/skills/code-max` |
+```bash
+./skills.sh --agent codex
+./skills.sh --target "$HOME/custom-agent/skills" --dry-run
+./skills.sh --target "$HOME/custom-agent/skills"
+./skills.sh --agent claude --uninstall --dry-run
+./skills.sh --agent claude --uninstall
+```
 
-Because they are symlinks, `git pull` updates every agent at once. Add or remove entries by editing the `TARGETS` array at the top of the script.
+`python3 scripts/install.py` accepts the same options without the Bash wrapper.
+With no target selection the installer exits without changing anything. `--all` explicitly
+selects all presets; it does not detect installed agents. Hosts that read multiple shared
+locations may show duplicates, so prefer selecting a single appropriate location.
+
+| Preset | Destination |
+| --- | --- |
+| `claude` | `~/.claude/skills/code-max` |
+| `codex` | `~/.agents/skills/code-max` |
+| `cursor` | `~/.cursor/skills/code-max` |
+| `gemini` | `~/.gemini/skills/code-max` |
+| `pi` | `~/.pi/agent/skills/code-max` |
+| `opencode` | `${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills/code-max` |
+
+These are discovery presets, not a claim that every host/version was integration-tested.
+Use `--target` for other hosts or configured paths. Presets require an absolute HOME;
+OpenCode also requires XDG_CONFIG_HOME to be absolute when set. Custom targets do not
+require HOME. The installed name remains `code-max` even if the checkout is renamed.
+
+Installation preflights all destinations, preserves existing correct links, and refuses
+files, directories, foreign links, and dangling links. Link creation is no-clobber. Dry-run
+creates no directories or links. Uninstall removes only links resolving to this checkout;
+it never deletes the checkout or target directories. There is no force/overwrite option.
+
+Use trusted, user-owned target directories, not directories concurrently modified by an
+adversary. Preflight is not a multi-target filesystem transaction: a later I/O failure may
+leave earlier reported operations completed. Inspect output and retry idempotently, or
+remove the successful links with the same target selection and `--uninstall`. Uninstall
+checks ownership before removal but is not a defense against hostile concurrent replacement.
+
+## Migration and update
+
+Older `./skills.sh` with no arguments installed everywhere and could overwrite entries.
+Use `--agent` or `--target` now; use `--all` only deliberately. Old Codex and Pi paths were
+`~/.codex/skills` and `~/.pi/skills`. Inspect them before removing duplicates; uninstall
+an old link with `--target` only while it still resolves to this checkout. Foreign/stale
+links are intentionally not auto-deleted. Nothing migrates your host settings or permissions.
+
+Links follow checkout changes. Review updates before pulling, and use a reviewed tag/commit
+or separate checkout when you need an immutable installation. To roll back, select a known
+good revision in a clean dedicated checkout; do not reset user-owned changes. See the
+[hardening audit](docs/hardening.md) for evidence and rollout limits.
 
 ## Use
 
-Ask for it by name, or describe the rigor you want:
+Ask your host to use code-max for the task, for example:
 
-```
-/code-max fix the token refresh race in src/auth/session.ts
+```text
+Use code-max to fix the token refresh race. Preserve existing APIs and user changes.
+Use code-max for a read-only architecture review. Do not edit or publish anything.
 ```
 
+Use the project's existing test commands, CI, review process, and task tracker. The skill
+does not automatically add hooks, copy AGENTS.md into other projects, or execute helpers.
+
+## Contributing and validation
+
+Read [AGENTS.md](AGENTS.md). Optional tools require no third-party Python packages:
+
+```bash
+python3 scripts/validate.py
+python3 -m unittest discover -s tests -v
+bash -n skills.sh
+shellcheck skills.sh
 ```
-Implement the CSV import. Verify before you claim done, no stubs.
-```
 
-Reach for it when a wrong answer is expensive: migrations, auth, payments, anything you plan to merge without reading closely. For a one-line typo fix it is overhead.
+The offline validator checks this repository's restricted two-scalar frontmatter profile,
+core line/byte budget, package symlinks, supported local link forms in all Markdown files,
+and [scenario definitions](evals/scenarios.json). It is not a general YAML/Markdown parser;
+it does not resolve heading anchors, check external URLs, or execute model evaluations.
+The installed folder name matches the skill metadata; renamed source checkouts are allowed.
+
+CI preserves the required `docs` check and gates it on Linux/Python 3.10 and macOS/Python
+3.13 utility checks, with ShellCheck on Linux. Actions are SHA-pinned with read-only contents
+permission and checkout credentials disabled. See [behavioral evaluation](evals/README.md)
+for the separate model/host evaluation procedure and its unrun status.
 
 ## License
 
-MIT
+[MIT](LICENSE). Original artwork and historical research remain in the repository.