please-make-no-mistakes 0.0.0-stage → 0.1.0-bootstrap.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "please-make-no-mistakes",
+  "displayName": "Please, Make No Mistakes",
+  "version": "0.1.0-bootstrap.0",
+  "description": "Epistemic integrity for AI-assisted software engineering.",
+  "author": {
+    "name": "Jonathan Muñoz Lucas",
+    "email": "git@jonathanmunoz.dev",
+    "url": "https://github.com/elnonathan"
+  },
+  "homepage": "https://github.com/elnonathan/please-make-no-mistakes#readme",
+  "repository": "https://github.com/elnonathan/please-make-no-mistakes",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "software-engineering",
+    "code-review",
+    "debugging",
+    "verification",
+    "epistemic-integrity"
+  ],
+  "hooks": "./hooks/claude/hooks.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "please-make-no-mistakes",
+  "version": "0.1.0-bootstrap.0",
+  "description": "Epistemic integrity for AI-assisted software engineering.",
+  "author": {
+    "name": "Jonathan Muñoz Lucas",
+    "email": "git@jonathanmunoz.dev",
+    "url": "https://github.com/elnonathan"
+  },
+  "homepage": "https://github.com/elnonathan/please-make-no-mistakes#readme",
+  "repository": "https://github.com/elnonathan/please-make-no-mistakes",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "software-engineering",
+    "code-review",
+    "debugging",
+    "verification",
+    "epistemic-integrity"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/codex/hooks.json",
+  "interface": {
+    "displayName": "Please, Make No Mistakes",
+    "shortDescription": "Evidence-first discipline for software work",
+    "longDescription": "Investigates before changing a project, makes the evidence and uncertainty visible, keeps task knowledge in a user-controlled PMNM folder, asks for agreement on one plan Digest, verifies the result, and audits the complete change before the human commits.",
+    "developerName": "Jonathan Muñoz Lucas",
+    "category": "Developer Tools",
+    "capabilities": ["Read", "Write"],
+    "defaultPrompt": [
+      "Investigate this regression and show me the plan Digest before changing anything.",
+      "Review this change, verify its contract, and audit the full diff before I commit.",
+      "Resume this task from its PMNM folder and tell me what remains uncertain."
+    ]
+  }
+}

package/ARCHITECTURE.md

@@ -0,0 +1,236 @@
+# Architecture
+
+## Goal
+
+Please, Make No Mistakes packages one portable Agent Skill and an optional brake for Claude Code and Codex. Support for other coding agents is in progress. The skill guides investigation, agreement, implementation and verification. A separate folder preserves rules and task evidence. The brake can stop covered destructive or sensitive operations before they run, when its host sends them to the hook.
+
+The architecture keeps four claims separate:
+
+1. The portable skill describes how an agent works.
+2. The PMNM folder preserves what the agent learned, decided and verified.
+3. The brake may stop covered destructive or sensitive operations.
+4. Tests establish only the behavior and boundary they directly exercise.
+
+None proves semantic truth or guarantees an error-free result. `SKILL.md` states what the product asks of the agent and what it does not promise; every change is checked against it.
+
+## Repository layers
+
+```text
+please-make-no-mistakes/
+├── .claude-plugin/plugin.json        public Claude Code plugin manifest
+├── .claude-plugin/marketplace.json   repository marketplace catalog for Claude Code
+├── .codex-plugin/plugin.json         public Codex plugin manifest
+├── .agents/plugins/marketplace.json repository marketplace catalog for Codex
+├── hooks/
+│   ├── claude/hooks.json             Claude Code brake registration
+│   ├── claude/pmnm-claude.mjs        retired interlock adapter for Claude Code, unregistered
+│   ├── codex/hooks.json              Codex brake registration
+│   ├── pmnm-brake.mjs                destructive-operation brake for both hosts
+│   ├── pmnm-guard.mjs                retired interlock engine, unregistered
+│   └── pmnm-shell.mjs                retired interlock shell classifier, unregistered
+├── skills/please-make-no-mistakes/
+│   ├── SKILL.md                      portable kernel and reference router
+│   ├── agents/openai.yaml            Codex presentation metadata
+│   └── references/                   conditionally loaded procedures
+├── evals/                            activation, behavior and guard contracts
+├── scripts/                          release and distribution validators
+├── assets/pls.png                    README mascot
+├── SETUP.md                          canonical setup procedure
+└── public project documentation
+```
+
+`AGENTS.md` and `.ai/` are local coordination. They are ignored by Git, excluded by the package allowlist and forbidden from public artifacts.
+
+## Portable skill
+
+`SKILL.md` is intentionally small. It owns the four parts and says when, how and where to apply them:
+
+- one PMNM folder per machine, where the agent writes freely
+- the flow: investigate, show the plan Digest, work inside it, verify, audit, then hand over the Test Digest at the human acceptance boundary
+- rules: one sentence each, written only after an always or a never and one question about their level
+- guards: how to read a card and take its `NEXT:` action
+
+Its reference table is one level deep. A reference is loaded only when its condition applies. References add detail; they cannot weaken the kernel.
+
+The skill has no required MCP service, programming language, version control system, repository host, test runner or delivery system. It uses the strongest evidence channels the host offers and reports what their absence leaves unresolved. Semantic navigation and other graph providers may supply definitions, references, call edges or unresolved candidates, but their output remains evidence rather than scope authority or proof of runtime reachability. Public prose carries shapes with placeholders, never worked examples.
+
+## PMNM folder
+
+The installed plugin is replaceable. User knowledge is not. PMNM stores task knowledge and learned rules outside repositories and outside installed packages.
+
+```text
+<PMNM folder>/
+├── index.json
+├── general-rules.md
+├── commands.json               the brake's sealed verdicts
+├── models.json                 the agent's judge proposal; grants nothing
+└── projects/<project>/
+    ├── project-rules.md
+    ├── project-knowledge.md
+    └── tasks/<task>/
+        ├── index.md
+        ├── plan.md
+        ├── verification.md
+        ├── impact.md           required for Standard or High implementation with file targets
+        ├── expectations.md     required for High effort
+        ├── permissions.json
+        ├── environment.md      optional operational preflight for persistent local resources
+        ├── review.md           required for High-effort passed closure
+        ├── operation.md        optional package for consequential work delegated to another actor
+        ├── provenance.md       optional material attribution links
+        ├── artifacts.md        optional evidence custody record
+        └── artifacts/          optional deliberately retained copies
+```
+
+The host configuration contains only a pointer to this folder. Claude Code and Codex each use their own config location. Another host, which is not officially supported, must use its own supported configuration surface. All can point to the same folder.
+
+Startup follows one route. The agent reads only the host's documented literal pointer, stops for the missing folder or project answer, and performs the setup itself. It starts each task with an effort and a work type. The durable work type is `implementation`, `advisory` or `verification`. The retired interlock had a second route through guard receipts; it returns only if the interlock is restored.
+
+Task selection belongs to a session, not to the repository. A fresh session starts task-neutral. Several sessions may work on different task folders in the same project; each task keeps its own Digest, permissions and completion. No hook serializes two sessions that share a task, so each reloads the task files before writing to them.
+
+`index.json` has one writer: the agent, using the `pmnm.projects/v1` schema, so another host does not lose repository-to-project continuity. An unindexed path already present under `projects/` is preserved and treated as occupied; a new repository receives another collision-safe path rather than silently adopting it. The agent seeds four base task files and adds canonical `impact.md` when Standard or High implementation has file targets; it fills them, adds whatever else the task needs and never renames them. Optional provenance and artifact records have canonical names when their responsibilities arise, but their absence does not make an unrelated task incomplete. Everything else inside the folder is the agent's to organize, except the brake's `commands.json`.
+
+The folder asks the human exactly four things: where it goes, the project name, whether a candidate task folder is this task, and whether a new rule belongs to the project or applies generally. The task question appears only when an existing folder shares the id or a name that contains or normalizes to it.
+
+Containment and secrets are agent obligations first. A path or symbolic link that escapes the folder is not an internal PMNM write. The brake adds one check: it judges every edit by the real path where it lands, so a symbolic link cannot carry an edit out of the folder or onto a secret or configuration file, and it still stops deletions, moves and secret or configuration edits inside the folder. It does not scan content for secrets. The agent never writes a secret there; it keeps a reference to where the secret lives instead. An empty folder is seeded before its pointer is written. Invalid pointer or index state is preserved under a unique recovery name and rebuilt only after the human chooses that recovery. The folder is a continuity aid, not a secret manager or access control system.
+
+External evidence is reference-first. Copying or moving an artifact is a custody decision with an exact source, destination, purpose, privacy result, identity method, recovery and retention. Full-content digests can establish byte identity; visual or semantic similarity cannot. Provenance is relational as well: authorship, operation, observation, discovery, review, approval and causality keep independent evidence and status.
+
+## Plan authority
+
+The plan Digest is the human checkpoint before material work. Before showing it, the agent writes `plan.md`. It names each file the implementation will write, each file that must stay as it is, and each material state transition or invariant. Advisory work instead pairs each `deliverable` with a `boundary` that records the strongest alternative, exclusion or uncertainty and its disposition. File lines name paths and reasons. State lines name stable ids and explicit before and after values.
+
+Standard or High implementation with file targets also writes `impact.md`. It gives either a bounded local rationale or a transitive ledger whose roots were derived independently of the proposed plan. A persistent local-environment operation gets an `environment.md` preflight covering command indirection, current resources, ownership, health, conflicts, the reuse-or-start-only-missing decision and cleanup.
+
+One preflight checks the work type, plan, verification contract, applicable impact contract, required environment preflight and permission forecast before agreement. The agent reports every defect it finds together. The Digest then shows the human the understanding, current state, change, impact, verification, ambiguities and trade-offs. Each check names the wrong result it could expose. The agent stops until the human answers.
+
+Agreement binds the canonical set of file, state and deliverable objectives, in any order, with the actionable verification plan and permission forecast. Checking a box is progress, not a change of agreement. Safe absolute and relative spellings of the same repository path share one identity. A state already complete when its Digest is shown is historical: current evidence remains necessary, but the old operation is not replayed. A material reframe is recorded immediately; unrelated read-only investigation may continue, but dependent effects and final delivery wait for renewed agreement. No hook refuses a write to an absent or excluded file, a state-changing operation not bound to its objective, or stale deliverable closure. The agent must not make them, and the audit compares the actual changes with `plan.md`.
+
+A repository mutation enters the Digest path. An ordinary write inside the PMNM folder needs no approval. An external-only effect uses its own exact authority without inventing a repository plan. After startup, resume, clear or compaction, the agent reloads the canonical files that exist before material work on an active task: general rules, project rules, project knowledge and active-task context. It reloads canonical rules and project knowledge again immediately before curating them, so a concurrent revision is not overwritten silently. No hook checks that reload, the order of the steps or the shape of the Test Digest.
+
+Sensitive effects remain separate outside ordinary contained PMNM maintenance. Predictable exact operations and bounded reusable capabilities appear together in the plan Digest and can receive task or project scoped authority. A capability is described by effect, boundary, persistence, operation shape and constraints rather than supplied by an executable catalog. A state transition is task scoped and binds its exact operation to a planned objective. An unlisted state operation requires a revised Digest; other newly discovered sensitive effects need their own yes. The brake does not read the forecast: it still stops each covered destructive or sensitive operation until the human replies with its exact single-use token or, in Claude Code, answers the host's own prompt. Native host approval remains controlling.
+
+## Verification and closure
+
+Before claiming any passed verification, the agent writes two current lines in `verification.md`: the request's own case and what was observed, and the thing that must stay the same and what was observed. A state plan repeats each agreed state contract; an advisory plan records each deliverable and boundary observation. After a material change or reframe the claims must postdate it. Those lines are claims the human can read. No hook checks them, and nothing checks that they are true. A successful state operation proves only that the operation reported success, so resulting-state evidence remains separate. Command verification also needs an observed successful check against the current state, and human verification needs a later human turn. A syntax, metadata or documentation check remains investigation evidence while planned objectives are open; it cannot become final verification. A check that changes the project invalidates the prior Digest and returns to investigation.
+
+Closure always needs a current passed verification. It walks `plan.md`: every objective checked, every file target materially changed, every changing state objective supported by its exact successful operation and current evidence, every advisory deliverable tested against its boundary, every exclusion preserved and nothing material outside the plan. It separately re-derives impact roots from the actual changed surface or delivered claim, asks what material path or contract the plan omitted, completes dynamic-boundary and non-functional dispositions, and binds that omission audit to the current verification fingerprint when applicable. Plan conformance cannot validate its own completeness. A no-op or a file restored to baseline is not complete. Across revised Digests, a direct-comparison baseline retains earlier path identities and adds newly planned paths, so removing a path can neither hide nor manufacture a change. The final audit names file comparison and other evidence separately. A state- or deliverable-only task reports no project-file comparison instead of inventing one. It also names how many canonical rules or knowledge files the task wrote.
+
+A reviewer who did not write the change is a source of evidence at High effort or on request. The review packet binds the contract, changed surface and impact roots to the current plan hash and verification fingerprint, then records a concrete counterexample, a distinct check, an omission challenge, non-functional dispositions, disagreement and residual limit. Passed closure rejects a stale packet, repeated evidence or unresolved disagreement. No hook validates the packet. It cannot prove reviewer independence or semantic correctness, and the agent does not inherit the reviewer's verdict. If no non-author is available, an adversarial self-review remains explicitly partial and cannot claim independence or completeness.
+
+The Test Digest follows current verification, required review and the agent's final audit. It is the final human acceptance handoff, normally immediately before commit, submit or close. A passed or partial final audit can request that handoff; a blocked audit keeps the task open and does not arm acceptance. The later human response closes the task. Intermediate verification never triggers it.
+
+## Brake
+
+`hooks/claude/hooks.json`, declared by `.claude-plugin/plugin.json`, and `hooks/codex/hooks.json`, declared by `.codex-plugin/plugin.json`, register one module, `hooks/pmnm-brake.mjs`, with `--host claude` or `--host codex`. Both register it on `PreToolUse` and `UserPromptSubmit`. In Claude Code it covers every tool; in Codex the tool matcher is `Bash|apply_patch|Edit|Write|mcp__.*`. The package carries no conventional `hooks/hooks.json`, because Claude Code would merge that file into the Claude plugin. The brake knows nothing about tasks, plans or Digests.
+
+The brake imports only Node.js built-in modules and runs no program except the host's own command-line client as its judge. Package validation enforces that boundary and an inspectable size budget.
+
+For each covered tool call it decides in two layers:
+
+1. Deterministic rules place known shapes as safe, sensitive or destructive, including commands inside wrappers, substitutions and heredocs. A compound command takes its most severe segment. Code that runs other code is classified by what it runs.
+2. What the rules cannot place goes first to a sealed stored verdict, then to the judge model the human confirmed. Only a safe verdict with high confidence runs without asking.
+
+A stop prints a card: `Blocked:` or `Ask:` with what happened, one `NEXT:` line with one exact action, and, when the human can approve by reply, the `PMNM-<code>` token alone on a last line. `Blocked:` covers a destructive operation, an operation that reaches the brake's own state, an operation the brake could not evaluate, and the Claude Code load stop. `Ask:` covers any other stop. For a destructive or sensitive operation, the `NEXT:` line tells the agent to show the human the exact operation; it runs only if the human replies with its exact `PMNM-<code>` token, or runs it themselves. Some cards carry no token: the brake's own state, an evaluation error, the load stop, full or busy approvals, and an event without a session id. In Claude Code a deterministic sensitive operation uses the host's own permission prompt instead of a card. A failed or unavailable classification asks. An error the brake catches while evaluating blocks. A brake that runs past its time limit or cannot start is handled by the host, which may let the operation run.
+
+On `UserPromptSubmit` the brake recognizes the human's exact prompts: an approval token grants one rerun of that operation in that session, and the judge confirmation and MCP allowlist prompts change sealed state. The agent cannot send a prompt. When the judge needs a confirmation or a re-evaluation, the brake adds one notice to the agent's context, once per change, and the agent relays it to the human.
+
+On the first prompt of each session the brake adds one line asking the agent to load PMNM. In Claude Code, when the agent has not loaded the skill with the Skill tool, the brake stops the first tool call that can touch the project once per session, with a card that asks the agent to load it. The next call runs whether or not the agent did. The human's exact prompt `PMNM-SKIP` turns that stop off for the session. Codex has no load stop.
+
+An operation that reaches the brake's own state is blocked on both hosts, before any grant is spent and with no token, so only the human can run it.
+
+Under the host's plugin data directory, in `brake/`, the brake keeps a secret key, pending approvals and one-time grants, the confirmed judge, the MCP allowlist, hashes of the sessions that received the load line and of the sessions that loaded the skill, the notices already shown, and decision counts. Every entry carries a seal made with that key, except the notices and the decision counts, which grant nothing. In the PMNM folder it writes only `commands.json`. Nothing in the PMNM folder grants authority by itself.
+
+It cannot:
+
+- understand product intent or check the flow
+- prove a model statement true
+- prove that a safe verdict makes an operation harmless
+- catch every obfuscated command
+- intercept an event the host does not deliver
+- replace the host sandbox, operating system permissions or native approval controls
+
+Disabled, untrusted, unsupported, failed, or bypassed paths leave the portable skill in advisory mode. This is a disclosed reduction in enforcement, not permission to claim the brake ran.
+
+## Host port contract
+
+Another host may run the brake through its own lifecycle API. Such a port is not officially supported. It must be designed, tested, installed and documented independently. Similar event names do not establish equivalent semantics.
+
+A port must preserve:
+
+- deterministic rules that take precedence over stored verdicts
+- two card levels, `Blocked` and `Ask`, each with one `NEXT:` action, or the host's own permission prompt where it has one
+- the human's exact operation-bound, session-bound and single-use approval token, which the agent cannot send
+- sealed state outside the PMNM folder
+- a failed classification that asks and an evaluation error that blocks
+- one PMNM folder and a host-local pointer
+- disclosure of uncovered paths
+
+Both hosts register one brake module, `hooks/pmnm-brake.mjs`, selected by `--host`. The module owns each host's output shape and has host decision tests for both. Codex has no native ask, so it always uses the token. Portable behavior lives in the skill and the PMNM folder.
+
+## Retired interlock
+
+Earlier releases shipped one portable Agent Skill packaged with an optional Codex procedural adapter and an optional Claude Code procedural adapter instead of the brake. Each adapter enforced a small set of observable ordering rules for the lifecycle events its host sent it. Their source stays in the package, unregistered: the engine `hooks/pmnm-guard.mjs`, its shell module `hooks/pmnm-shell.mjs` and the Claude Code adapter `hooks/claude/pmnm-claude.mjs`. None of it runs now. This section describes how the interlock works once restored; [Restoring the interlock](docs/architecture-decisions.md#restoring-the-interlock) lists the steps and the defects to fix first.
+
+`hooks/pmnm-guard.mjs` owns bounded host-provided state and imports one local pure module, `hooks/pmnm-shell.mjs`, for shell structure, target evidence and narrow hard stops. The module contains no positive executable catalog. Operation admission keeps classification evidence, human authority and host execution or result as independent stages. Ordinary operations use a structured model declaration, then a separate human-agreed capability or exact authority when needed; satisfying one stage does not erase or manufacture another. Neither module has a registry dependency. For the interlock, distribution validation accepts exactly this two-file local graph beside the brake, rejects links and escaping or unlisted modules, and enforces explicit per-file and aggregate inspectability budgets. Its cards have two lines: `Blocked`, `Ask` or `Note` with what happened, and one exact `NEXT:` action. A NEXT line is an order: one verb, its limit, and who acts next.
+
+The guard tracks ordering, freshness, target geometry and scope. It owns `index.json`, seeds the task files and writes every preflight issue and safe canonicalization to guard-owned `preflight.md`. Lifecycle discontinuities make the session's durable basis stale until the agent reloads the canonical files that exist. A covered successful read correlates through host operation identity when available and counts only when the result returns the current file bytes. On Codex Stop events the guard inspects only the latest assistant message for the current Test Digest. If Codex omits that Stop event, the next human prompt may recover only the latest assistant message from a fixed-size tail of the literal host-provided transcript path. That transcript schema is unstable: unreadable, linked, oversized, malformed, unsupported, stale or unrelated evidence fails closed, and neither the path nor the message is retained. Both routes check only shape and freshness. They cannot establish the message's truth, judge whether the investigation was sufficient, know whether the rules were understood or know whether the human understood the plan.
+
+The interlock adapter may:
+
+- establish a PMNM folder pointer and project mapping
+- block the first project read without an open task
+- require a task before a covered write and a fresh `plan.md` before a Digest
+- aggregate plan, verification, impact and permission defects before asking for agreement
+- block a project write until the Digest is agreed, a write outside the plan before it runs, and an unbound state-changing operation
+- allow writes inside the PMNM folder while containing inspected paths and refusing detected secret-shaped content on covered write channels
+- bind a reviewed permission forecast to exact operations or bounded task and project capabilities, while binding state changes only to task objectives
+- distinguish project, contained PMNM and external-only targets before choosing an authority path
+- split unknown compound commands and commands with several sensitive effects
+- require an exact structured effect declaration when host metadata is absent, without trusting an executable name
+- let one plain same-turn declaration or already agreed capability classify exactly the next otherwise-unknown operation; discard unused intent at the existing boundaries, but retain a legitimately applied exact classification across its separate authority decision until that same operation is admitted
+- observe non-persistent verification without presuming a project write, and render its card from the observed workspace delta rather than task phase
+- account for missing, failed and late results
+- require fresh verification claims, a current impact omission audit, a complete audit and a current semantic review packet for High-effort passed closure
+- reconcile unfinished task transitions once and isolate the successor's task-scoped state
+- keep transient state per session, reusable authority per project and implementation authority per task, with revision checks when sessions share a task
+- require durable rule reload after startup, resume, clear or compact before material work on an active task
+- require fresh canonical rule and project-knowledge context before a curation write
+- require a complete operational preflight before persistent local-environment authority enters a Digest
+- print a bounded source fingerprint and name file comparison and state evidence separately
+
+A host adapter for the interlock must preserve:
+
+- the twelve public receipt meanings and the three card levels
+- two-line cards with one `NEXT:` action
+- one PMNM folder and a host-local pointer
+- free contained task-folder writes without per-file approval
+- `plan.md` agreement before file or state implementation and refusal of out-of-plan effects
+- the human's exact operation-bound approval token for each unforecast sensitive effect
+- current verification claims, a passed verification and a complete audit before closure
+- disclosure of uncovered paths
+
+The Codex and Claude Code adapters call one shared transition engine. Each adapter owns host event parsing, output shape and its own conformance tests.
+
+## Evidence and evaluation
+
+Evaluation is layered:
+
+1. Activation cases test whether the skill is selected for the right requests.
+2. Blind decision cases test routing without exposing expected answers to the model.
+3. Behavior cases test observable collaboration, investigation, verification and continuity.
+4. Brake tests cover classification, approval tokens, sealed state and host decisions. The retired interlock keeps its guard cases, action oracle and adapter tests for rollback.
+5. Install smoke compares exact source and installed skill bytes.
+6. Live trials test discovery, trust, model behavior and real host delivery.
+
+Passing a lower layer does not prove a higher one. A syntax validator does not prove behavior. A synthetic hook event does not prove the host delivered it. A passing test does not prove the entire product contract.
+
+The release gate runs every deterministic package check and reports all failures. Live acceptance follows against the exact installed candidate. Any material change invalidates the checks whose subject changed.
+
+## Distribution boundary
+
+The npm artifact contains the portable skill, the optional destructive-operation brake for Claude Code and Codex, the retired interlock source (unregistered), public documentation, reusable evaluations and deterministic validators. It declares no runtime registry dependency and no npm lifecycle script.
+
+The package excludes repository automation, marketplace source metadata, private coordination, user PMNM folders, generated test output and credentials. npm transports exact bytes; it does not register a plugin, activate a skill, trust a hook or prove a conversation loaded that revision.
+
+Repository source, packed artifact, marketplace entry, installed plugin, enabled plugin, trusted hook and loaded conversation are distinct states. `SETUP.md` owns their installation, update, rollback, removal and verification sequence.

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable user-visible changes are recorded here.
+
+## 0.1.0 - 2026-11-09
+
+First public release. PMNM brings a portable Agent Skill, a folder for task context and rules, and an optional brake to Claude Code and Codex. Together they help an agent keep evidence and decisions attached to the work.
+
+Orders and rule layers
+
+- The skill is written as orders: each block states its intent, the end state to leave and at most five numbered orders with stable ids, such as `IN-2`. PMNM sets the phases and stops; the agent chooses how to carry out each order.
+- `SKILL.md` is a short core that survives compaction. It opens with a reading map naming the reference to read before each step, keeps every order that can fall due before a reference is read, and stays under 12,000 characters of body. Other orders moved to their references word for word with their ids. After compaction the agent rereads the core from the directory the host loaded it from, then only the reference its next step needs.
+- Rules come in layers: PMNM orders, the human's general rules, project rules, task rules and the current instruction. A higher layer extends, narrows or replaces a lower rule by its id. Rules carry `G-`, `P-` or `T-` ids, are never renumbered, record their basis (the human's literal words or `agent-worded`) and move to a `Retired` section instead of disappearing.
+- Human authority comes only from the human's own recorded words. Relayed agent text, summaries, repeated notes and one-round permissions do not become decisions or rules; `decisions.md` keeps who chose each decision and every autonomy grant with its scope and end.
+- When no one else can review, the author runs a labelled author audit and reports `ready for commit` with `(author audit)`.
+- New orders: names only from a listing or a read; proof that a new test can fail; results marked as own run, own reading or reported and tied to the exact tree; no weakened tests; databases discovered and accessed read-only first; nothing of the working method in publishable artifacts; a minimal decision tree that runs one scenario through every option.
+- The Codex hook configuration lives in `hooks/codex/hooks.json` and is declared in `.codex-plugin/plugin.json`; the Claude Code one lives in `hooks/claude/hooks.json`. The package carries no conventional `hooks/hooks.json`, so each host loads only its own registration.
+
+The folder
+
+- One PMNM folder per machine, chosen by the human once; the host keeps only a pointer to it.
+- One project folder per repository, named by the human once; reusable project knowledge stays separate from human-owned rules; one task folder per unit of work with `index.md`, `plan.md`, `verification.md` and `permissions.json`, plus `impact.md` for Standard and High work and `expectations.md` and `review.md` for High work.
+- Task-folder writes need no per-file approval.
+- Four questions only: where the folder goes, the project name, whether a candidate folder is this task, and the level of a new rule.
+- Optional `provenance.md` keeps material attribution as separate evidence-bearing relationships, without treating proximity or participation as responsibility.
+- Optional `artifacts.md` records reference-first custody, content identity, privacy limits, recovery and retention for external evidence; exact retained copies may live under `artifacts/`.
+- Optional `operation.md` separates executor, observer, cost, stop conditions and evidence context when consequential work is delegated.
+
+The flow
+
+- Investigate, write `plan.md` and show the plan Digest, then stop until the human answers.
+- Implement only inside the agreed plan.
+- Plan material non-file state with explicit before and after values, bind its exact task operation, and keep resulting-state evidence separate from operation success.
+- Plan material advisory work as a deliverable paired with its strongest relevant boundary; a reframe leaves independent reads available but requires renewed agreement before dependent effects or final delivery.
+- Require an actionable verification plan before Standard or High implementation; verify with claims the human can read, complete the agent audit and any required review, then hand over a complete Test Digest at the final human acceptance boundary.
+- Persistent local-environment operations require one current preflight covering command indirection, resources, ownership, health, conflicts, reuse or start-only-missing and cleanup.
+- Trace a material value across producers, transformations, boundaries, consumers, variants and precedence only when that lifecycle can change the solution or its evidence.
+- Standard and High implementation now records either a concise local impact rationale or a transitive ledger in `impact.md`; unresolved nodes, untouched placeholders, duplicate identities and contradictory boundary declarations block the plan Digest, while Light and state-only work avoid an empty graph ceremony.
+- Final audit derives impact roots again from the actual changed surface, challenges omissions separately from plan conformance and records dynamic and non-functional dispositions against the current verification fingerprint.
+- Agreeing to the implementation plan alone is not a yes to commit, push, tag or publish. An exact operation in the permission forecast may receive authority with that agreement; otherwise each needs its own yes at the time or a human-owned rule, and native host controls still apply. The brake does not read the forecast. It still stops each covered destructive or sensitive operation for the human's exact token or, in Claude Code, the host's own prompt.
+
+Rules
+
+- A decision stays with its task; a rule is one sentence born from an always or a never, with its origin, at the project or general level.
+- A newer rule that contradicts an older one replaces it.
+- A standalone approved rule write may end without an artificial implementation Digest; rule writes inside broader work do not waive its normal gates.
+- Audit-time curation promotes only corroborated reusable knowledge, records task-local dispositions, reloads canonical files before writing and checks concurrency, overlap, contradiction, audience and overfitting.
+
+Destructive-operation brake
+
+- Both plugins register one dependency-free Node.js hook, on tool calls and on the human's prompts. It classifies each covered operation as safe, sensitive or destructive.
+- Deterministic rules recognize deletions, overwrites, history rewrites, service stops and restarts, publication, datastore drops and deletions, plugin changes, reads of credential files and commands that print secrets, such as environment dumps, keychain reads and token printers, including when they are hidden in wrappers, substitutions, heredocs or local scripts.
+- The brake reads a shell command through bash's whole quoting layer: backslashes, single, double, `$'…'` and `$"…"` quotes, and line continuations. It does not resolve expansions: a variable, a command substitution or brace expansion inside a path, an alias or a function.
+- Anything that runs other code is classified by what it runs: local and sourced scripts by content, package scripts by their manifest entry, make targets by their recipes, `find -exec`, `trap` and `awk` by the command they carry, and a literal container exec by its visible inner operation. Test runners stay ordinary project work.
+- MCP tools are placed by name. Every tool of semantic-js-mcp, by the same authors, is known and safe, except a tool named for destruction. It is matched by the exact server names the hosts give it; a name is all the hook sees, so a server registered under one of those names would get the same trust. Any other MCP server runs without the judge only after the human sends the exact prompt `PMNM-ALLOW-MCP <server>`, which the agent cannot send; the entry is sealed, `PMNM-REVOKE-MCP <server>` removes it, and a tool named for destruction still stops.
+- Approval tokens are `PMNM-` and four random characters without look-alikes, such as `PMNM-7K2Q`, printed alone on the card's last line so they can be copied whole, accepted in any letter case and with surrounding spaces, bound to one operation and session, and spent by their use. An open token lasts 60 minutes; the human's reply turns it into a grant that the next run of the same operation spends within 10 minutes. A reply that matches no open token says it expired, was used or belongs to another session. Approvals are re-read under a lock before each write, so concurrent sessions do not erase each other's tokens, and an open token or grant is never evicted: past 8 open tokens in a session, or 128 across sessions, the operation stops with no token and says so, and past 128 unused grants the reply is not applied and says to send it again after one is used or expires. When another session holds the lock, the operation stops with no token and says to retry, and a reply says to send it again. An event without a session id cannot be approved in-band.
+- An operation that reaches the brake's own state is blocked on both hosts with no token, before any grant is spent, so only the human can run it: by any spelling of its path, by a glob that can match it, or through a hardlink or symlink to one of its files.
+- What the rules cannot place goes to the judge model the human confirmed with the prompt `PMNM-CONFIRM-JUDGE <host> <model>`, through the host's own command-line client with plugins and hooks off. Its answer carries a safety and a confidence.
+- A `PMNM_JUDGE_MODEL` set in the human's own environment pins the judge for that environment. A command that sets it, or the judge's recursion guard `PMNM_JUDGE_ACTIVE`, is destructive.
+- The brake never picks the judge model. As soon as no judge is confirmed the agent proposes, before continuing its task, the cheapest model the host can run, from each provider's current published documentation with its URLs and never from local caches; when PMNM cannot list a host's models, it asks the human which ones they can use. The human confirms the proposal or names another model with that prompt, and the brake keeps the confirmation sealed. For Codex the brake checks the model against Codex's catalog and asks for a re-evaluation when the offer changes. For Claude Code, which keeps no catalog, the confirmation alone names the judge. `models.json` holds the agent's proposal and grants nothing. Without a confirmed model, or when it stops answering, what the rules cannot place needs approval; no other model is tried in its place.
+- Only a safe verdict with high confidence runs without asking. Every other operation stops until the human replies with the exact operation-bound `PMNM-<code>` token; in Claude Code a deterministic sensitive operation uses the host's own permission prompt.
+- `commands.json` keeps model and human verdicts by a hash of the exact operation, with a seal made with a key kept in the host's plugin data; it never stores the command or any free text from the judge, which answers only with a safety and a confidence. An unsealed or copied entry grants nothing. A stored safe verdict runs without the model; a stored sensitive or destructive one asks directly. Deterministic rules always win over stored verdicts, and an edited script invalidates its verdict.
+- A failed or unavailable classification asks; an error inside the brake blocks.
+- On the first prompt of each session the brake adds one line asking the agent to load the PMNM skill before reading the project: with the Skill tool in Claude Code, from its `SKILL.md` in Codex. In Claude Code, when the agent has not loaded it with the Skill tool, the first tool call that can touch the project is stopped once, with no token, and the stop says how to load the skill. The human's prompt `PMNM-SKIP` turns the stop off for one session. Codex is not stopped. Sessions are remembered only as hashes.
+- Edits inside the PMNM folder are ordinary editing, like edits inside the working directory. A folder that holds the home directory or overlaps the host configuration, the brake's data or its code frees nothing, and secret files, configuration files and deletions there still stop. Every edit is judged by the real path where it lands, a patch's move destination included, so a symlink cannot lead it out of the working directory or the folder or onto a secret or configuration file. Secret and configuration names match in any letter case, and paths are compared in the letter case stored on disk.
+
+Retired procedural interlock
+
+The interlock below is no longer registered by either plugin. Its source stays in the package for rollback, and [architecture decisions](docs/architecture-decisions.md) records why each part was retired, what may get worse and how to restore it.
+
+- Twelve receipts; two-line cards in English or Spanish with one literal `NEXT:` action; three levels: Blocked, Ask, Note.
+- The output of a `pmnm-guard` run in a shell was never a guard card.
+- Predictable exact sensitive operations may be approved together with task or project scope; changed and unlisted operations still ask, and one-off authority remains exact and single-use.
+- Ordinary commands now use one structured effect-declaration path rather than positive executable catalogs. Declarations name effect, boundary, persistence, certainty and capability, but never grant their own authority or override mechanical hard stops.
+- A plain same-turn declaration or already agreed capability may classify exactly the next otherwise-unknown operation before a deliberate first denial. Unused intent is spent by that operation or expires at the existing boundaries; once applied, its exact classification remains independent from human authority until that same operation is admitted. Changed input cannot borrow either classification or authority, and native host review remains controlling.
+- Non-persistent verification cards now report a project mutation only when the observed workspace delta shows one, rather than inferring it from task phase.
+- Non-persistent verification follows the read path and becomes a project mutation only when its observed result changes the project.
+- Human-approved task or project capabilities can cover bounded recurring operation families without tying PMNM to a runtime, language or provider; task capability expires with the task and an explicit project replacement revokes reusable authority.
+- The verification plan and permission forecast remain bound after agreement; changing either requires `redo` before implementation or forecast use continues.
+- A missing project mapping records the name only after the human supplies it; the guard cannot answer its own question.
+- Project, contained PMNM and external-only targets take distinct authority paths; external-only work does not invent a repository plan.
+- Compound commands with an unknown segment or several sensitive effects are split before authority is requested.
+- Passed closure requires current `example:` and `unchanged:` claims plus current passed verification; no-op and restored writes do not satisfy a plan.
+- High-effort passed closure requires a current semantic review packet bound to the plan and verification fingerprint, with a concrete counterexample, distinct independent check, impact challenge, disagreement and residual limit. Its seed names every required field, and only a literal `none` resolves disagreement; the guard rejects stale or unresolved packets without treating the reviewer as truth.
+- Revised plans preserve the direct-comparison baseline for earlier paths while adding newly planned paths.
+- Existing unindexed project folders are preserved instead of being silently adopted by a new repository mapping.
+- Compound commands cannot hide an ordinary external write beside another sensitive effect.
+- Guard state separates session-local flow, canonical project authority and canonical task authority. Concurrent sessions may work on different tasks; a fresh session inherits none, and same-task revision drift blocks stale material work.
+- Restarting the same task cannot discard an in-flight host result; it remains pending until reconciled before task runtime is reloaded.
+- Startup, resume, clear and compact lifecycle discontinuities require reloading general, project and active-task context before material work; changed applicable rules invalidate the prior basis.
+- Lifecycle reload names only existing canonical files, includes project knowledge and applicable `impact.md`, and correlates successful returned bytes by host operation identity; a path mention is not evidence of a read, and a read is not proof of comprehension.
+- Earlier receipt names are accepted for one compatibility release.
+- Complete streamed content identity prevents a byte-identical rewrite of a large planned file from appearing as a material change.
+- Related suffix tasks with the same bounded work id are reconciled instead of silently fragmenting one activity.
+- After current verification, required review and final audit, Codex Stop requires one actionable Test Digest in the latest assistant message and a later human response before closure.
+- Test Digest validation now requires its exact task title plus contiguous, ordered, non-empty fields in English or Spanish, and the rejection card exposes that grammar.
+- If Codex omits the final Stop event, the next prompt can recover only the latest shaped Test Digest from a bounded, unlinked, host-provided transcript tail; unsupported evidence fails closed and is never retained.
+- Pending host results now outrank new declarations, blocked audits remain open without arming acceptance, and task cards distinguish observed paths, internal work counters and current verification without inventing file or verification claims.
+- Certain non-persistent verification remains on the read path across a mixed boundary; persistence, uncertainty and mechanical or sensitive effects still fail closed.
+- A receipt that reaches the shell switches explicitly to portable advisory behavior instead of triggering PATH searches or retries.
+- State-only and mixed plans close against their own objectives without invented file targets or version-control evidence; unlisted state operations require a revised Digest.
+- Digest preflight now reports all plan, verification, permission and required operational-environment defects together in guard-owned `preflight.md`, including safe path canonicalizations.
+- Safe absolute repository paths and their relative spellings share one contract identity; representation-only normalization does not withdraw unchanged agreement.
+- A state objective already complete at Digest time keeps its historical operation while still requiring current evidence.
+- Switching away from unfinished work asks once and isolates the successor from the prior task's agreement, counters and task permissions.
+- Literal container exec commands are classified by their visible inner operation; opaque inner commands remain unknown.
+- Investigation and administrative checks cannot activate final passed verification while planned file objectives remain open.
+- Sensitive-operation cards print an operation-bound approval token. Only an exact later human reply arms the single-use `allow` receipt for those command bytes.
+- Task start records `work=implementation`, `work=advisory` or `work=verification`. Advisory plans reject file and changing state objectives before agreement.
+- Native project reads still route to `start` before execution. Opaque operations declare their boundary first, and only a declared project read then routes to `start`.
+- The Codex adapter is split into a bounded state-machine entrypoint and an independently reviewable shell classifier, with an exact packaged module graph and aggregate size budget.
+- The guard reference matches the engine: the exact approval token applies to `allow`, a project read before `start` is blocked on its first attempt, and each host reaches one shared engine through its own adapter. The Claude adapter also runs when its plugin directory is a symbolic link, including under `--preserve-symlinks-main`.
+
+Package
+
+- Exact-version npm artifact and repository marketplace, with no runtime dependency and no lifecycle script; package installation is not host activation.
+- Claude Code marketplace `.claude-plugin/marketplace.json` pinning the same npm version as the Codex marketplace, with its SETUP route, update, rollback and removal steps and the pointer `<CLAUDE_CONFIG_DIR>/pmnm.path`. The marketplace is validated but not packaged.
+- MIT license for original project materials and a separately disclosed AI-generated mascot.

package/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing
+
+Please, Make No Mistakes has one portable Agent Skill and an optional destructive-operation brake for Claude Code and Codex. Start with the behavior you want to improve in `skills/please-make-no-mistakes/SKILL.md`. A contribution should make a demonstrated failure less likely without turning one person's project or tools into a rule for everyone.
+
+## Requirements
+
+- Node.js 22 or 24 for the brake and JavaScript tests
+- Python 3.9 through 3.13 for dependency free release validators
+- no runtime registry dependencies
+
+## Before Changing Behavior
+
+Start from an observable failure, an accepted design decision or a bounded compatibility requirement. Record what currently happens and which check would distinguish the desired behavior. Add the smallest failing evaluation before changing the runtime when a deterministic surface exists.
+
+When a model misses an instruction, improve the instruction first. Add a guard only when a real trial shows that the instruction alone does not hold and the host provides a reliable event to check.
+
+## Writing Rules For Models
+
+- State the pattern, never a worked example. Public prose and cards use shapes with placeholders; an example teaches the instance, not the rule.
+- A card's `NEXT:` line is an order. It uses one imperative verb, or a short sequence joined by "then", and names the limit and who acts next. It gives the agent one action, with no alternatives to weigh or extra explanation. Waiting belongs to the human, never to the agent. A brake card tells the agent to show the exact operation and approval token, or says that only the human can run it. The skill's own stopping order is literal: `stop here; no more actions until the human answers`.
+- A claim the hook cannot observe is not written on a card. The hook states what it recorded, not what the model meant.
+- A small model must be able to read the sentence and act on it. When it cannot, the sentence is wrong, not the reader.
+
+## Source Of Truth
+
+- `skills/please-make-no-mistakes/SKILL.md` owns the portable kernel and reference routing.
+- `skills/please-make-no-mistakes/references/` owns condition specific procedures.
+- `hooks/pmnm-brake.mjs` owns classification, approval tokens, sealed state and cards for both hosts; `scripts/test_brake.mjs` owns its tests.
+- `hooks/pmnm-guard.mjs`, `hooks/pmnm-shell.mjs` and `hooks/claude/pmnm-claude.mjs` are the retired interlock, unregistered and kept for rollback.
+- `evals/host-guard-cases.json` owns the retired interlock's stable guard claims, kept for rollback.
+- `evals/host-guard-action-oracle.json` owns the retired interlock's normalized Codex event sequences and expected actions, kept for rollback.
+- `evals/activation-cases.json` and `evals/agent-evaluation-cases.json` own model selection and blind routing fixtures.
+- `evals/behavior-cases.md` owns observable portable behavior cases.
+- `scripts/documentation_contract.py` owns public documentation invariants.
+- `SETUP.md` alone owns detailed installation, update, rollback, removal and verification commands.
+
+Private coordination under `.ai/` can explain intent and preserve evidence. It never changes public behavior by itself.
+
+## Host Isolation
+
+Do not extend the brake to a host by resemblance. Preserve the brake's behavioral outcomes, then implement each host's input and output against its documented native events and test them independently.
+
+Changes to the brake must not silently redefine the portable skill. Changes to the portable skill must not claim enforcement that no host provides.
+
+## Focused Checks
+
+Run the narrow check while iterating:
+
+```text
+npm run test:brake
+```
+
+For the retired interlock source:
+
+```text
+npm run test:host-guard
+npm run test:claude-adapter
+```
+
+For the Claude Code hook registration:
+
+```text
+npm run test:claude-discovery
+```
+
+For documentation changes:
+
+```text
+npm run test:documentation
+```
+
+For blind decision fixtures:
+
+```text
+npm run smoke:evaluation
+```
+
+Before a release readiness claim:
+
+```text
+npm run release:verify
+```
+
+Each check must state what it can falsify. A validator pass is not behavioral evidence from a live model or host.
+
+## Documentation Ownership
+
+- `README.md` explains the product and routes setup elsewhere.
+- `SETUP.md` is the single detailed setup procedure.
+- `ARCHITECTURE.md` describes component and trust boundaries.
+- `docs/architecture-decisions.md` records durable public rationale.
+- `docs/distribution.md` owns release identity and supply chain procedure.
+- `docs/getting-started.md` explains expected use.
+- `SECURITY.md` owns supported security claims and reporting.
+- `CHANGELOG.md` records user visible release changes.
+- `ROADMAP.md` records deferred public work without promising dates.
+
+Do not duplicate setup commands outside `SETUP.md`. Do not publish local paths, private task folders, raw internal evaluations, credentials, customer data, internal identifiers or maintainer handoffs.
+
+## Evaluation Changes
+
+A behavior change needs:
+
+1. a case that failed before the change
+2. the smallest implementation that closes it
+3. a negative or adversarial case where overreach would be harmful
+4. exact test results and remaining limits
+
+Blind evaluation inputs must not contain their expected decision. Deterministic graders may keep expected outcomes in code, separate from the prompt sent to a model.
+
+Model trials must record the exact skill and guard identity, host, model, effort, available tools, prompt, source fixture, human turns, writes, verification and cleanup. Sanitize private source and personal data before publishing any result.
+
+## Pull Requests
+
+Describe the observed problem, contract change, evidence, affected public surfaces, tests run and residual risk. Keep unrelated cleanup separate. Do not claim installation, hook trust or live behavior from package validation alone.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 please-make-no-mistakes contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.