POHEEngineering field guide
METHOD / EVIDENCE / REPRODUCIBILITY

Claims should carry
their own boundaries.

This site is a static rendering of a proposed pattern discipline and an exploratory repository audit. It deliberately separates a useful record from the evidence that supports it.

Open the paper Research agenda Return to the catalog
01

Evidence key

A pattern label, a lexical cue, a source-located mechanism, and a reviewed contract are not interchangeable.

E0 / PROPOSED

Pattern specification

The context, trigger, structure, effect, contract, variation, test obligation, and negative control define a candidate mechanism. A specification does not assert repository conformance.

E1 / RETRIEVAL

Exploratory retrieval cue

A frozen regular expression or structural matcher finds a place to inspect. A hit is not a confirmed implementation. Coverage counts any available evidence layer and is not a prevalence estimate.

E2 / SOURCE

Source-located exemplar

A repository, immutable commit, and implementation locator identify a concrete example. The atlas holds at most one canonical exemplar per candidate, so it cannot measure cross-repository contract depth.

E3 / CONTRACT

Executable or contract support

Ordering, errors, or boundaries need additional executable or contract evidence. The field guide does not infer E3 from the presence of a source anchor.

02

Frozen inputs

The rendered catalog uses the supplied candidate manifest, pointcut specification, interaction models, canonical atlas, and any-evidence coverage table. Repository clones, caches, evidence packets, and raw evidence are intentionally excluded from this site.

Inventory
52 records / five source families
Audit panel
41 repositories / 36 families
Specification
v0.1.0
Diagram models
v1.0.0 / analytical
Study checkout
dbb9bf8f685dcf7a219d9440565821c12b715a59
Detector environment
PyYAML==6.0.3
pandas==2.3.3

Input and detector SHA-256

These hashes identify the exact local inputs used for this rendering. A hash supplies integrity, not validity.

Study-relative fileSHA-256
data/manifests/candidates.csvd3c071946ab128642275544e4de15705b4864fe060d2b94eae647ae74ffd1410
protocol/harness_pattern_specification.yaml3f5e16a539675ba5e1831d24d531906ff15411a5acefbabe085279a605c091c2
protocol/pattern_diagram_models.yaml25b18e5f64ecae7eec21acf91f5c2d5c73139f0c51bd2ae7b0d1961abcc4b545
protocol/detector_queries.yaml41811b978a3b96f91dc1da1e542d650e08bcc173300e006f2a0fe1ce87ee6699
reports/full_catalog/pattern_instance_atlas.csvc334af137d972e26289abb9f217254cef687971bfbff8e49c1bcb3dc305e43e0
data/statistics/pattern_coverage.csvc211d3dd55b8db786cbc95b428c4b6e5148234a821295a4de6488e2e194a757c
data/derived/pattern_repo_realizations.csv34b0dae9fb6ecd491d480c0d9e04e43461e1a4149dc6e1df116099c810574977
data/manifests/current_41_repositories.csv61155fb41ffc1e21e8de0bdaee844071e3e1f3537cd43fab1f9fac3ad4d10cdd
environment/requirements.lock9d20a7092c271e0455d1ee7cd89185f371a0dfa9a6d11e07c2955f75eaa521f4
src/detectors/run_candidate_queries.pyf24ed3772b753d3e37ea48651d1c789055f1c979d5d76e2186a3f8362c16d60e
src/detectors/layered_pattern_matcher.pyfc194d459b5b0f0536446d1f94ab81ae7036c9a81ef4e0a32dfa80eae476c45f
03

Improvement loop

Revise from evidence outward; retain a change only when the claim–evidence link and quality gates hold.

  1. Register claims. Type each statement as descriptive, exploratory, presentational, or causal.
  2. Attach evidence. Name the frozen artifact and independent unit.
  3. Audit integration. Require both evidence and a visible manuscript link.
  4. Rank gaps. Prioritize inference-changing analysis over decorative summaries.
  5. Compute the smallest sufficient result. Preserve denominators, missing-data semantics, and uncertainty.
  6. Run statistical and manuscript QA. Retain or roll back without weakening claim boundaries.
04

Overlay boundary

The layered matcher adds Python AST symbols, multi-language declarations, artifact context, exact-symbol refinement, and source triage to frozen lexical retrieval. It remains a discovery instrument, not an automatic conformance classifier.

The first broad pass produced 851 overinclusive candidates and was rejected. Exact refinement produced 16 review candidates; eight promoted cells live in a separate, non-frozen overlay. The frozen 1,272-cell evidence matrix remains unchanged. Overlay coverage therefore cannot be read as a new field-wide prevalence estimate.

Historical cue gaps are detector gaps, not evidence of retirement. A source path change is a cue-path event, not automatically an architectural redesign.

05

Reproduce the study

Run these commands in a complete companion study checkout with its locked environment. Network access and GitHub authentication are needed only for discovery, freezing, and repository materialization. This static site does not include those repository caches.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
make seed test

# Core frozen pipeline
make final verify

# Empirical and longitudinal extension
make longitudinal

# Corpus-level detector, matrix, statistics, and figures
make cartesian

# Layered discovery and separately reviewed overlay
make layered-overlay
make coverage-funnel

Rebuild this field guide

python3 scripts/generate_site.py
python3 -I tests/validate_site.py
python3 -m http.server 8000

The generator uses PyYAML with a stdlib fallback and expects ../pattern-mining-study and ../POHE_complete/main.pdf by default; --study and --paper override those paths.

Source repository

The supplied study checkout has no configured public remote. This field guide therefore does not invent an external study-repository URL. Canonical source anchors link directly to the named public implementation repository at the recorded commit. The complete local paper is available as the companion PDF.

06

Limitations

  • The 52 records are a scoped candidate inventory, not 52 disjoint or universally established mechanisms.
  • Current cue coverage is descriptive retrieval in a selected frozen panel, not a prevalence denominator or confirmed prevalence.
  • Locating a source-backed exemplar for 51 of 52 records does not establish frequency, generality, or contract conformance elsewhere. E08 remains specification-only.
  • Lexical detectors have false-positive and construction-leakage risks. Exact structural matching and one-model profile coding do not replace independent adjudication. The post-freeze scope-anchored calibration is an instrument audit; its source_matched verdict is not E2/E3.
  • A² is a proposed analytical lens, not a validated lifecycle model. Recording a contract does not enforce it.
  • H1–H3 are prospective, design-only studies. No causal performance, safety, cost, or reliability benefit follows from repository association.
  • The complete paper PDF is an unpublished, untagged preview, not an accessibility-compliant publication file.
07

Research agenda

The Paper page carries the full H1–H3 agenda: stable design commitments, mechanized agency, and controlled variation, with evidence and falsification boundaries attached to each claim.

Read the research agenda on the Paper page
◇

Colophon: why this field guide exists

By Haoyi Xiong

It continues an unpublished master’s research project on design patterns.

That project asked what this one still asks: when does a recurring solution become a pattern, and what must a record say before anyone else can use it? The vocabulary here is learned from the Gang of Four’s catalog, Roy T. Fielding’s account of architectural styles in network software, and Douglas C. Schmidt’s writing on distributed-computing patterns and the Pattern-Oriented Software Architecture series.

Those teachers insisted on the discipline this guide tries to keep: name the join point, state the contract, separate what may vary, and show the evidence. The field guide is dedicated to the research that remained unpublished—and to the readers who can carry the question further.