POHEEngineering field guide
OPEN PACKAGE / AGENT + CLI + SKILLS

Point the lens
at your own harness.

A portable agent package for the 52 POHE records. Scan an arbitrary repository for harness-pattern cues, pull the structural candidates into source review, and turn what survives into a pattern-guided evolution proposal.

Open the repository Install the CLI
  • MITlicense
  • stdlibno runtime deps
  • 52frozen records
  • 3agent skills
THE PIPELINE

Three moves, three questions.

What is worth reading? Is the mechanism in this scope? What may safely change?

01 / DETECT

Where are the leads?

Run the frozen cue expressions over code, tests, and support files. Excludes caches, build output, and vendored trees.

pohe-agent scan <repo>
02 / ANALYZE

Is the mechanism here?

Anchor each cue to its enclosing declaration, then check context, trigger, structure, and effect. The packet reports missing roles, the negative control, and contract probes. Parallel file analysis is deterministic with --jobs.

pohe-agent analyze <repo> --pattern P01
03 / EVOLVE

What may change?

Build a proposal that protects the contract, names authority, adds the test obligation, and records rollback.

pohe-agent plan <repo> --findings findings.json
INSTALL / 60 SECONDS

Clone, install, point.

The scanner is Python standard library only. The agent instructions and skills travel with the repository.

Python 3.10+. No API key, no network access, and no repository upload.

TERMINAL
git clone https://github.com/xhyccc/pohe-agent.git
cd pohe-agent
python3 -m pip install -e .
pohe-agent scan /path/to/your/harness
WHAT SHIPS

An agent package, not a black box.

Every layer is readable, testable, and replaceable.

A

AGENTS.md

The operating manual: the evidence ladder, the standard workflow, the hard rules, and the handoff points between detection, matching, and evolution.

S

Three skills

Detection finds leads. Matching adjudicates a candidate against the pointcut, contract, and negative control. Evolution plans and verifies the change.

  • pohe-pattern-detection
  • pohe-pattern-matching
  • pohe-harness-evolution
C

CLI

scan, match, analyze, plan, list, and show. Deterministic walking, JSON output, and Markdown reports.

D

Frozen catalog

All 52 records: pointcut, contract, variation, test obligation, negative control, evolution question, cue, and canonical exemplar where one exists.

E

Runnable example

A three-file mini harness with a bounded loop, deferred tool discovery, and a permission check. Scan it before pointing the tool at your own code.

T

Tests

Catalog integrity, repository walking, cue retrieval, structural candidates, report boundaries, and plan generation. Runs on every push.

VALIDATION / 41 REPOSITORIES

Run on the study's own checkouts.

Not only the bundled example: 52 records against 41 frozen repositories, compared cell by cell with the published cue matrix.

172,832candidate files scanned
2,132repository × record cells
98.55%exact agreement
99.60%recall over study-positive cells

All five misses are files the scanner excludes by design: four above the 2 MB limit and one minified third-party asset. Most extra cells are cells where re-running the study's own detector retrieves cues the frozen matrix omits. This is cue-level agreement, not a claim that every match is an implemented pattern. Method and per-cell differences

The current calibration audit retrieves all 51 canonical anchors and rejects none, while keeping 33 missing-structure cases and one medium negative-control risk visible. It does not force exemplars to pass. Read the calibration report

EVIDENCE LADDER

Cues are leads.
Contracts are claims.

The tool can produce E1 on its own. E2 and E3 require reading the source, the tests, or a runtime check. The package keeps that boundary visible in every report.

Read the full evidence key
  1. E0
    Proposed recordThe frozen specification and its negative control.
  2. E1
    Retrieval cueA regex or symbol hit. Produced by scan and match.
  3. E2
    Source-located mechanismRoles, state, and control flow identified in source.
  4. E3
    Contract supportExecutable or explicit evidence for ordering, errors, or boundaries.
AGENT WORKFLOW

From scan to recorded decision.

  1. 01

    Orient

    Read the target repository's own instructions and confirm the task: detection only, matching, or evolution.

  2. 02

    Scan

    Retrieve cues, read the family table, and keep unobserved records visible as unobserved.

  3. 03

    Analyze

    Run analyze, read the anchored scope and missing roles, then open the source. Answer all four pointcut dimensions and all four contract fields. Apply the negative control.

  4. 04

    Record

    Write the evidence level actually reached, the files and tests, and the remaining unknowns.

  5. 05

    Plan

    Protect the contract, stay inside the variation seam, and name authority, rollback, and a retirement trigger.

  6. 06

    Verify

    Add the contract test first. Exercise failure and termination paths. Canary one real task before rollout.