agent-baseline 0.1.0__tar.gz

agent_baseline-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agent-baseline
+Version: 0.1.0
+Summary: Evidence-backed project guidance and verification for coding agents
+Author: Lemuel Boyce
+Project-URL: Homepage, https://github.com/rhymiz/agent-baseline
+Project-URL: Repository, https://github.com/rhymiz/agent-baseline
+Project-URL: Issues, https://github.com/rhymiz/agent-baseline/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Agent Baseline
+
+A local tool for maintaining evidence-backed project instructions. Version 0.1.0 combines a reusable authoring skill, a standard-library Python CLI, and a Codex plugin manifest. It needs no model API key or service. The skill runs inside the coding agent you already use.
+
+## Run with uvx or install once
+
+Requires Python 3.11+; Git for inventory; macOS or Linux for running checks. Run the CLI from PyPI without a permanent installation:
+
+```sh
+uvx agent-baseline --help
+uvx agent-baseline inspect .
+uvx agent-baseline check .
+uvx agent-baseline verify .
+```
+
+For a persistent installation:
+
+```sh
+uv tool install agent-baseline
+```
+
+Pin a version for reproducible automation, for example `uvx agent-baseline@0.1.0 check .`. These commands operate on the current project; `check` and `verify` require its configured baseline. Verification runs in the caller's environment, so declared commands must select the project's runtime explicitly where needed (for example, `uv run pytest`).
+
+To develop the tool or obtain the agent skill, clone the public repository:
+
+```sh
+gh repo clone rhymiz/agent-baseline
+cd agent-baseline
+uv tool install .
+```
+
+If you already have a checkout, run `uv tool install .` from its root. The GitHub repository is the maintained source; project-specific guidance and baseline records belong in each project repository.
+
+Or run directly without installation:
+
+```sh
+python3 skills/baseline-project/scripts/baseline.py inspect /absolute/project/path
+```
+
+The installed command works from any project:
+
+```sh
+agent-baseline inspect .
+agent-baseline check .
+agent-baseline verify .
+```
+
+The CLI installation does not register a skill or plugin with an agent.
+
+This package is also a configured example project: from its root, run `agent-baseline check .` and `agent-baseline verify .`. Its declared check executes the integration suite against the tool itself. Inspect its `AGENTS.md` and `.agent-baseline.json` to see a populated record.
+
+## Set up a project with an agent
+
+Give your agent the absolute path to `skills/baseline-project/SKILL.md` and this request:
+
+> Use this skill to set up an agent baseline for the current project. Ground every rule in inspected code, contracts, or commands. Preserve existing instructions and unrelated edits. Create the project evidence record, run the relevant development checks, and report anything unverified.
+
+The skill writes or improves a small root instruction file, relevant task routing and domain guidance, and `.agent-baseline.json`. It records the reviewed hashes in `.agent-baseline.lock.json`. These project files belong in version control. The helper does not generate guidance from filenames; the agent inspects the actual evidence first.
+
+For global discovery, copy the entire `skills/baseline-project` folder into a user skill directory supported by your host, preserving scripts and references. Codex and Claude Code also support linked skill folders. Alternatively, install the supplied Codex plugin through a configured local marketplace. The plugin is packaged here but is not registered or installed globally.
+
+| Host | User skill destination |
+| --- | --- |
+| Codex | `~/.agents/skills/baseline-project/` |
+| Claude Code | `~/.claude/skills/baseline-project/` |
+
+Preserve an existing destination if one is already present; review and update it rather than overwriting blindly. After the host discovers the skill, invoke it by name: `$baseline-project` in Codex CLI/IDE or `/baseline-project` in Claude Code. In other surfaces, select it through the skill picker. Other agents can read the same `SKILL.md` by absolute path and use the CLI without the Codex manifest.
+
+Codex skill authoring/discovery: [official docs](https://learn.chatgpt.com/docs/build-skills). Claude Code skill loading: [official docs](https://code.claude.com/docs/en/skills). Codex local plugin packaging: [official docs](https://developers.openai.com/plugins/build/plugins).
+
+## Ongoing use
+
+Ask the agent to audit guidance for a read-only report, or refresh guidance after the tool reports drift. Examples:
+
+> Use baseline-project to audit this project's agent guidance. Report concrete contradictions, weak triggers, stale references, and verification gaps.
+
+> Use baseline-project to review the changed evidence, update only affected guidance, and verify the refreshed baseline.
+
+The skill offers a model-evaluation protocol when requested. Automated model trials, aggregate scoring, and model-specific routing are not implemented in this release.
+
+## CLI behavior
+
+| Command | Behavior |
+| --- | --- |
+| `inspect [project]` | Finds candidate instructions, manifests, CI files, and contracts. Reads filenames; does not execute project commands. |
+| `record [project]` | Snapshots the config, guidance, and supporting files after review. Does not certify quality. |
+| `check [project]` | Detects drift in the monitored files. No project commands execute. |
+| `verify [project]` | Runs every explicitly declared project check and reports pass/failure/timeout/blocked status. |
+
+All commands emit JSON. Exit codes are 0 for operation success, 1 for drift or failed verification, and 2 for invalid input/configuration or prerequisite errors. Run `--help` for invocation syntax. See [the record specification](https://github.com/rhymiz/agent-baseline/blob/main/skills/baseline-project/references/project-record.md) for configuration and limitations.
+
+Use `record` only after semantic review. Never run it automatically in a CI validation job before `check`. A hash change means guidance needs review, not necessarily rewriting. A matching hash means files are unchanged, not that their claims are correct.
+
+In CI, use a pinned copy/version of the CLI, run `check`, then the project's required verification. Independently review changes to verification policy. The tool tracks selected evidence files, not the full patch, and does not establish architecture quality or model parity.
+
+## Development verification
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+Tests use temporary project fixtures and real child commands. They cover evidence drift, missing and malformed inputs, path escape rejection, command failures/timeouts, working directories, and mutation during verification.
+
+## Publishing
+
+Publishing a GitHub release with a tag matching `v<project.version>` triggers `.github/workflows/publish.yml`. The workflow verifies the evidence and tests, builds and checks distributions, tests the wheel outside the checkout, and publishes through the `pypi` environment using PyPI Trusted Publishing. No PyPI API token is stored in the repository.
+
+The PyPI publisher is scoped to project `agent-baseline`, GitHub owner `rhymiz`, repository `agent-baseline`, workflow `publish.yml`, and environment `pypi`. PyPI distributions contain the CLI; the authoring skill remains available in the GitHub repository and Codex plugin.

agent_baseline-0.1.0/README.md

@@ -0,0 +1,108 @@
+# Agent Baseline
+
+A local tool for maintaining evidence-backed project instructions. Version 0.1.0 combines a reusable authoring skill, a standard-library Python CLI, and a Codex plugin manifest. It needs no model API key or service. The skill runs inside the coding agent you already use.
+
+## Run with uvx or install once
+
+Requires Python 3.11+; Git for inventory; macOS or Linux for running checks. Run the CLI from PyPI without a permanent installation:
+
+```sh
+uvx agent-baseline --help
+uvx agent-baseline inspect .
+uvx agent-baseline check .
+uvx agent-baseline verify .
+```
+
+For a persistent installation:
+
+```sh
+uv tool install agent-baseline
+```
+
+Pin a version for reproducible automation, for example `uvx agent-baseline@0.1.0 check .`. These commands operate on the current project; `check` and `verify` require its configured baseline. Verification runs in the caller's environment, so declared commands must select the project's runtime explicitly where needed (for example, `uv run pytest`).
+
+To develop the tool or obtain the agent skill, clone the public repository:
+
+```sh
+gh repo clone rhymiz/agent-baseline
+cd agent-baseline
+uv tool install .
+```
+
+If you already have a checkout, run `uv tool install .` from its root. The GitHub repository is the maintained source; project-specific guidance and baseline records belong in each project repository.
+
+Or run directly without installation:
+
+```sh
+python3 skills/baseline-project/scripts/baseline.py inspect /absolute/project/path
+```
+
+The installed command works from any project:
+
+```sh
+agent-baseline inspect .
+agent-baseline check .
+agent-baseline verify .
+```
+
+The CLI installation does not register a skill or plugin with an agent.
+
+This package is also a configured example project: from its root, run `agent-baseline check .` and `agent-baseline verify .`. Its declared check executes the integration suite against the tool itself. Inspect its `AGENTS.md` and `.agent-baseline.json` to see a populated record.
+
+## Set up a project with an agent
+
+Give your agent the absolute path to `skills/baseline-project/SKILL.md` and this request:
+
+> Use this skill to set up an agent baseline for the current project. Ground every rule in inspected code, contracts, or commands. Preserve existing instructions and unrelated edits. Create the project evidence record, run the relevant development checks, and report anything unverified.
+
+The skill writes or improves a small root instruction file, relevant task routing and domain guidance, and `.agent-baseline.json`. It records the reviewed hashes in `.agent-baseline.lock.json`. These project files belong in version control. The helper does not generate guidance from filenames; the agent inspects the actual evidence first.
+
+For global discovery, copy the entire `skills/baseline-project` folder into a user skill directory supported by your host, preserving scripts and references. Codex and Claude Code also support linked skill folders. Alternatively, install the supplied Codex plugin through a configured local marketplace. The plugin is packaged here but is not registered or installed globally.
+
+| Host | User skill destination |
+| --- | --- |
+| Codex | `~/.agents/skills/baseline-project/` |
+| Claude Code | `~/.claude/skills/baseline-project/` |
+
+Preserve an existing destination if one is already present; review and update it rather than overwriting blindly. After the host discovers the skill, invoke it by name: `$baseline-project` in Codex CLI/IDE or `/baseline-project` in Claude Code. In other surfaces, select it through the skill picker. Other agents can read the same `SKILL.md` by absolute path and use the CLI without the Codex manifest.
+
+Codex skill authoring/discovery: [official docs](https://learn.chatgpt.com/docs/build-skills). Claude Code skill loading: [official docs](https://code.claude.com/docs/en/skills). Codex local plugin packaging: [official docs](https://developers.openai.com/plugins/build/plugins).
+
+## Ongoing use
+
+Ask the agent to audit guidance for a read-only report, or refresh guidance after the tool reports drift. Examples:
+
+> Use baseline-project to audit this project's agent guidance. Report concrete contradictions, weak triggers, stale references, and verification gaps.
+
+> Use baseline-project to review the changed evidence, update only affected guidance, and verify the refreshed baseline.
+
+The skill offers a model-evaluation protocol when requested. Automated model trials, aggregate scoring, and model-specific routing are not implemented in this release.
+
+## CLI behavior
+
+| Command | Behavior |
+| --- | --- |
+| `inspect [project]` | Finds candidate instructions, manifests, CI files, and contracts. Reads filenames; does not execute project commands. |
+| `record [project]` | Snapshots the config, guidance, and supporting files after review. Does not certify quality. |
+| `check [project]` | Detects drift in the monitored files. No project commands execute. |
+| `verify [project]` | Runs every explicitly declared project check and reports pass/failure/timeout/blocked status. |
+
+All commands emit JSON. Exit codes are 0 for operation success, 1 for drift or failed verification, and 2 for invalid input/configuration or prerequisite errors. Run `--help` for invocation syntax. See [the record specification](https://github.com/rhymiz/agent-baseline/blob/main/skills/baseline-project/references/project-record.md) for configuration and limitations.
+
+Use `record` only after semantic review. Never run it automatically in a CI validation job before `check`. A hash change means guidance needs review, not necessarily rewriting. A matching hash means files are unchanged, not that their claims are correct.
+
+In CI, use a pinned copy/version of the CLI, run `check`, then the project's required verification. Independently review changes to verification policy. The tool tracks selected evidence files, not the full patch, and does not establish architecture quality or model parity.
+
+## Development verification
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+Tests use temporary project fixtures and real child commands. They cover evidence drift, missing and malformed inputs, path escape rejection, command failures/timeouts, working directories, and mutation during verification.
+
+## Publishing
+
+Publishing a GitHub release with a tag matching `v<project.version>` triggers `.github/workflows/publish.yml`. The workflow verifies the evidence and tests, builds and checks distributions, tests the wheel outside the checkout, and publishes through the `pypi` environment using PyPI Trusted Publishing. No PyPI API token is stored in the repository.
+
+The PyPI publisher is scoped to project `agent-baseline`, GitHub owner `rhymiz`, repository `agent-baseline`, workflow `publish.yml`, and environment `pypi`. PyPI distributions contain the CLI; the authoring skill remains available in the GitHub repository and Codex plugin.

agent_baseline-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-baseline"
+version = "0.1.0"
+description = "Evidence-backed project guidance and verification for coding agents"
+readme = "README.md"
+authors = [{name = "Lemuel Boyce"}]
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://github.com/rhymiz/agent-baseline"
+Repository = "https://github.com/rhymiz/agent-baseline"
+Issues = "https://github.com/rhymiz/agent-baseline/issues"
+
+[project.scripts]
+agent-baseline = "baseline:main"
+
+[tool.setuptools]
+py-modules = ["baseline"]
+package-dir = {"" = "skills/baseline-project/scripts"}

agent_baseline-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_baseline-0.1.0/skills/baseline-project/scripts/agent_baseline.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agent-baseline
+Version: 0.1.0
+Summary: Evidence-backed project guidance and verification for coding agents
+Author: Lemuel Boyce
+Project-URL: Homepage, https://github.com/rhymiz/agent-baseline
+Project-URL: Repository, https://github.com/rhymiz/agent-baseline
+Project-URL: Issues, https://github.com/rhymiz/agent-baseline/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Agent Baseline
+
+A local tool for maintaining evidence-backed project instructions. Version 0.1.0 combines a reusable authoring skill, a standard-library Python CLI, and a Codex plugin manifest. It needs no model API key or service. The skill runs inside the coding agent you already use.
+
+## Run with uvx or install once
+
+Requires Python 3.11+; Git for inventory; macOS or Linux for running checks. Run the CLI from PyPI without a permanent installation:
+
+```sh
+uvx agent-baseline --help
+uvx agent-baseline inspect .
+uvx agent-baseline check .
+uvx agent-baseline verify .
+```
+
+For a persistent installation:
+
+```sh
+uv tool install agent-baseline
+```
+
+Pin a version for reproducible automation, for example `uvx agent-baseline@0.1.0 check .`. These commands operate on the current project; `check` and `verify` require its configured baseline. Verification runs in the caller's environment, so declared commands must select the project's runtime explicitly where needed (for example, `uv run pytest`).
+
+To develop the tool or obtain the agent skill, clone the public repository:
+
+```sh
+gh repo clone rhymiz/agent-baseline
+cd agent-baseline
+uv tool install .
+```
+
+If you already have a checkout, run `uv tool install .` from its root. The GitHub repository is the maintained source; project-specific guidance and baseline records belong in each project repository.
+
+Or run directly without installation:
+
+```sh
+python3 skills/baseline-project/scripts/baseline.py inspect /absolute/project/path
+```
+
+The installed command works from any project:
+
+```sh
+agent-baseline inspect .
+agent-baseline check .
+agent-baseline verify .
+```
+
+The CLI installation does not register a skill or plugin with an agent.
+
+This package is also a configured example project: from its root, run `agent-baseline check .` and `agent-baseline verify .`. Its declared check executes the integration suite against the tool itself. Inspect its `AGENTS.md` and `.agent-baseline.json` to see a populated record.
+
+## Set up a project with an agent
+
+Give your agent the absolute path to `skills/baseline-project/SKILL.md` and this request:
+
+> Use this skill to set up an agent baseline for the current project. Ground every rule in inspected code, contracts, or commands. Preserve existing instructions and unrelated edits. Create the project evidence record, run the relevant development checks, and report anything unverified.
+
+The skill writes or improves a small root instruction file, relevant task routing and domain guidance, and `.agent-baseline.json`. It records the reviewed hashes in `.agent-baseline.lock.json`. These project files belong in version control. The helper does not generate guidance from filenames; the agent inspects the actual evidence first.
+
+For global discovery, copy the entire `skills/baseline-project` folder into a user skill directory supported by your host, preserving scripts and references. Codex and Claude Code also support linked skill folders. Alternatively, install the supplied Codex plugin through a configured local marketplace. The plugin is packaged here but is not registered or installed globally.
+
+| Host | User skill destination |
+| --- | --- |
+| Codex | `~/.agents/skills/baseline-project/` |
+| Claude Code | `~/.claude/skills/baseline-project/` |
+
+Preserve an existing destination if one is already present; review and update it rather than overwriting blindly. After the host discovers the skill, invoke it by name: `$baseline-project` in Codex CLI/IDE or `/baseline-project` in Claude Code. In other surfaces, select it through the skill picker. Other agents can read the same `SKILL.md` by absolute path and use the CLI without the Codex manifest.
+
+Codex skill authoring/discovery: [official docs](https://learn.chatgpt.com/docs/build-skills). Claude Code skill loading: [official docs](https://code.claude.com/docs/en/skills). Codex local plugin packaging: [official docs](https://developers.openai.com/plugins/build/plugins).
+
+## Ongoing use
+
+Ask the agent to audit guidance for a read-only report, or refresh guidance after the tool reports drift. Examples:
+
+> Use baseline-project to audit this project's agent guidance. Report concrete contradictions, weak triggers, stale references, and verification gaps.
+
+> Use baseline-project to review the changed evidence, update only affected guidance, and verify the refreshed baseline.
+
+The skill offers a model-evaluation protocol when requested. Automated model trials, aggregate scoring, and model-specific routing are not implemented in this release.
+
+## CLI behavior
+
+| Command | Behavior |
+| --- | --- |
+| `inspect [project]` | Finds candidate instructions, manifests, CI files, and contracts. Reads filenames; does not execute project commands. |
+| `record [project]` | Snapshots the config, guidance, and supporting files after review. Does not certify quality. |
+| `check [project]` | Detects drift in the monitored files. No project commands execute. |
+| `verify [project]` | Runs every explicitly declared project check and reports pass/failure/timeout/blocked status. |
+
+All commands emit JSON. Exit codes are 0 for operation success, 1 for drift or failed verification, and 2 for invalid input/configuration or prerequisite errors. Run `--help` for invocation syntax. See [the record specification](https://github.com/rhymiz/agent-baseline/blob/main/skills/baseline-project/references/project-record.md) for configuration and limitations.
+
+Use `record` only after semantic review. Never run it automatically in a CI validation job before `check`. A hash change means guidance needs review, not necessarily rewriting. A matching hash means files are unchanged, not that their claims are correct.
+
+In CI, use a pinned copy/version of the CLI, run `check`, then the project's required verification. Independently review changes to verification policy. The tool tracks selected evidence files, not the full patch, and does not establish architecture quality or model parity.
+
+## Development verification
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+Tests use temporary project fixtures and real child commands. They cover evidence drift, missing and malformed inputs, path escape rejection, command failures/timeouts, working directories, and mutation during verification.
+
+## Publishing
+
+Publishing a GitHub release with a tag matching `v<project.version>` triggers `.github/workflows/publish.yml`. The workflow verifies the evidence and tests, builds and checks distributions, tests the wheel outside the checkout, and publishes through the `pypi` environment using PyPI Trusted Publishing. No PyPI API token is stored in the repository.
+
+The PyPI publisher is scoped to project `agent-baseline`, GitHub owner `rhymiz`, repository `agent-baseline`, workflow `publish.yml`, and environment `pypi`. PyPI distributions contain the CLI; the authoring skill remains available in the GitHub repository and Codex plugin.

agent_baseline-0.1.0/skills/baseline-project/scripts/agent_baseline.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+skills/baseline-project/scripts/baseline.py
+skills/baseline-project/scripts/agent_baseline.egg-info/PKG-INFO
+skills/baseline-project/scripts/agent_baseline.egg-info/SOURCES.txt
+skills/baseline-project/scripts/agent_baseline.egg-info/dependency_links.txt
+skills/baseline-project/scripts/agent_baseline.egg-info/entry_points.txt
+skills/baseline-project/scripts/agent_baseline.egg-info/top_level.txt
+tests/test_baseline.py

agent_baseline-0.1.0/skills/baseline-project/scripts/agent_baseline.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_baseline-0.1.0/skills/baseline-project/scripts/agent_baseline.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-baseline = baseline:main

agent_baseline-0.1.0/skills/baseline-project/scripts/agent_baseline.egg-info/top_level.txt

@@ -0,0 +1 @@
+baseline

agent_baseline-0.1.0/skills/baseline-project/scripts/baseline.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Inspect project guidance, track its evidence, and execute declared checks."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import signal
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG = ".agent-baseline.json"
+LOCK = ".agent-baseline.lock.json"
+EXCLUDED = {".git", "node_modules", ".venv", "venv", "__pycache__", ".next", "dist", "build", "vendor"}
+MANIFESTS = {"package.json", "pyproject.toml", "Cargo.toml", "go.mod", "Makefile", "justfile", "Gemfile", "pom.xml", "build.gradle", "build.gradle.kts"}
+INSTRUCTIONS = {"AGENTS.md", "AGENTS.override.md", "CLAUDE.md", "GEMINI.md", "SKILL.md", "copilot-instructions.md"}
+
+
+class InvalidBaseline(ValueError):
+    """A project record is missing, unsafe to resolve, or malformed."""
+
+
+@dataclass(frozen=True)
+class Artifact:
+    path: str
+    sources: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    argv: tuple[str, ...]
+    cwd: str
+    timeout_seconds: int
+
+
+@dataclass(frozen=True)
+class Baseline:
+    artifacts: tuple[Artifact, ...]
+    checks: tuple[Check, ...]
+
+
+def fields(value: object, expected: set[str], label: str) -> dict[str, object]:
+    if not isinstance(value, dict) or set(value) != expected:
+        raise InvalidBaseline(f"{label} must contain exactly: {', '.join(sorted(expected))}")
+    result: dict[str, object] = {}
+    for key, item in value.items():
+        if not isinstance(key, str):
+            raise InvalidBaseline(f"{label} keys must be strings")
+        result[key] = item
+    return result
+
+
+def string(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value.strip() or "\x00" in value:
+        raise InvalidBaseline(f"{label} must be a nonempty string without NUL characters")
+    return value
+
+
+def items(value: object, label: str) -> list[object]:
+    if not isinstance(value, list) or not value:
+        raise InvalidBaseline(f"{label} must be a nonempty array")
+    return list(value)
+
+
+def version(value: object) -> None:
+    if type(value) is not int or value != 1:
+        raise InvalidBaseline("schema_version must be the integer 1")
+
+
+def within(root: Path, relative: str) -> Path:
+    path = Path(relative)
+    if path.is_absolute() or ".." in path.parts:
+        raise InvalidBaseline(f"Use a project-relative path without '..': {relative}")
+    resolved = (root / path).resolve()
+    if not resolved.is_relative_to(root):
+        raise InvalidBaseline(f"Path or symlink leaves the project: {relative}")
+    return resolved
+
+
+def read_json(path: Path) -> object:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_baseline(root: Path) -> Baseline:
+    config = fields(read_json(within(root, CONFIG)), {"schema_version", "artifacts", "checks"}, CONFIG)
+    version(config["schema_version"])
+    artifacts: list[Artifact] = []
+    for raw in items(config["artifacts"], "artifacts"):
+        entry = fields(raw, {"path", "sources"}, "artifact")
+        path = string(entry["path"], "artifact.path")
+        sources = tuple(string(source, "source") for source in items(entry["sources"], "sources"))
+        for candidate in (path, *sources):
+            if candidate in {CONFIG, LOCK} or not within(root, candidate).is_file():
+                raise InvalidBaseline(f"Artifact/source must be an existing project file other than the baseline records: {candidate}")
+        if len(set(sources)) != len(sources):
+            raise InvalidBaseline(f"Duplicate sources for {path}")
+        if within(root, path) in {within(root, source) for source in sources}:
+            raise InvalidBaseline(f"An artifact cannot be its own evidence: {path}")
+        artifacts.append(Artifact(path, sources))
+    if len({within(root, artifact.path) for artifact in artifacts}) != len(artifacts):
+        raise InvalidBaseline("Artifact paths must be unique")
+    checks: list[Check] = []
+    for raw in items(config["checks"], "checks"):
+        entry = fields(raw, {"name", "argv", "cwd", "timeout_seconds"}, "check")
+        timeout = entry["timeout_seconds"]
+        if type(timeout) is not int or not 1 <= timeout <= 86400:
+            raise InvalidBaseline("timeout_seconds must be an integer between 1 and 86400")
+        cwd = string(entry["cwd"], "check.cwd")
+        if not within(root, cwd).is_dir():
+            raise InvalidBaseline(f"Check working directory does not exist: {cwd}")
+        argv = tuple(string(arg, "argv item") for arg in items(entry["argv"], "argv"))
+        checks.append(Check(string(entry["name"], "check.name"), argv, cwd, timeout))
+    if len({check.name for check in checks}) != len(checks):
+        raise InvalidBaseline("Check names must be unique")
+    return Baseline(tuple(artifacts), tuple(checks))
+
+
+def digest(path: Path) -> str:
+    with path.open("rb") as handle:
+        return hashlib.file_digest(handle, "sha256").hexdigest()
+
+
+def snapshot(root: Path, baseline: Baseline) -> dict[str, str]:
+    paths = {CONFIG}
+    for artifact in baseline.artifacts:
+        paths.add(artifact.path)
+        paths.update(artifact.sources)
+    return {path: digest(within(root, path)) for path in sorted(paths)}
+
+
+def save_snapshot(root: Path, baseline: Baseline) -> None:
+    destination = root / LOCK
+    if destination.is_symlink():
+        raise InvalidBaseline("The lock record must not be a symlink")
+    content = json.dumps({"schema_version": 1, "files": snapshot(root, baseline)}, indent=2) + "\n"
+    with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=root, delete=False) as handle:
+        temporary = Path(handle.name)
+        handle.write(content)
+    try:
+        temporary.replace(destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def drift(root: Path, current: dict[str, str]) -> list[str]:
+    record = fields(read_json(within(root, LOCK)), {"schema_version", "files"}, LOCK)
+    version(record["schema_version"])
+    raw = record["files"]
+    if not isinstance(raw, dict):
+        raise InvalidBaseline("lock.files must be an object")
+    recorded: dict[str, str] = {}
+    for key, value in raw.items():
+        name = string(key, "lock path")
+        fingerprint = string(value, "lock hash")
+        if len(fingerprint) != 64 or any(c not in "0123456789abcdef" for c in fingerprint):
+            raise InvalidBaseline(f"Invalid SHA-256 for {name}")
+        recorded[name] = fingerprint
+    changed: list[str] = []
+    for name in sorted(current.keys() | recorded.keys()):
+        if name not in current or name not in recorded or current[name] != recorded[name]:
+            changed.append(name)
+    return changed
+
+
+def inventory(root: Path) -> dict[str, object]:
+    git = subprocess.run(["git", "-C", str(root), "ls-files", "--cached", "--others", "--exclude-standard", "-z"], capture_output=True, check=False)
+    if git.returncode == 0:
+        paths = sorted(set(git.stdout.decode("utf-8").split("\x00")) - {""})
+        method = "git tracked and non-ignored untracked files"
+    else:
+        paths = []
+        for directory, subdirs, files in os.walk(root, followlinks=False):
+            subdirs[:] = sorted(name for name in subdirs if name not in EXCLUDED)
+            paths.extend((Path(directory) / name).relative_to(root).as_posix() for name in files)
+        paths.sort()
+        method = "filesystem walk with common dependency/build directories excluded; ignore files not interpreted"
+    groups: dict[str, list[str]] = {"manifests": [], "instructions": [], "ci": [], "contracts": []}
+    for path in paths:
+        parts = Path(path).parts
+        if any(part in EXCLUDED for part in parts):
+            continue
+        name = Path(path).name
+        if name in MANIFESTS:
+            groups["manifests"].append(path)
+        if name in INSTRUCTIONS or path.startswith(".cursor/rules/"):
+            groups["instructions"].append(path)
+        if path.startswith(".github/workflows/") or name in {".gitlab-ci.yml", "Jenkinsfile"}:
+            groups["ci"].append(path)
+        if name.endswith((".md", ".json", ".yaml", ".yml")) and any(part in {"contracts", "schemas", "openspec"} for part in parts):
+            groups["contracts"].append(path)
+    return {"status": "inventory", "root": str(root), "method": method, "file_count": len(paths), "candidates": {name: entries[:200] for name, entries in groups.items()}, "truncated_groups": [name for name, entries in groups.items() if len(entries) > 200], "note": "Paths are candidates, not verified sources of authority. No project commands were executed."}
+
+
+def run_check(root: Path, check: Check) -> dict[str, object]:
+    with tempfile.TemporaryFile() as output:
+        try:
+            process = subprocess.Popen(check.argv, cwd=within(root, check.cwd), stdin=subprocess.DEVNULL, stdout=output, stderr=subprocess.STDOUT, start_new_session=True)
+        except OSError as error:
+            return {"name": check.name, "status": "blocked", "error": str(error)}
+        try:
+            code = process.wait(timeout=check.timeout_seconds)
+            status = "passed" if code == 0 else "failed"
+        except subprocess.TimeoutExpired:
+            os.killpg(process.pid, signal.SIGKILL)
+            process.wait()
+            code = process.returncode
+            status = "timed_out"
+        output.seek(0, os.SEEK_END)
+        length = output.tell()
+        output.seek(max(0, length - 8000))
+        tail = output.read().decode("utf-8", errors="replace")
+    return {"name": check.name, "argv": list(check.argv), "cwd": check.cwd, "status": status, "exit_code": code, "output_tail": tail, "output_truncated": length > 8000}
+
+
+def execute(command: str, root: Path) -> tuple[dict[str, object], int]:
+    if not root.is_dir():
+        raise InvalidBaseline(f"Project directory does not exist: {root}")
+    if command == "inspect":
+        return inventory(root), 0
+    baseline = load_baseline(root)
+    if command == "record":
+        save_snapshot(root, baseline)
+        return {"status": "recorded", "note": "Evidence snapshot recorded. This does not run checks or certify the guidance."}, 0
+    before = snapshot(root, baseline)
+    changed = drift(root, before)
+    if changed:
+        return {"status": "needs_review", "changed": changed, "note": "Review the dependent guidance before recording a new baseline."}, 1
+    if command == "check":
+        return {"status": "current", "artifacts": len(baseline.artifacts), "checks_declared": len(baseline.checks), "note": "Monitored files match their recorded hashes. Verification commands were not run; semantic correctness is not established."}, 0
+    if os.name != "posix":
+        raise InvalidBaseline("verify currently requires macOS or Linux for process-group timeout handling")
+    results = [run_check(root, check) for check in baseline.checks]
+    after = snapshot(root, load_baseline(root))
+    passed = before == after and all(result["status"] == "passed" for result in results)
+    return {"status": "passed" if passed else "not_passed", "checks": results, "monitored_inputs_changed": before != after, "evidence_sha256": hashlib.sha256(json.dumps(before, sort_keys=True).encode()).hexdigest(), "scope": "Declared checks and monitored files only; not a full-worktree attestation or proof of architectural quality."}, 0 if passed else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("command", choices=["inspect", "record", "check", "verify"], help="inspect: read candidates; record: snapshot reviewed guidance; check: detect drift; verify: execute all declared project commands")
+    parser.add_argument("project", nargs="?", default=".")
+    args = parser.parse_args()
+    try:
+        report, code = execute(args.command, Path(args.project).expanduser().resolve())
+    except (InvalidBaseline, OSError, ValueError) as error:
+        report, code = {"status": "invalid", "error": str(error)}, 2
+    print(json.dumps(report, indent=2))
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_baseline-0.1.0/tests/test_baseline.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+CLI = Path(__file__).resolve().parents[1] / "skills/baseline-project/scripts/baseline.py"
+
+
+class BaselineTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temporary.cleanup)
+        self.root = Path(self.temporary.name)
+        (self.root / "AGENTS.md").write_text("Run the declared checks.\n")
+        (self.root / "contract.txt").write_text("Input must be validated.\n")
+        self.config: dict[str, object] = {
+            "schema_version": 1,
+            "artifacts": [{"path": "AGENTS.md", "sources": ["contract.txt"]}],
+            "checks": [self.command("ok", "print('verified')")],
+        }
+        self.write_config()
+
+    def command(self, name: str, program: str, cwd: str = ".", timeout: int = 5) -> dict[str, object]:
+        return {"name": name, "argv": [sys.executable, "-c", program], "cwd": cwd, "timeout_seconds": timeout}
+
+    def write_config(self) -> None:
+        (self.root / ".agent-baseline.json").write_text(json.dumps(self.config))
+
+    def invoke(self, command: str, expected_code: int = 0) -> dict[str, object]:
+        result = subprocess.run([sys.executable, str(CLI), command, str(self.root)], capture_output=True, text=True, timeout=15)
+        self.assertEqual(result.returncode, expected_code, result.stdout + result.stderr)
+        payload: object = json.loads(result.stdout)
+        if not isinstance(payload, dict):
+            self.fail("Expected a JSON report")
+        report: dict[str, object] = {}
+        for key, value in payload.items():
+            if not isinstance(key, str):
+                self.fail("Expected string keys")
+            report[key] = value
+        return report
+
+    def test_record_current_and_verify(self) -> None:
+        self.assertEqual(self.invoke("record")["status"], "recorded")
+        self.assertEqual(self.invoke("check")["status"], "current")
+        report = self.invoke("verify")
+        self.assertEqual(report["status"], "passed")
+        self.assertIn("verified", str(report["checks"]))
+
+    def test_changed_source_requires_review_and_does_not_run_checks(self) -> None:
+        self.config["checks"] = [self.command("sentinel", "from pathlib import Path; Path('ran').touch()")]
+        self.write_config()
+        self.invoke("record")
+        (self.root / "contract.txt").write_text("Changed contract\n")
+        report = self.invoke("verify", 1)
+        self.assertEqual(report["changed"], ["contract.txt"])
+        self.assertFalse((self.root / "ran").exists())
+
+    def test_artifact_and_command_drift(self) -> None:
+        self.invoke("record")
+        (self.root / "AGENTS.md").write_text("Different guidance\n")
+        self.assertEqual(self.invoke("check", 1)["changed"], ["AGENTS.md"])
+        self.invoke("record")
+        self.config["checks"] = [self.command("new-check", "print('new')")]
+        self.write_config()
+        self.assertEqual(self.invoke("check", 1)["changed"], [".agent-baseline.json"])
+
+    def test_missing_lock_and_missing_evidence_are_not_success(self) -> None:
+        self.assertEqual(self.invoke("check", 2)["status"], "invalid")
+        self.invoke("record")
+        (self.root / "contract.txt").unlink()
+        self.assertEqual(self.invoke("check", 2)["status"], "invalid")
+
+    def test_invalid_schema_unknown_keys_and_empty_checks(self) -> None:
+        for replacement in (True, 2, "1"):
+            with self.subTest(replacement=replacement):
+                self.config["schema_version"] = replacement
+                self.write_config()
+                self.invoke("record", 2)
+        self.config["schema_version"] = 1
+        self.config["unrecognized"] = "typo"
+        self.write_config()
+        self.invoke("record", 2)
+        del self.config["unrecognized"]
+        self.config["checks"] = []
+        self.write_config()
+        self.invoke("record", 2)
+
+    def test_outside_source_symlink_is_rejected(self) -> None:
+        with tempfile.TemporaryDirectory() as external:
+            target = Path(external) / "source"
+            target.write_text("external")
+            (self.root / "outside").symlink_to(target)
+            self.config["artifacts"] = [{"path": "AGENTS.md", "sources": ["outside"]}]
+            self.write_config()
+            self.assertIn("leaves the project", str(self.invoke("record", 2)["error"]))
+
+    def test_path_traversal_is_rejected(self) -> None:
+        self.config["artifacts"] = [{"path": "AGENTS.md", "sources": ["../outside"]}]
+        self.write_config()
+        self.invoke("record", 2)
+
+    def test_failure_blocked_and_timeout_have_distinct_results(self) -> None:
+        missing = {"name": "missing", "argv": ["/no/such/baseline-test-executable"], "cwd": ".", "timeout_seconds": 1}
+        self.config["checks"] = [self.command("failure", "raise SystemExit(7)"), missing, self.command("timeout", "import time; time.sleep(10)", timeout=1)]
+        self.write_config()
+        self.invoke("record")
+        report = self.invoke("verify", 1)
+        self.assertEqual(report["status"], "not_passed")
+        for status in ("failed", "blocked", "timed_out"):
+            self.assertIn(status, str(report["checks"]))
+
+    def test_check_is_read_only_and_uses_no_project_commands(self) -> None:
+        self.config["checks"] = [self.command("sentinel", "from pathlib import Path; Path('ran').touch()")]
+        self.write_config()
+        self.invoke("record")
+        self.invoke("check")
+        self.assertFalse((self.root / "ran").exists())
+
+    def test_configured_working_directory_and_literal_arguments(self) -> None:
+        (self.root / "package").mkdir()
+        self.config["checks"] = [self.command("cwd", "from pathlib import Path; assert Path.cwd().name == 'package'", cwd="package"), {"name": "argv", "argv": [sys.executable, "-c", "import sys; assert sys.argv[1] == '$(touch injected)'", "$(touch injected)"], "cwd": ".", "timeout_seconds": 5}]
+        self.write_config()
+        self.invoke("record")
+        self.invoke("verify")
+        self.assertFalse((self.root / "injected").exists())
+
+    def test_mutation_during_verify_cannot_pass(self) -> None:
+        self.config["checks"] = [self.command("mutation", "from pathlib import Path; Path('contract.txt').write_text('changed')")]
+        self.write_config()
+        self.invoke("record")
+        report = self.invoke("verify", 1)
+        self.assertTrue(report["monitored_inputs_changed"])
+
+    def test_inspect_respects_git_ignored_dependencies(self) -> None:
+        subprocess.run(["git", "init", "-q", str(self.root)], check=True)
+        (self.root / ".gitignore").write_text("ignored/\n")
+        (self.root / "ignored").mkdir()
+        (self.root / "ignored" / "AGENTS.md").write_text("ignore")
+        (self.root / "package.json").write_text("{}")
+        report = self.invoke("inspect")
+        self.assertIn("package.json", str(report["candidates"]))
+        self.assertNotIn("ignored/AGENTS.md", str(report["candidates"]))
+
+
+if __name__ == "__main__":
+    unittest.main()