POHE Agent

Detect harness design patterns. Match them to protected responsibilities. Plan evolution without losing authority.

pohe-agent is a portable agent package and command-line tool for the Pattern-Oriented Harness Engineering field guide. It brings the 52-record POHE harness pattern catalog to an arbitrary repository, then helps an agent or maintainer decide what is actually there and what may safely change.

The package is deliberately small and dependency-free. The scanner is Python standard library only; the agent instructions and skills work with any coding agent that reads AGENTS.md or SKILL.md.

Quick start

git clone https://github.com/xhyccc/pohe-agent.git
cd pohe-agent
python3 -m pip install -e .
pohe-agent scan /path/to/your/repo --json findings.json --markdown findings.md

Then inspect the structural candidates for a record:

pohe-agent match /path/to/your/repo --pattern P01,P09 --markdown candidates.md
pohe-agent show P01

For a scope-anchored evidence packet instead of symbol leads:

pohe-agent analyze /path/to/your/repo --pattern P01,P09 --markdown analysis.md

analyze maps each cue to its enclosing declaration, checks an operational signature for context, trigger, structure, and effect, applies the record's negative control, and reports the missing roles. Cues are matched with identifier-aware boundaries, and a signature may carry calibrated operational aliases when the frozen regex misses its own exemplar. See docs/analysis.md for the method and docs/calibration.md for the 51-anchor audit that separates retrieval gaps, anchor gaps, and missing structure roles.

And turn findings into a reviewed evolution proposal:

pohe-agent plan /path/to/your/repo --findings findings.json \
  --patterns P01,P09 --goal "harden termination and tool discovery" \
  -o evolution.md

No installation is required for development:

PYTHONPATH=src python3 -m pohe_agent scan examples/mini_harness

What it does

repository
   │
   ├── scan ────────► lexical cues (E1) + review priority
   │                    per record, file, line, contract, negative control
   │
   ├── match ───────► structural symbols + adjudication questions
   │                    Python AST, declaration syntax, alias hits
   │
   ├── analyze ─────► scope-anchored evidence triangulation
   │                    operational signature, dimensions, negative control,
   │                    contract probes, verdict
   │
   └── plan ────────► pattern-guided evolution proposal
                        protected contract, variation, tests, authority,
                        rollback, verification gates

scan

Runs the frozen cue expressions over code, test, and support files. It excludes dependency caches, build output, vendored trees, minified files, and files over 2 MB. Every candidate file is scanned by default. Pass --max-files N only when you need a hard runtime bound; the budget keeps code first, then tests, then support material, so a large docs tree cannot crowd out the source. The output is a JSON document plus an optional Markdown report.

Each observed record carries:

• join point and four pointcut dimensions,
• contract fields (requires, ensures, invariant, violation),
• the negative control,
• representative file and line matches,
• a review priority (high, medium, low),
• the next review action.

match

Extracts function, class, and declaration symbols and narrows them to candidates whose name, alias, or body contains the record's cue. It returns candidates and the questions needed to adjudicate them. A body hit is a lead, not a pointcut match; it does not decide that a candidate is a pattern instance.

analyze

Anchors each cue to the smallest enclosing function, method, class, or declaration, then checks an operational signature against the scope. A signature is a detection contract, separate from the prose pointcut, so a curation disagreement does not silently change the matcher. The output reports dimension-level coverage, missing roles, negative-control checks, contract probes, test linkage, and an explicit verdict from rejected to source_matched.

source_matched means the scope visibly contains every signature role. It is not E2 and not contract support. Tests are excluded from primary candidates by default because fixtures often contain every role at once; use --include-tests when that is the object of study.

plan

Builds a Markdown evolution plan from scan findings. It preserves the protected contract, the permitted variation, the test obligation, the negative control, and the evolution question for each selected record. The plan is a proposal: authority, evidence, rollback, and retirement remain to be filled.

The evidence ladder

Level	Meaning	What the tool can produce
E0	Proposed record	The frozen specification
E1	Retrieval cue	scan, match, and analyze candidate retrieval
E2	Source-located mechanism	An agent or maintainer reads the source; analyze prepares the packet
E3	Contract support	Tests or runtime checks named per contract field

A cue is not an implementation. Cue coverage is not prevalence. Absence of a cue is not absence of a mechanism. The tool is a discovery and review instrument, not a conformance classifier.

Agent package

The repository is also an agent package:

AGENTS.md                                  operating manual for coding agents
agent.md                                   pointer for tools that look for agent.md
skills/pohe-pattern-detection/SKILL.md     scan and triage
skills/pohe-pattern-matching/SKILL.md      adjudicate a candidate
skills/pohe-harness-evolution/SKILL.md     plan and verify a change

This is the beginning of the README. Read the rest at the original. Read the full README ↗