Skip to content

AGENTS.md

Latest commit

 

History

History
42 lines (26 loc) · 3.13 KB

AGENTS.md

File metadata and controls

42 lines (26 loc) · 3.13 KB

PAWL

What you see is a work in progress, aimed at the future. To make that future better, read on.

PAWL instruments and simulates the macOS Seatbelt through the interplay of system artifacts and project code. The hard part is assembling a structure that can speak with the host's vocabulary through its moving parts and notice when it stops speaking true. We are past the hard part.

Posture

This project is in a constant state of learning and change--backwards compatibility is an anti-pattern. You must:

  • Refactor to leave no shims behind. Downstream consumers will learn to write more tests.
  • Treat the working tree as intentionally dirty. Never chase working tree diffs.
  • Crashers are visions of the future. If libsandbox asserts (SIGABRT) during compilation, treat it as evidence: log the crasher before reporting back.
  • Adopt a paranoid stance toward testing. Tests are instrumentation for the future. Write them like you want your eyes open.
  • Document multiply at every layer. Docs, line-level code comments, CLI help text, and test messages are all first class documentation objects. They should be useful, informative, and most importantly, present. Avoid using code, tests, or documentation to convey stateful project information. All self-references outside of the root README should be stateless.

Finally, you must adopt a discipline about evidence that is iron-clad and stone-simple. If the honest answer is “we don’t know yet” or evidence conflicts, say so. Further graduation shades your view.

PLANning

Processes which change the repo state should be recorded in temporary PLAN.md files, local to the activity being planned. Prefer these files (or an equivalent SUBJECT-PLAN.md) over embedding stateful planning information in documentation. Generate, use, and eventually dissolve these PLANs as you work.

Python path

Use an explicit interpreter and PYTHONPATH for every Python command; do not rely on source .venv/bin/activate or the python alias, and always put the repo root on sys.path via PYTHONPATH.

  • From repo root: PYTHONPATH="$PWD" ./.venv/bin/python -m pawl.structure --help

Baseline

All claims are scoped to a host via a world_id, resolved from the baseline world in world/registry.json. Treat this as implicitly true rather than remarking on it. Call the doctor if you are unsure about your current host.

Location

Agents working on this project are frequently enclosed in a sandbox by their harness. Before testing sandbox policy, run inside to determine whether you need to disambiguate harness restraint from policy denial.

An incomplete router

  • Workbench logic lives in pawl/.
  • Problem-solving CLIs are often local to the subsystem you are touching. Check nearby README.md, AGENTS.md, and CLI entrypoints before inventing ad hoc scripts; use tools/ for shared development helpers such as path and hash functions.
  • Probe planning/orchestration lives in orchestration/ and probe execution lives in runtime/.

Agent instructions exist in local AGENTS.md files, scoped to their directory. As you work, treat guidance closer to you as more authoritative.