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

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@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        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

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.