assayhq 0.1.0__tar.gz

assayhq-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 haqaliz
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

assayhq-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: assayhq
+Version: 0.1.0
+Summary: Execution-grounded security verifier for AI agent skills
+Keywords: ai-agents,security,sandbox,agent-skills,verification
+Author: Ali Haqiqi
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Dist: pyyaml>=6
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/haqaliz/assay
+Project-URL: Repository, https://github.com/haqaliz/assay
+Project-URL: Issues, https://github.com/haqaliz/assay/issues
+Project-URL: Changelog, https://github.com/haqaliz/assay/blob/master/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Assay
+
+**Execution-grounded security verifier for AI agent skills.** Runs a skill in a sandbox against a
+real agent, captures what it actually did, and checks that against what it claims to do.
+
+[![Status](https://img.shields.io/badge/status-A1--A7%20+%20A8%2FOpenClaw%2BCursor%20+%20A10%20·%20offline-orange)](docs/ROADMAP.md)
+[![CI](https://github.com/haqaliz/assay/actions/workflows/ci.yml/badge.svg)](https://github.com/haqaliz/assay/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+[Vision](VISION.md) · [Roadmap](docs/ROADMAP.md) · [Architecture](docs/technical/ARCHITECTURE.md) · [Capabilities](docs/technical/CAPABILITY_ROADMAP.md)
+
+---
+
+## Install
+
+Sandboxed checks require macOS. Install the CLI with `uv` or `pip`:
+
+```sh
+uv tool install assayhq
+# or
+pip install assayhq
+```
+
+From a checkout, `uv sync --dev` then `uv run assay ...` works too.
+
+## Status
+
+**A1–A7 exist, plus two A8 adapters (OpenClaw/ClawHub and Cursor rules) and the A10 static
+pre-filter; the engine has a verdict, a portable record and a measured benchmark.** What is built and
+tested, all offline (the bundle tests run a local `ssh-keygen`; the benchmark makes no model or
+network call):
+
+- **Ingest** (`src/assay/ingest/`) — parses a Claude Code `SKILL.md`, an OpenClaw/ClawHub
+  `SKILL.md` (format plus `metadata.openclaw` requirements), and a Cursor project rule (`.mdc`,
+  `globs`/`alwaysApply` as file scope) into a frozen `Skill` record with a tri-state declared scope
+  (undeclared vs declared none) and a named refusal for malformed input. A declared
+  `env`/`config`/`os` requirement the jail cannot satisfy, or a missing required binary, is refused
+  before a run with `UNVERIFIED/REQUIREMENTS_UNMET`.
+- **Sandbox** (`src/assay/sandbox/`) — runs a command under a macOS Seatbelt jail: writes confined
+  to a run root, network deny-by-default with a port-scoped allowlist, a scrubbed environment,
+  CPU/wall limits, and a capture channel the child cannot rewrite.
+- **Agent driver** (`src/assay/agent/`) — a bounded BYOK loop: the model runs outside the jail, every
+  tool call runs inside it, with cost, step, action and wall caps and a named stop cause.
+- **Capture and diff** (`src/assay/capture/`) — turns a run into a canonical, content-addressed
+  trace of file, network, shell and instruction events and diffs it against the declared scope.
+- **Verdict and strictness** (`src/assay/verdict/`) — turns that diff into one `Assessment` with a
+  `CLEAN/FLAGGED/MALICIOUS/UNVERIFIED` verdict, findings with evidence, a named cause when
+  undecidable, and a `blocked` flag. The four-class severity floor cannot be lowered.
+- **CLI** (`src/assay/cli/`) — `assay check <skill>` composes A1–A5, saves the trace, prints a
+  human or canonical JSON report, and exits `0` only on `CLEAN`.
+- **Signed bundle** (`src/assay/bundle/`) — turns a saved trace and its `SKILL.md` into one
+  canonical record with the exact skill source, the observed trace, the sandbox config hashes and
+  the verdict, signed with `ssh-keygen`. `assay verify` checks the hashes and the signature offline,
+  re-parses the embedded source and re-runs the shipped verdict layer; a signed assessment that does
+  not follow from the record is refused. The bundle proves the record is intact, who attested it,
+  and that the verdict follows from the recorded inputs. It does not prove the run happened or that
+  the skill is safe.
+- **Labeled corpus and benchmark** (`src/assay/corpus/`, `corpus/`) — 20 labeled cases (18 synthetic,
+  2 local-model) scored offline by `assay corpus`, with precision and recall, explicit denominators,
+  the ids of any false `MALICIOUS` on clean cases, and `UNVERIFIED` coverage by cause. Single labeler
+  and synthetic-dominated: a regression measurement, not a population estimate. A separate 8-case
+  real-world control (`corpus/real/`) holds one local-model run of each of the maintainer's own
+  Plumb skills, all labeled clean; it is a private false-positive and coverage control, not a
+  benchmark.
+- **Static pre-filter** (`src/assay/triage/`, `assay triage`) — ranks a skill for a run from its
+  text; it emits `priority` and `signals` only, with no verdict, findings, trace or run. It is a
+  queue heuristic, not a detector, and the sandboxed run remains the verdict.
+- **Audit gate** ([`ETHICS.md`](ETHICS.md), [`docs/audit/`](docs/audit/)) — the rules and protocol
+  for third-party audits: evidence, three private runs, two-person review, a disclosure window,
+  publication limits and corrections. **No third-party audit has been run or published.** A private
+  own-skill runner dry run was executed on 2026-11-06; it is unreviewed and unpublished. The
+  maintainer is the only reviewer today; a public finding waits for a second reviewer and the
+  disclosure steps.
+
+The pattern lists are now measured on that corpus; run `assay corpus corpus/` for the current
+numbers and read `corpus/README.md` for the limits. The first real Anthropic-keyed run has not
+happened (the Phase 0 gate used a local model). Read `CLAUDE.md` before writing any code here; do not
+describe capability that is not in `git log`.
+
+## Usage
+
+```sh
+ANTHROPIC_API_KEY=... uv run assay check path/to/SKILL.md \
+  --model claude-sonnet-4-5 --input-price 3 --output-price 15 --max-cost 0.50
+```
+
+A local model needs no key at all. With Ollama running:
+
+```sh
+uv run assay check path/to/SKILL.md \
+  --provider openai-compatible --base-url http://127.0.0.1:11434/v1 \
+  --model qwen3-coder:30b --input-price 0 --output-price 0 --max-cost 0.01
+```
+
+`<skill>` may be the `SKILL.md` file or its directory. `--model`, `--input-price`,
+`--output-price` and `--max-cost` are required, with env fallbacks `ASSAY_MODEL`,
+`ASSAY_INPUT_PRICE`, `ASSAY_OUTPUT_PRICE` and `ASSAY_MAX_COST`; the OpenAI-compatible provider also
+reads `ASSAY_API_KEY`, but only for a non-local base URL (local URLs need no key, and a non-local URL
+must be https). Prices are USD per million tokens. Traces are written to
+`./.assay/traces/<sha256>.json` unless `--out` says otherwise, and `--json` prints one canonical
+line for CI. Exit `0` only on `CLEAN`; `1` on `FLAGGED`, `MALICIOUS` or `UNVERIFIED` (including a
+sandbox that cannot start, or a declared requirement the jail cannot satisfy); `2` on a usage or
+config error. The suite injects a scripted model and fake sandbox; a real Anthropic-keyed run is
+still the maintainer's.
+
+Claude Code, OpenClaw/ClawHub `SKILL.md` files, and Cursor project rules (`.mdc`) are accepted; the
+report's `format` and `requirements` fields say which and what it declares. An OpenClaw skill whose
+requirements cannot be met in the jail (`requires.env`, `requires.config`, a mismatched `os`, or a
+required binary absent from the jail PATH) is refused before any run with
+`UNVERIFIED/REQUIREMENTS_UNMET` and the exact missing item. A satisfiable skill runs normally. Most
+OpenClaw skills declare no file/network/tool scope, so the run stays
+`UNVERIFIED/NO_DECLARED_SCOPE` unless `metadata.assay` adds one.
+
+A Cursor rule's `globs` (or `alwaysApply: true`) becomes its file scope; the format declares no
+tools or network, so a run with no findings stays `UNVERIFIED/NO_DECLARED_SCOPE`, and a write outside
+the globs is `FLAGGED`. Pass the `.mdc` file itself, not its directory. `AGENTS.md`, `.cursorrules`,
+and Cursor user/team rules are not project-rule files and are out of scope.
+
+### Attesting a run
+
+A bundle binds one saved trace to the `SKILL.md` that produced it. Use a dedicated, unencrypted
+attestation key:
+
+```sh
+ssh-keygen -t ed25519 -N '' -C assay-attest -f ~/.ssh/assay-attest
+uv run assay bundle .assay/traces/<sha256>.json \
+  --skill path/to/SKILL.md --key ~/.ssh/assay-attest
+uv run assay verify .assay/traces/<sha256>.bundle.json \
+  --public-key ~/.ssh/assay-attest.pub
+```
+
+`bundle` writes `<trace-stem>.bundle.json` next to the trace unless `--out` says otherwise, and
+exits `0` only when it wrote the file. `verify` exits `0` only when the record is canonical, every
+hash agrees, and the signature verifies against the public key you supply; `1` on any failure, `2`
+on a usage error. Both accept `--json`. The bundle embeds the trace, so a verifier needs only the
+bundle and the public key — never the private key, the model, or the sandbox. A bundle embeds the
+trace's event excerpts, so read it before publishing. Pass the same `--strictness` you checked
+with (the default is `standard`); the bundle records the level it used. `verify` checks the
+signature and then replays the verdict: it re-parses the embedded `SKILL.md`, re-runs the shipped
+verdict layer at the recorded strictness, and refuses unless the result matches (`replay: verified`).
+A valid signature over a false verdict therefore fails with `replay-mismatch`. Replay proves the
+verdict follows from the recorded inputs, not that the run was captured honestly or that the skill
+is safe; the skill hash covers `SKILL.md` only, not the rest of the skill directory. `CLEAN` still
+means "matched declared scope in this run".
+
+### Measuring the verdict
+
+The repo ships a labeled corpus and an offline benchmark:
+
+```sh
+uv run assay corpus corpus/
+uv run assay corpus corpus/ --json
+```
+
+It verifies every case's skill and trace hash, re-runs the verdict layer, and prints precision and
+recall with explicit denominators, `UNVERIFIED` counts by cause, and the ids of any false
+`MALICIOUS` on clean cases. Exit `0` means the report was computed, not that the numbers passed a
+threshold. The corpus is small, single-labeled and synthetic-dominated; `corpus/README.md` states
+the limits, and the numbers are a regression signal, not a population estimate.
+
+### Triaging a collection
+
+`assay triage <skill>` ranks a skill from its text before you spend a run:
+
+```sh
+uv run assay triage path/to/SKILL.md
+uv run assay triage path/to/SKILL.md --json
+```
+
+It prints `priority` (`low`/`medium`/`high`) and the `signals` that produced it (credentials,
+network, shell, install, persistence, prompt injection, destructive, privilege, filesystem). It is a
+pre-filter: no verdict, no findings, no trace, no model and no sandbox. A high priority is not
+`MALICIOUS`, and a low priority is not safe; run `assay check` for an observed verdict.
+
+## What Assay is
+
+Point Assay at a skill — a Claude Code or OpenClaw/ClawHub `SKILL.md`, or a Cursor project rule
+today. MCP server verification is a separate, deferred capability: a server is a long-lived program,
+not a file. It runs the skill in an isolated sandbox against a real
+agent, captures every file access, network call, shell command, and injected instruction it
+produced, and diffs that against what the skill declares about itself. The verdict is backed by
+a captured record of the run, which can be signed into a bundle a third party verifies offline.
+
+## What Assay is not
+
+- Not a static pattern scanner as a verdict. Those exist (NVIDIA's SkillSpector) and are a cheap
+  pre-filter; `assay triage` is our queue heuristic, and it never decides. Only the sandboxed run
+  assigns a verdict.
+- Not an antivirus signature match. Assay observes novel behavior, not known hashes.
+- Not an MCP server verifier yet. A manifest says how to start a server, not what it does; MCP needs
+  a sandbox session and a client, so it is a separate, deferred capability (see
+  [`docs/planning/mcp-design/prd.md`](docs/planning/mcp-design/prd.md)).
+- Not a claim that a `CLEAN` skill is safe forever — only that this run's observed behavior
+  matched its declared scope.
+
+## The verdict
+
+| Verdict | Meaning |
+|---|---|
+| `CLEAN` | No findings, all three dimensions declared, and at least one captured behavior event |
+| `FLAGGED` | At least one finding, none of them `HIGH` |
+| `MALICIOUS` | At least one `HIGH` finding from a captured `OK`/`DENIED` action — never inferred from text alone |
+| `UNVERIFIED` | Could not decide; carries `NO_TRIGGER`, `NO_DECLARED_SCOPE`, `AGENT_FAILED`, `BUDGET_LIMIT` or `COST_CAPPED` |
+
+Strictness (`baseline`/`standard`/`strict`) decides only whether a run is `blocked`; it never
+changes the verdict. The severity floor for the four finding classes is fixed and cannot be
+lowered. An instruction-pattern match is a candidate capped at `REVIEW`: it can make a run
+`FLAGGED`, never `MALICIOUS`. The shell and instruction pattern lists are deliberately short. The A7
+corpus measures them on 20 labeled cases; the shell list was calibrated on a separate 8-case
+held-out set, adding four `HIGH` patterns (`dd` to a device, `pty.spawn`, `/dev/tcp/`, `socat ...
+EXEC:/bin/sh`) and taking strict malicious recall from 0/4 to 4/4 with 0 false `MALICIOUS` on four
+clean guards. The instruction list was calibrated on its own 8-case held-out set: five patterns were
+added (`ignore the above`, `disregard previous`, `forget your instructions`, `keep this between us`,
+`do not reveal this`) and two narrowed (`override your`, `system prompt`), taking detection from 0/4
+to 4/4 and clean review from 2/4 to 0/4 with 0 false `MALICIOUS`. Both sets are small and synthetic;
+those numbers are a regression/calibration signal, not a population estimate. Instruction findings
+remain capped at `REVIEW` — `FLAGGED` is a review, never an accusation — so strict malicious recall
+stays 0/4 by design.
+
+A static scan or model may flag a candidate; the sandboxed, observed run assigns the verdict.
+
+## Development
+
+macOS is required for the Seatbelt sandbox; the suite is offline (no model or network call).
+
+```sh
+uv sync --dev
+uv run pytest
+uv run assay --version
+```
+
+CI runs the same suite on `macos-latest`.
+
+## Docs
+
+- [`VISION.md`](VISION.md) — the thesis, the moat, non-goals.
+- [`CLAUDE.md`](CLAUDE.md) — guardrails and the verdict contract.
+- [`ETHICS.md`](ETHICS.md) — the audit ethics, disclosure and correction policy.
+- [`docs/audit/PROTOCOL.md`](docs/audit/PROTOCOL.md) — the audit protocol and checklist.
+- [`docs/ROADMAP.md`](docs/ROADMAP.md) — phased plan and risk register.
+- [`docs/technical/CAPABILITY_ROADMAP.md`](docs/technical/CAPABILITY_ROADMAP.md) — A1..A10 capabilities in build order.
+- [`docs/technical/ARCHITECTURE.md`](docs/technical/ARCHITECTURE.md) — the design.
+
+## Lineage
+
+Assay is one of three siblings scaffolded together on 2026-10-22 (with [Tenon](../tenon) and
+[Pry](../pry)), out of a market-demand research pass, sharing house DNA with
+[Belay](../belay), [Plumb](../plumb), and [Whetstone](../whetstone). Standalone by design — no
+code dependency on sibling projects yet.