refactor: make the repository legible and its contracts durable

.github/workflows/tests.yml

@@ -0,0 +1,20 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m unittest discover -s tests -q
+      - run: python -m json.tool .agents/plugins/marketplace.json >/dev/null
+      - run: python -m json.tool .codex-plugin/plugin.json >/dev/null

AGENTS.md

@@ -16,14 +16,44 @@ templates for agent-assisted implementation.
 - Do not publish credentials, raw private logs, screenshots containing private
   information, or local runtime output.
 
+## Repository Shape
+
+The portable layer is the eight-skill, six-template workflow and its docs; it
+works without Python. The optional `unknowns_harness` layer is a local,
+non-authoritative observer and does not grant authority or perform actions.
+
+## Frozen Contracts
+
+Do not change without a recorded decision:
+
+- package, module, function, and dataclass field names;
+- console script names, flags, exit codes, JSON keys, and key ordering;
+- typed error strings and rejection fields;
+- the eight skills and six templates, including their filenames and content.
+
+The exact module map and platform boundary are in `docs/architecture.md`.
+
+## Input Validation
+
+`evidence_graph`, `consultation_budget`, and `semantic_fingerprint` use
+`type(value) is not str` deliberately; `isinstance(True, int) is True`.
+
+## Non-Authoritative Boundary
+
+The harness observes local inputs only. It must not grant authority, issue
+tokens or permissions, perform external actions, or add an authority layer.
+
 ## Verification
 
 Before pushing, run:
 
 ```bash
+python3 -m unittest discover -s tests -q
+python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
+python3 -m json.tool .codex-plugin/plugin.json >/dev/null
 git diff --check
-find . -type f -not -path './.git/*' -maxdepth 4 -print
 ```
 
 When changing Markdown, inspect the rendered structure or at least review the
-headings and links.
+headings and links. Read `docs/architecture.md` for the complete map and test
+coverage summary.

CLAUDE.md

@@ -0,0 +1,5 @@
+# Agent Instructions
+
+This repository's agent instructions live in [AGENTS.md](AGENTS.md).
+Read [docs/architecture.md](docs/architecture.md) for the module map,
+platform boundary, and test coverage summary.

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+The portable workflow layer is the primary product and must remain usable
+without Python. The optional harness is a local observer only: it does not
+grant authority, issue tokens or permissions, or perform external actions.
+
+## Verification
+
+From the repository root, run:
+
+```bash
+python3 -m unittest discover -s tests -q
+python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
+python3 -m json.tool .codex-plugin/plugin.json >/dev/null
+git diff --check
+```
+
+Public-facing changes receive independent review before push. Changes to the
+skills or templates are contract changes and need a discussion before editing.
+
+`tests/golden/` pins the public CLI output; regenerating it is a contract change requiring a decision.
+`tests/test_docs_consistency.py` fails if a new document or skill is not linked from the README.
+
+See [AGENTS.md](AGENTS.md) for repository rules and
+[docs/architecture.md](docs/architecture.md) for the module map, platform
+boundary, and test coverage.

PROJECT_PROFILE.yaml

@@ -17,8 +17,10 @@ authority:
 
 verification:
   default:
+    - python3 -m unittest discover -s tests -q
+    - python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
+    - python3 -m json.tool .codex-plugin/plugin.json >/dev/null
     - git diff --check
-    - find . -type f -not -path './.git/*' -maxdepth 4 -print
 
 layout:
   skills: skills/

README.md

@@ -20,6 +20,35 @@ Most agent failures are not only coding failures. They are failures to notice
 that the agent was operating with the wrong map: missing domain context,
 implicit taste, unasked architecture questions, or hidden codebase constraints.
 
+## Copy-Paste Prompt
+
+Use this when you want an agent to apply the workflow without installing the
+skills first:
+
+```text
+Before implementing, run an unknowns pass.
+
+Classify the work into:
+- Known Knowns
+- Known Unknowns
+- Unknown Knowns
+- Unknown Unknowns
+
+Declare familiarity as new, partial, or known. If the area is unfamiliar,
+teach me the likely blindspots before planning. If the success criteria are
+implicit, give me a few concrete options to react to before editing code. If
+named decisions remain, ask only the questions that would change architecture,
+scope, or user-visible behavior.
+
+During implementation, keep implementation notes. If the real codebase forces
+you to deviate from the plan, choose the conservative option and log:
+- Expected
+- Found
+- Chosen conservative option
+- Why conservative
+- Follow-up needed
+```
+
 ## The 4-Way Split
 
 Use these labels before implementation:
@@ -233,36 +262,13 @@ disagreement in each direction. The recorded dispatch remains
 `executed: false`.
 
 The lower-level capability preflight remains available as
-`unknowns-harness preflight`.
+`unknowns-harness preflight`. For a capability preflight check, use
+`examples/capabilities-missing.json` as a sample manifest with
+`unknowns-harness preflight --manifest examples/capabilities-missing.json
+--require ledger`.
 
-## Copy-Paste Prompt
-
-Use this when you want an agent to apply the workflow without installing the
-skills first:
-
-```text
-Before implementing, run an unknowns pass.
-
-Classify the work into:
-- Known Knowns
-- Known Unknowns
-- Unknown Knowns
-- Unknown Unknowns
-
-Declare familiarity as new, partial, or known. If the area is unfamiliar,
-teach me the likely blindspots before planning. If the success criteria are
-implicit, give me a few concrete options to react to before editing code. If
-named decisions remain, ask only the questions that would change architecture,
-scope, or user-visible behavior.
-
-During implementation, keep implementation notes. If the real codebase forces
-you to deviate from the plan, choose the conservative option and log:
-- Expected
-- Found
-- Chosen conservative option
-- Why conservative
-- Follow-up needed
-```
+The `workflow` module and console script require POSIX `fcntl`; the preflight
+and review commands remain cross-platform.
 
 ## Optional Automation Gates
 
@@ -279,6 +285,20 @@ unknowns, resolve what matters, log deviations, and teach the result.
 Reviews can use the [proportional review contract](docs/review-contract.md) and
 its optional immutable-artifact provenance check.
 
+## Documentation
+
+- [Architecture](docs/architecture.md) — entrypoints, module map, boundaries,
+  platforms, tests, and growth seams.
+- [Contributing](CONTRIBUTING.md) — verification and contribution guidance.
+- [Workflow](docs/workflow.md) — the portable workflow in detail.
+- [Examples](docs/examples.md) — example artifacts and usage.
+- [Automation gates](docs/gates.md) — optional checks and review hooks.
+- [Review contract](docs/review-contract.md) — proportional review guidance.
+- [Project notes](docs/project-notes.md) — scope and design notes.
+- [日本語の紹介](docs/ja.md) — Japanese overview.
+- [Implementation record](docs/implementation-record.md) — frozen historical
+  build and review record.
+
 ## Status
 
 The original portable skills, templates, and manual workflow are accompanied

docs/architecture.md

@@ -0,0 +1,141 @@
+# Architecture
+
+`unknowns-workflow` ships two layers that are useful together but have
+different requirements.
+
+## Two layers
+
+The portable workflow is the primary product: eight installable skills under
+`skills/`, six reusable templates under `templates/`, and the explanatory
+prose in `README.md` and `docs/`. It works without Python and does not depend
+on the optional harness.
+
+The optional local harness is an installable Python package named
+`unknowns_harness`. It observes and demonstrates the workflow locally. It
+grants no authority, issues no token or permission, and performs no external
+action.
+
+## Entrypoints and module map
+
+The public entrypoints are:
+
+| Entrypoint | Implementation |
+| --- | --- |
+| `unknowns-harness` | `unknowns_harness.cli:main` |
+| `workflow` | `unknowns_harness.workflow_cli:main` |
+| `python -m unknowns_harness` | `unknowns_harness.__main__` -> `cli:main` |
+
+The import and dependency direction is:
+
+```text
+cli.py            -> preflight, review_provenance
+workflow_cli.py   -> workflow
+workflow.py       -> preflight, evidence_graph, consultation_budget
+evidence_graph.py -> stdlib only; imports fcntl
+preflight.py      -> stdlib only
+consultation_budget.py -> stdlib only
+review_provenance.py   -> stdlib only
+telemetry.py      -> stdlib only; no in-package consumer
+semantic_fingerprint.py -> stdlib only; no in-package consumer
+__init__.py       -> preflight only
+```
+
+Module purposes are intentionally small:
+
+- `cli.py` parses the `unknowns-harness` commands and prints preflight or
+  review-provenance results.
+- `workflow_cli.py` parses the two deterministic `workflow` scenarios.
+- `workflow.py` runs the portable-kernel demonstrations and produces their
+  stable observational reports.
+- `preflight.py` checks a caller-supplied capability manifest and returns
+  typed local rejections.
+- `evidence_graph.py` validates and appends non-authoritative JSONL evidence
+  events under an explicit root.
+- `consultation_budget.py` computes deterministic blocker, evidence, and
+  attempt fingerprints and local consultation decisions.
+- `review_provenance.py` validates an optional review record against its
+  caller-supplied artifact, route, and independence requirements.
+- `telemetry.py` builds in-memory observational events with stable JSON.
+- `semantic_fingerprint.py` hashes only explicitly named artifacts and paths.
+- `__init__.py` exposes the small preflight API without importing POSIX-only
+  modules eagerly.
+- `__main__.py` routes `python -m unknowns_harness` to `cli:main`.
+
+`telemetry` and `semantic_fingerprint` have no consumer inside the package.
+They remain public API by intent: callers and tests import them directly, so
+their absence would be a compatibility break rather than dead-code cleanup.
+
+## Platform boundary
+
+`evidence_graph.py` imports POSIX-only `fcntl`. Consequently,
+`unknowns_harness.evidence_graph`, `unknowns_harness.workflow`, and the
+`workflow` console script are POSIX-only. `import unknowns_harness`,
+`unknowns-harness preflight`, and `unknowns-harness review` do not import
+`fcntl` and remain cross-platform.
+
+## Input validation convention
+
+`evidence_graph.py`, `consultation_budget.py`, and
+`semantic_fingerprint.py` deliberately use `type(value) is not str` at their
+closed string-input boundaries instead of `isinstance(value, str)`. The exact
+check rejects string subclasses and preserves the numeric-field rule that
+`isinstance(True, int) is True`; a future cleanup must not weaken these
+contracts. `preflight.py` and `review_provenance.py` use `isinstance` where
+subclass acceptance is harmless.
+
+## Non-authoritative boundary
+
+The harness is an observational local checker. Its outputs describe declared
+capabilities, review records, evidence, telemetry, fingerprints, and demo
+results; they do not authorize effects, issue permissions or tokens, or
+perform external actions. The boundary is not a universal `authoritative`
+field: `PreflightResult`, review-provenance JSON, and telemetry JSON do not
+carry that field and never did.
+
+The boundary's mechanical coverage is deliberately limited. The workflow
+tests use a recursive closed-output check; the evidence path has a closed
+`_FIELDS` set plus injection tests; telemetry has a complete JSON pin; and the
+remaining serializers use frozen dataclass shapes. No single check enforces
+the property globally. The remainder is a semantic boundary held by code
+review, not a keyword filter presented as a proof of authority absence.
+
+## Tests and verification
+
+Tests live under `tests/` and run with the standard library:
+
+```bash
+python3 -m unittest discover -s tests -q
+```
+
+The test modules cover these contracts:
+
+| Test module | Coverage |
+| --- | --- |
+| `test_cli.py` | malformed, rejected, and ready capability CLI results |
+| `test_preflight.py` | manifest shape, capability values, and deterministic JSON |
+| `test_review_provenance.py` | review record schema, routes, identity, and exit codes |
+| `test_evidence_graph.py` | path safety, JSONL durability, schema, locking, and adjudication |
+| `test_consultation_budget.py` | fingerprints, closed records, and consultation limits |
+| `test_semantic_fingerprint.py` | explicit path bounds, escapes, and stable hashes |
+| `test_telemetry.py` | stable in-memory event serialization |
+| `test_workflow.py` | phase order, demos, kernel calls, determinism, and boundary assertions |
+
+The two plugin descriptors are validated as JSON with:
+
+```bash
+python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
+python3 -m json.tool .codex-plugin/plugin.json >/dev/null
+```
+
+## Growth seams
+
+`run_workflow` is intentionally linear while there are two scenarios. If a
+third scenario is added, split the function at its scenario branch so each
+scenario can be read and tested independently. Do not add a registry or
+strategy layer before that condition exists.
+
+`evidence_graph.py` currently keeps five concerns together: path safety,
+canonical encoding, event schema validation, file locking, and exposure
+adjudication. If the module grows further and a real change becomes difficult
+to make, those concerns are the candidate split lines. This is a future seam,
+not work to perform now.

implementation-notes.md → docs/implementation-record.md

@@ -1,3 +1,6 @@
+> This is the frozen historical record of how the harness was built and reviewed.
+> It is not user documentation and is not maintained going forward.
+
 # Unknowns Workflow Harness — Implementation Record
 
 ## Goal

docs/ja.md

@@ -4,6 +4,15 @@
 
 AIにコードを書かせるとき、失敗の原因は「AIの実装力が低い」だけではありません。そもそも依頼文や計画の中に、まだ言語化されていない前提、未確認の仕様、コードベース特有の落とし穴が残っていることが多いです。
 
+## オプションのローカルハーネス
+
+このリポジトリには、ワークフローをローカルで観察・実演する任意の
+Python ハーネスも含まれています。ハーネスは利用必須ではなく、
+ポータブルなスキルとテンプレートは Python なしで利用できます。
+ハーネスの概要は [README の説明](../README.md#what-the-harness-adds) を、
+モジュール構成と対応プラットフォームは
+[アーキテクチャの説明](architecture.md) を参照してください。
+
 このワークフローは、そこを実装前に見つけるためのものです。
 
 ## 何を解決するものか

docs/project-notes.md

@@ -8,7 +8,8 @@ for agent-assisted implementation.
 - Installable skill folders live under `skills/`.
 - Reusable artifact templates live under `templates/`.
 - Public workflow explanation lives under `docs/` and `README.md`.
-- No CLI is included in the initial release.
+- An optional local harness ships the `unknowns-harness` and `workflow` CLI
+  scripts; the portable workflow still works without Python.
 
 ## Design Choices