autofab-py 0.2.0__tar.gz

autofab_py-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+/bazel-*
+/agent_loop.log*
+/staging/
+/testing/
+__pycache__/
+*.py[cod]
+*$py.class
+.update_with_ai.textproto
+.update_with_ai.proto
+/.mcp.active*
+/.cleanroom/
+/.autofab/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.mcp.worker_sessions.json
+.DS_Store
+/.cleanroom_workspaces.json
+/.cleanroom_blame_buffer.json
+/.autofab_workspaces.json
+/.autofab_blame_buffer.json
+*.bak
+*.bak/
+/logs/
+*.cleanroom.log*
+*.autofab.log*
+/benchmark_*
+scratch/
+.coverage*
+autofab_role_workspaces/
+role_workspaces/
+dist/
+build/
+*.egg-info/

autofab_py-0.2.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.5
+Name: autofab-py
+Version: 0.2.0
+Summary: Python methodology and verification tools for the Autofab framework
+Author-email: Sean McDirmid <mcdirmid@outlook.com>
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: pyright>=1.1.350
+Requires-Dist: pytest>=8.0.0
+Description-Content-Type: text/markdown
+
+# autofab-py
+
+Python methodology package, linters, guides, and arbiter verifiers for the [Autofab](https://pypi.org/project/autofab/) autonomous pair-programming framework.
+
+## Overview
+
+`autofab-py` provides the specification methodology, structural linting gates, and AST contracts for Python components developed under Autofab.
+
+### Key Capabilities
+- **Specification Linters**: High-level specification (`high_lint`), epistemic planning (`spec_lint`), and low-level AST contract verifiers (`low_lint`).
+- **Methodology Guides**: Comprehensive pair-programming guides for specifications, double-blind verification, QA arbitration, and test coverage.
+- **Roles**: Declares the canonical Python roles in `autofab_roles.toml`.
+
+## Installation
+
+```bash
+uv pip install autofab-py
+```

autofab_py-0.2.0/README.md

@@ -0,0 +1,18 @@
+# autofab-py
+
+Python methodology package, linters, guides, and arbiter verifiers for the [Autofab](https://pypi.org/project/autofab/) autonomous pair-programming framework.
+
+## Overview
+
+`autofab-py` provides the specification methodology, structural linting gates, and AST contracts for Python components developed under Autofab.
+
+### Key Capabilities
+- **Specification Linters**: High-level specification (`high_lint`), epistemic planning (`spec_lint`), and low-level AST contract verifiers (`low_lint`).
+- **Methodology Guides**: Comprehensive pair-programming guides for specifications, double-blind verification, QA arbitration, and test coverage.
+- **Roles**: Declares the canonical Python roles in `autofab_roles.toml`.
+
+## Installation
+
+```bash
+uv pip install autofab-py
+```

autofab_py-0.2.0/autofab_roles.toml

@@ -0,0 +1,257 @@
+# autofab_roles.toml
+# Autofab Python methodology role definitions
+# Canonical package address: //autofab_python
+
+[methodology]
+name = "python"
+description = "Cleanroom literate specification and verification methodology for Python"
+
+[roles.high]
+name = "high"
+persona = "High-Level Spec Engineer"
+src_pattern = "{unit_dir}/high/{unit_name}.md"
+guide = "autofab_python/guides/high_level_spec.md"
+template = "autofab_python/templates/hls_template.md"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = true
+role_deps = []
+star_role_deps = ["high"]
+common_spec_roles = []
+tools = [
+    "autofab_python.support.lib.high_lint",
+    "autofab_python.support.lib.build_lint_common",
+]
+active_component_types = ["implementation", "assembly", "interface", "external"]
+verify_template = "uv run python -m autofab_python.support.lib.high_lint {unit_dir}/high/{unit_name}.md"
+
+[roles.scenario]
+name = "scenario"
+persona = "Scenario Author"
+src_pattern = "{unit_dir}/scenarios/{unit_name}.md"
+guide = "autofab_python/guides/high_to_scenario.md"
+template = "autofab_python/templates/scenario_template.md"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = true
+role_deps = []
+star_role_deps = ["scenario"]
+common_spec_roles = ["high"]
+tools = [
+    "autofab.support.lib.build_lint_common",
+]
+active_component_types = ["interface", "implementation"]
+verify_template = "# Scenario files verified against high_to_scenario.md"
+
+[roles.planning]
+name = "planning"
+persona = "Planning Engineer"
+src_pattern = "{unit_dir}/planning/{unit_name}.md"
+guide = "autofab_python/guides/high_to_planning.md"
+template = "autofab_python/templates/planning_template.md"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = true
+role_deps = []
+star_role_deps = ["planning"]
+feedback_role_deps = ["high"]
+common_spec_roles = ["high"]
+tools = [
+    "autofab.support.lib.build_lint_common",
+]
+active_component_types = ["implementation", "interface"]
+verify_template = "# Planning canvas verified against high_to_planning.md"
+
+[roles.low]
+name = "low"
+persona = "Low-Level Spec Engineer"
+src_pattern = "{unit_dir}/low/{unit_name}.pyi"
+guide = "autofab_python/guides/planning_to_low.md"
+template = "autofab_python/templates/low_template.pyi"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = true
+role_deps = []
+star_role_deps = ["low"]
+feedback_role_deps = ["planning"]
+common_spec_roles = ["planning"]
+tools = [
+    "autofab.support.lib.build_lint_common",
+]
+active_component_types = ["implementation", "assembly", "interface", "external"]
+verify_template = "uv run python -m autofab_python.support.lib.low_lint {unit_dir}/low/{unit_name}.pyi && uv run pyright --project $([ -f pyright_spec.json ] && echo pyright_spec.json || find . -name pyright_spec.json -not -path '*/.*' | head -n 1) {unit_dir}/low/{unit_name}.pyi"
+
+[roles.spec_qa]
+name = "spec_qa"
+persona = "Specification QA Arbiter"
+src_pattern = ""
+guide = "autofab_python/guides/spec_qa.md"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = false
+role_deps = ["scenario"]
+star_role_deps = ["high", "planning", "low"]
+feedback_role_deps = ["high", "planning", "low"]
+common_spec_roles = ["high", "planning", "scenario"]
+tools = [
+    "autofab_python.support.lib.high_lint",
+    "autofab_python.support.lib.spec_lint",
+    "autofab_python.support.lib.low_lint",
+    "autofab_python.support.lib.build_lint_common",
+]
+active_component_types = ["implementation", "assembly", "interface"]
+verify_template = "uv run python -m autofab_python.support.lib.high_lint {unit_dir}/high/{unit_name}.md && (! test -f {unit_dir}/planning/{unit_name}.md || uv run python -m autofab_python.support.lib.spec_lint {unit_dir}/planning/{unit_name}.md) && uv run python -m autofab_python.support.lib.low_lint {unit_dir}/low/{unit_name}.pyi && uv run pyright --project $([ -f pyright_spec.json ] && echo pyright_spec.json || find . -name pyright_spec.json -not -path '*/.*' | head -n 1) {unit_dir}/low/{unit_name}.pyi"
+verification_success_message = "Specification, planning, and low-level specification verified for {unit_name}."
+
+[roles.lib]
+name = "lib"
+persona = "Lib Engineer"
+src_pattern = "{unit_dir}/lib/{unit_name}.py"
+guide = "autofab_python/guides/low_to_lib.md"
+template = "autofab_python/templates/lib_template.py"
+template_command = "uv run python -m autofab_python.support.lib.lib_lint --scaffold {target_file}"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = true
+role_deps = []
+star_role_deps = ["low"]
+silent_role_deps = ["spec_qa"]
+silent_cross_role_deps = ["lib"]
+common_spec_roles = ["low"]
+tools = [
+    "autofab_python.support.lib.lib_lint",
+    "autofab_python.support.lib.build_lint_common",
+]
+active_component_types = ["implementation", "assembly", "interface"]
+verify_template = "uv run python -m autofab_python.support.lib.lib_lint {unit_dir}/lib/{unit_name}.py --pyi {unit_dir}/low/{unit_name}.pyi && uv run pyright {unit_dir}/lib/{unit_name}.py"
+verification_success_message = "{unit_name}.py passed static checks (syntax & types). IMPORTANT: Static verification does NOT run unit tests or verify runtime logic. If this target has unacted feedback, you must resolve the defect against low/*.pyi contracts and tests before submitting."
+
+[roles.test]
+name = "test"
+persona = "Test Engineer"
+pipeline = "standard"
+src_pattern = "{unit_dir}/tests/{unit_name}_test.py"
+guide = "autofab_python/guides/low_to_test.md"
+template = "autofab_python/templates/test_template.py"
+template_command = "uv run python -m autofab_python.support.lib.test_lint --scaffold {target_file} --lib-pkg {unit_dir}/lib"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = true
+role_deps = []
+star_role_deps = ["low"]
+silent_role_deps = ["spec_qa"]
+stub_role_deps = ["lib"]
+silent_cross_role_deps = ["lib"]
+common_spec_roles = ["low"]
+tools = [
+    "autofab_python.support.lib.test_lint",
+    "autofab_python.support.lib.build_lint_common",
+]
+active_component_types = ["implementation"]
+verify_template = "uv run python -m autofab_python.support.lib.test_lint {unit_dir}/tests/{unit_name}_test.py --pyi {unit_dir}/low/{unit_name}.pyi && uv run pyright {unit_dir}/tests/{unit_name}_test.py"
+
+verification_success_message = "{unit_name}_test.py passed static checks (syntax & types). IMPORTANT: Static verification does NOT execute test suites. Call check_file often to verify test structure and imports."
+
+[roles.qa]
+name = "qa"
+persona = "QA Arbiter"
+pipeline = "standard"
+src_pattern = ""
+guide = "autofab_python/guides/qa.md"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = false
+role_deps = []
+star_role_deps = ["low"]
+feedback_role_deps = ["lib", "test"]
+common_spec_roles = ["low"]
+tools = []
+active_component_types = ["implementation"]
+verify_template = "uv run pytest {unit_dir}/tests/{unit_name}_test.py --timeout=10 --timeout-method=thread"
+verification_success_message = "Test {unit_name}_test.py passed."
+
+[roles.coverage]
+name = "coverage"
+persona = "Coverage Arbiter"
+pipeline = "standard"
+src_pattern = ""
+guide = "autofab_python/guides/coverage.md"
+prompt_template = "Files are aligned according to the guide. Coverage audits must be formulated strictly against public specification contracts. Never demand testing private helpers or internal methods; uncovered defensive branches belong to the library to prune as dead code or mark as unreachable according to the methodology."
+allows_step_mode = false
+role_deps = []
+silent_role_deps = ["qa"]
+star_role_deps = ["low"]
+feedback_role_deps = ["lib", "test"]
+common_spec_roles = ["low"]
+tools = [
+    "autofab.support.lib.autofab_role_tool",
+]
+active_component_types = ["implementation"]
+verify_template = "uv run pytest {unit_dir}/tests/{unit_name}_test.py --timeout=10 --timeout-method=thread && uv run python -m autofab.support.lib.autofab_role_tool coverage --impl {unit_dir}/lib/{unit_name}.py --test {unit_dir}/tests/{unit_name}_test.py --threshold 100.0"
+verification_success_message = "All lines of {unit_name}.py are covered by {unit_name}_test.py."
+
+[roles.pretense]
+name = "pretense"
+persona = "Pretense Engineer"
+pipeline = "pretense"
+src_pattern = "{unit_dir}/pretense/{unit_name}_pretense.py"
+guide = "autofab_python/guides/pretense.md"
+template = "autofab_python/templates/pretense_template.py"
+template_command = "uv run python -m autofab_python.support.lib.pretense_lint --scaffold {target_file} --pyi {unit_dir}/low/{unit_name}.pyi --impl {unit_dir}/lib/{unit_name}.py"
+prompt_template = "Files are aligned according to the guide. In Pretense test suites, define transition postconditions in ctx.ensures(...). In Test<Target>ImplReal, bind real instances into self.sm = TargetStateMachine(singletons={...}) and drive scenarios via self.sm.dispatch_transition(...) without redundant manual assertions, relying on ctx.ensures(...) to verify contracts automatically."
+allows_step_mode = true
+role_deps = []
+star_role_deps = ["low"]
+silent_role_deps = ["spec_qa"]
+stub_role_deps = ["lib"]
+silent_cross_role_deps = ["lib"]
+common_spec_roles = ["low"]
+tools = [
+    "autofab_python.support.lib.pretense_lint",
+    "autofab_python.support.lib.build_lint_common",
+]
+active_component_types = ["implementation"]
+verify_template = "uv run python -m autofab_python.support.lib.pretense_lint {unit_dir}/pretense/{unit_name}_pretense.py --pyi {unit_dir}/low/{unit_name}.pyi && uv run pyright {unit_dir}/pretense/{unit_name}_pretense.py"
+verification_success_message = "{unit_name}_pretense.py passed static checks (syntax & types). IMPORTANT: Static verification does NOT execute test suites. Call check_file often to verify pretense structure."
+
+[roles.pretense_qa]
+name = "pretense_qa"
+persona = "Pretense QA Arbiter"
+pipeline = "pretense"
+src_pattern = ""
+guide = "autofab_python/guides/pretense_qa.md"
+prompt_template = "Files are aligned according to the guide."
+allows_step_mode = false
+role_deps = []
+star_role_deps = ["low"]
+feedback_role_deps = ["lib", "pretense"]
+common_spec_roles = ["low"]
+tools = []
+active_component_types = ["implementation"]
+verify_template = "uv run pretense {unit_dir}/pretense/{unit_name}_pretense.py"
+verification_success_message = "Pretense test {unit_name}_pretense.py passed."
+
+[roles.pretense_coverage]
+name = "pretense_coverage"
+persona = "Pretense Coverage Arbiter"
+pipeline = "pretense"
+src_pattern = ""
+guide = "autofab_python/guides/pretense_coverage.md"
+prompt_template = "Files are aligned according to the guide. Coverage audits must be formulated strictly against public specification contracts. Never demand testing private helpers or internal methods; uncovered defensive branches belong to the library to prune as dead code or mark as unreachable according to the methodology."
+allows_step_mode = false
+role_deps = []
+silent_role_deps = ["pretense_qa"]
+star_role_deps = ["low"]
+feedback_role_deps = ["lib", "pretense"]
+common_spec_roles = ["low"]
+tools = []
+active_component_types = ["implementation"]
+verify_template = "uv run pretense {unit_dir}/pretense/{unit_name}_pretense.py --no-fuzz --cov --threshold 100.0"
+verification_success_message = "All lines of {unit_name}.py are covered by {unit_name}_pretense.py."
+
+[fused_roles.baseline]
+name = "baseline"
+persona = "Baseline Software Developer"
+pipeline = "standard"
+roles = ["lib", "test", "qa", "coverage"]
+guide = "autofab_python/guides/low_to_lib.md"
+
+[fused_roles.pretense_baseline]
+name = "pretense_baseline"
+persona = "Pretense Baseline Software Developer"
+pipeline = "pretense"
+roles = ["lib", "pretense", "pretense_qa", "pretense_coverage"]
+guide = "autofab_python/guides/low_to_lib.md"
+

autofab_py-0.2.0/guides/coverage.md

@@ -0,0 +1,45 @@
+# Guide: Coverage Arbiter
+
+## Summary
+
+The verification targets are the library implementation (`lib/<name>.py`) and the test suite (`tests/<name>_test.py`) for the specified unit. In a multi-node session, multiple targets are evaluated together; each target is evaluated and submitted independently via `submit(target="<target_file>")` once 100% statement coverage is achieved, which stamps `COVERAGE_AUDIT: <timestamp>` into the in-band metadata blocks of `lib/<name>.py` and `tests/<name>_test.py` without modifying their last changed timestamps. All code files (both lib and test files) are strictly read-only for coverage; calling file editing tools on code files is prohibited, coverage never edits `.py` files directly, and coverage delivers defect attribution exclusively via the `blame` tool (specifying the blamed file `lib/<name>.py` or `tests/<name>_test.py`). When coverage deficits involve both roles (such as uncovered requirements in tests and unreachable code in the library), the arbiter attributes blame to each culprit file (`tests/<name>_test.py` and `lib/<name>.py`) within the current round. Deficit diagnosis is concise (under 200 words); the arbiter inspects uncovered lines in the library implementation with line numbers enabled, translates uncovered code into missing specification requirements, and delivers targeted blame. The search tool is never installed.
+
+Blame feedback is strictly a single paragraph containing no newline characters; line breaks, multi-line formatting, and bulleted lists in blame explanations are prohibited. Feedback must be provided in terms of how the file being blamed is not compliant with the common source of truth specification. Line numbers can be mentioned only if they reference the file being blamed; exposing line numbers, code details, or internal variables of other files is strictly prohibited. Blame feedback delivered to the test module is strictly non-prescriptive, identifying only what specification requirements and behavioral aspects lack test coverage; it is framed strictly as missing unit test cases asserting specification postconditions, invariants, or error branches from low-level specifications, and never phrases deficits as defects or missing behaviors in library classes (e.g. stating that a class or method 'does not' perform an action), never prescribes test scenario designs, mock setups, graph topologies, or code snippets, and never mentions library file names, file paths, line numbers, or internal variable names. Blame feedback delivered to the library module is strictly restricted to reporting that code is unreachable under the specification, instructing the library to either restructure the code to eliminate the dead code or annotate it with `# pragma: no cover (assumption: <reason>)` for impossible branches or caller assumptions guaranteed by the contract; diagnosing functional bugs or prescribing functional logic changes to library code is prohibited. When a coverage deficit is attributable to missing unit tests, blaming `tests/<name>_test.py` fully resolves the assigned target; delivering blame, courtesy notices, or informational updates to `lib/<name>.py` when the library implementation contains no unreachable code or dead code is strictly prohibited. When 100% statement coverage is achieved and verified, calling `blame` is prohibited, and the target concludes via the `submit` tool, stamping `COVERAGE_AUDIT` across both verified target files. When coverage cannot be achieved without violating the contract and the code cannot be restructured or annotated with a pragma, the run fails via the `fail` tool instead.
+
+> META: "The coverage arbiter attributes uncovered lines to missing specification requirements or caller assumptions without modifying code files."
+
+## Deficit diagnosis and blame feedback
+
+- [ ] In multi-node sessions, each target is evaluated independently for its corresponding module, and submitted individually via `submit(target="<target_file>")`
+- [ ] All code files are strictly read-only: the agent never modifies `.py` files directly
+- [ ] Uncovered statements are inspected by reading the library implementation file with line numbers enabled
+- [ ] Coverage evaluation presents all uncovered statement spans per cycle without throttling, enabling the arbiter to diagnose all active deficits together
+- [ ] Blame feedback delivered to the test module is strictly non-prescriptive: it identifies only which specification requirements and behavioral aspects lack test coverage, leaving scenario design, fixture structure, graph topology, and assertion choices entirely to the test module
+- [ ] Blame feedback delivered to the test module is framed strictly as missing unit test cases asserting specification postconditions, invariants, or error branches, and never phrases deficits as defects or missing behaviors in library classes (e.g. stating that a class or method 'does not' perform an action)
+- [ ] Blame feedback delivered to the test module never prescribes test implementations, mock configurations, fixture designs, graph shapes, node counts, variable values, or assertion code snippets
+- [ ] Anti-contamination: blame feedback must be provided in terms of how the file being blamed is not compliant with the common source of truth specification (the low-level specification and imported interface/boundary contracts in module_deps); line numbers may be mentioned only if they reference the file being blamed; mentioning line numbers, file names, file paths, internal variables, helper methods, or private execution branches of other files is strictly prohibited
+- [ ] Blame feedback delivered to the test module never instructs tests to assert unmandated behaviors, internal implementation artifacts, or fabricated requirements observed in uncovered library code
+- [ ] Blame feedback delivered to the test module never instructs tests to access private attributes, manipulate internal collaborator state, or invoke uncontracted methods to force execution through defensive branches; unreachable defensive branches are attributed to the library module for pragma annotation or dead code elimination
+- [ ] Uncontracted non-concerns and defensive branches: when library code implements defensive checks or fallback branches for uncontracted non-concerns (conditions not specified in the low-level contract closure), instructing tests to test those branches is strictly prohibited; unreachable defensive branches must be attributed to the library module to prune as dead code or annotate with `# pragma: no cover (assumption: <reason>)`
+- [ ] Repeating identical blame feedback across cycles for an unyielding deficit is prohibited: when previous feedback fails to achieve coverage, the arbiter deepens analysis of the specification contract to formulate distinct requirement aspects or evaluates whether the code is unreachable
+- [ ] In multi-target sessions, the `blame` tool specifies the bound target file receiving blame (`lib/<name>.py` or `tests/<name>_test.py`)
+- [ ] Multi-role defect attribution: when coverage deficits span both the test module and the library module, blame is attributed to each culprit file (`tests/<name>_test.py` and `lib/<name>.py`) within the current round
+- [ ] Test deficit target resolution: when a coverage deficit is attributable to missing unit tests in `tests/<name>_test.py`, delivering blame to `tests/<name>_test.py` fully resolves the assigned target; delivering courtesy blame, informational notes, or status feedback to `lib/<name>.py` when the library implementation contains no unreachable code or dead code is strictly prohibited
+- [ ] Blame feedback paragraph format: the blame explanation string is strictly a single paragraph containing no newline characters; multi-line formatting, line breaks, and bulleted lists in blame explanations are prohibited
+- [ ] Blame feedback delivered to the library module is strictly restricted to reporting that specific code is unreachable under the specification closure: the feedback instructs the library module only to either restructure the code to eliminate the unreachable code or annotate it with `# pragma: no cover (assumption: <reason>)` when the code represents an impossible branch or caller assumption guaranteed by the contract
+- [ ] Defensive deadlock guards, loop stall breakers, and assertions protecting against infinite execution loops are safety guards rather than redundant dead code: blaming library code to delete defensive deadlock or stall guards is prohibited; such guards are covered by testing edge/failure conditions or annotated with `# pragma: no cover (assumption: <reason>)`
+- [ ] Blame feedback delivered to the library module never diagnoses functional bugs, contract deviations, or algorithmic logic errors, and never prescribes functional code fixes; functional defect arbitration belongs exclusively to QA
+- [ ] When coverage cannot be achieved without violating the specification contract and the code cannot be eliminated by restructuring or justified by an assumption pragma, the session concludes via the `fail` tool
+- [ ] When 100% statement coverage is achieved and verified, calling the `blame` tool is prohibited, and the target concludes via the `submit` tool
+
+## Lint checks
+
+- [ ] Applies only to implementation modules ending in `_impl`
+- [ ] The verified target files (lib/<name>.py and tests/<name>\_test.py) contain valid COVERAGE_AUDIT metadata tags upon successful completion
+
+<!-- CLEANROOM METADATA
+LAST_CLEANED: 2026-10-20T22:50:00Z
+LAST_CHANGED: 2026-10-20T22:50:00Z
+CHANGE: Enforce framing coverage blame feedback as missing unit test cases rather than library defects
+CODE_HASH: 34eb94099181
+-->

autofab_py-0.2.0/guides/high_level_spec.md

@@ -0,0 +1,148 @@
+# Guide: High-Level Specifications
+
+## Summary
+
+The artifact is a High-Level Specification (HLS) that defines a software component declaratively through literate prose under `high/<name>.md`. In a multi-node session, multiple high-level specifications are processed together; each target is identified by its file alias relative path, and each target is submitted individually via `submit(target="<target_file>", change_summary="...")` when complete (in single-target sessions, the target parameter may be omitted). Cleanroom metadata blocks at the bottom of the file (enclosed by `<!-- CLEANROOM METADATA` and `-->`) are managed automatically by Cleanroom tooling upon `submit(change_summary=...)`; direct edits to metadata blocks are prohibited and rejected by editing tools. The artifact conforms to this guide and the component architecture described in the design documents. Specifications define interface (`high/<name>.md`), implementation (`high/<name>_impl.md`), external boundary (`high/<name>_ext.md`), or assembly (`high/<name>_asm.md`) components without pseudo-code, bolding, nested bullet trees, or artificial parameter flags.
+
+Specifications define domain concepts through a disciplined term ontology where each concept is represented by exactly one canonical term, avoiding synonym drift and avoiding introducing different terms for opposite sides of the same concept. Component visibility and lifetimes are governed by hierarchical lifecycle tiers (the root system tier and subordinate tiers defined by interface components) where services access each other directly without object type containment or factory plumbing. Specifications follow a closed two-section layout: a why-focused `## Purpose` section with an `**Out of scope:**` boundary disclaimer and an optional `**Delegated:**` boundary statement, and either a unified `## Types and Behavior` section expressed in literate prose with semantic italics strictly on term introductions (for interface, implementation, and assembly specifications), or a `## Grounding Gaps Covered` section in plain prose without semantic italics (for external boundary specifications).
+
+> META: "High-level specifications establish declarative component architectures and disciplined term ontologies; synonym drift, dual-term divergence, and unmandated behaviors are avoided."
+
+## Lint checks
+
+- [ ] Header matches `# <name> <component_type> component` where `<component_type>` is `interface`, `implementation`, `external`, or `assembly`
+- [ ] Front-matter ordering places `assembles:` (for assembly specifications) and `imports:` first, followed by `implements:`
+- [ ] Implementation specifications (`high/<name>_impl.md`) and assembly specifications (`high/<name>_asm.md`) declare `implements: <components>` listing the interface component names closed
+- [ ] Assembly specifications (`high/<name>_asm.md`) declare `assembles: <components>` listing constituent implementation and sub-assembly component names closed
+- [ ] Front-matter `implements:` clause lists interface component names rather than type names or polymorphic types
+- [ ] An interface or external boundary specification never declares `implements:`
+- [ ] Front-matter `implements:` clause never contains entries that are also declared under `imports:` or `assembles:`
+- [ ] An implementation component implements all singleton types defined in each interface component it lists under `implements:`
+- [ ] An assembly component's `implements:` clause equals the union of all `implements:` clauses of its constituent components
+- [ ] An assembly component's `imports:` clause contains all components imported by its constituents except those implemented by the assembly
+- [ ] A root assembly component ready for execution implements all interface components in the binary and has no imports outside data types and external boundary components
+- [ ] Front-matter never contains `instantiates:` or `types from <dep>:` statements
+- [ ] Imported component names in `imports:` never appear in `## Types and Behavior` or `**Out of scope:**`, appearing only in `**Delegated:**` when declared
+- [ ] Implementation import accountability: every component declared in `imports:` of `high/<name>_impl.md` must be utilized in AST signatures or cited in at least one `GROUNDING:` section of `low/<name>_impl.pyi`
+- [ ] Host file literal grounding: host file names, serialization schemas, and repository marker conventions belong strictly in external boundary specifications (`high/<name>_ext.md`)
+- [ ] Section inventory is closed strictly to `## Purpose` and `## Types and Behavior` (or `## Grounding Gaps Covered` for external boundary specifications)
+- [ ] Sub-headers (`###`) are strictly prohibited
+
+## Document structure and front-matter
+
+- [ ] The document consists exclusively of optional front-matter, `## Purpose`, and `## Types and Behavior` (or `## Grounding Gaps Covered` for external boundary specifications)
+- [ ] An interface component (`high/<name>.md`) defines public object types, data types, and capabilities as the bill of sale for consumers and mock generation
+- [ ] An implementation component (`high/<name>_impl.md`) refines capabilities into concrete naming, algorithms, preconditions, and failure feedback for realized types without repeating property catalogs or data fields already defined in implemented interface components
+- [ ] An external boundary component (`high/<name>_ext.md`) describes domain knowledge and grounding gaps covered without specifying an API or types, containing strictly `## Purpose` and `## Grounding Gaps Covered` sections, using zero semantic italics, and grounding to an external boundary stub without Python code
+- [ ] An assembly component (`high/<name>_asm.md`) aggregates constituent implementation and sub-assembly components, closing their combined interface components and propagating unresolved dependencies
+- [ ] Assembly components are purely structural aggregations of constituent components; no behavioral logic, tool installation, algorithmic branching, operational code, or runtime logic can occur at the assembly level
+- [ ] Specifications without external dependencies omit `imports:` entirely
+- [ ] `imports:` lists only component-level module names separated by commas
+- [ ] Implementation specifications declare strictly necessary imports in front-matter; every declared import must be accounted for in downstream low-level AST signatures or explicit `GROUNDING:` arguments
+- [ ] Host file names, configuration schemas, and persistence formats belong strictly in external boundary specifications (`high/<name>_ext.md`); interface and implementation specifications import `_ext` components rather than inventing host file literals
+- [ ] Assembly specifications declare `assembles: <components>` listing constituent implementation and sub-assembly components separated by commas
+- [ ] Implementation and assembly specifications declare `implements: <components>` listing closed interface component names separated by commas
+- [ ] No component appears in both `imports:` and `implements:` within the same specification
+
+## Purpose and boundaries
+
+- [ ] The `## Purpose` section begins with a single standalone summary sentence naming the component (`The <name> <component_type> component ...`) and articulating why the component exists rather than how it maintains state
+- [ ] A single blank line follows the summary sentence, followed by one or two paragraphs of architectural rationale motivating the component from a system perspective
+- [ ] The architectural rationale explains systemic friction, cascading risks, and workflow failure modes prevented, without overlapping or repeating behavioral details from `## Types and Behavior`
+- [ ] The section ends with an out of scope paragraph qualified by the exact prefix `**Out of scope:** `, optionally followed by a delegated paragraph qualified by the exact prefix `**Delegated:** `
+- [ ] The out of scope text identifies workflow purpose, background intent, or caller motivations outside the component and its imported dependencies, ending with `; these are handled by other components.`
+- [ ] Out of scope never lists technical operations that the component coordinates or delegates to its imported dependencies
+- [ ] The delegated text identifies responsibilities within the workflow coordinated by this component that are explicitly delegated to imported collaborator components, mentioning imported component names only at a high level
+- [ ] Collaborator component names in `imports:` appear only in `**Delegated:**` and never appear in `**Out of scope:**` or `## Types and Behavior`
+
+## Term ontology and semantic italics
+
+- [ ] Italics (`*term*`) are used strictly as semantic markers upon the first introduction of a newly defined entity, object type, data type, property or state, sub-type variant, or callable operation
+- [ ] Common English words, adjectives, outcome descriptions, and structural descriptors remain in plain text without italics unless they constitute an introduced domain property
+- [ ] Once introduced, all subsequent references to that term anywhere within the specification remain in plain text without italics
+- [ ] Terms imported from upstream components remain in plain text without italics
+- [ ] Built-in architecture constructs, lifecycle tiers, execution phases, and runtime framework concepts are not introduced by the specification and remain in plain text without italics
+- [ ] Formal parameters of callable tools or explicit execution actions are italicized only upon initial introduction as newly defined parameter entities; general service capabilities express inputs, criteria, and operational context in natural plain-text prose without artificial parameter italics
+- [ ] Literal tokens, method names, and identifiers mentioned in message feedback or naming are enclosed in backticks
+- [ ] External boundary specifications (`high/<name>_ext.md`) use zero semantic italics throughout the document
+- [ ] No bolding (`**term**`) is used anywhere in the specification, except for the `**Out of scope:**` and `**Delegated:**` prefixes
+
+## Canonical language and dual-term elimination
+
+- [ ] Every domain concept is represented by exactly one canonical term; introducing synonyms, alternative verbs, or interchangeable nouns for the same concept is prohibited
+- [ ] Different sides or opposite polarities of a single concept are expressed using the canonical term with negation or boolean qualifiers rather than introducing opposing dual terms
+- [ ] Exceptional and failure conditions are phrased around the exceptional state rather than negating the normal path
+- [ ] Domain verbs are pinned to a single canonical action across the specification rather than alternating between competing synonyms for the same action
+- [ ] Specifications consistently distinguish between configuration schema definitions and runtime invocation values using distinct, consistent terms rather than interchangeable synonyms
+- [ ] Registration and lifecycle management actions use a single canonical verb throughout the specification rather than mixing interchangeable operational verbs
+- [ ] Outcome and result payloads use a single canonical noun throughout the specification rather than alternating between interchangeable synonyms
+- [ ] Conjunctions in prose pair distinct conceptual conditions and never pair synonyms that imply non-existent states or dualities
+- [ ] Relationships between entities are expressed through natural possessive phrasing rather than spatial containment or artificial container nouns
+- [ ] Redundant explanatory gloss is omitted when naming already conveys type or variant intent; downstream enforcement rules belong in the components that enforce them
+
+## Lifecycle tiers and architecture
+
+- [ ] Every singleton service declares its lifecycle tier using natural possessive phrasing rather than "is a" classification (e.g., "The *queue coordinator* of a render session..." or "A system's *resource manager*..."); polymorphic types do not specify a lifecycle tier
+- [ ] Services do not form containment or ownership hierarchies; services within the same tier access each other directly without nested type definitions
+- [ ] Aggregate services maintain collections via explicit operations, never as owned sub-types
+- [ ] Lifecycle tiers form a hierarchy rooted at system with child tiers defined by interface components; descendant tiers may access ancestor tiers, but ancestor services never hold references to descendant services
+- [ ] Subordinate lifecycle tiers are defined in interface components as child tiers of system or another ancestor tier, enabling dependent components to import and participate in that lifecycle
+- [ ] Container and runner frameworks instantiate scoped phase services directly without factory objects
+- [ ] Lifecycle phases are established as execution blocks where scoped services operate, without explicit start or stop operations; processing happens within a scoped lifecycle phase
+- [ ] Lifecycle phase transitions are specified declaratively rather than procedurally, describing initial context provision rather than invocation sequences
+
+## Capabilities and operational rules
+
+- [ ] Content is written in literate prose paragraphs, using selective single-level bullets separated by blank lines to enumerate parallel items or constituent collections
+- [ ] Bullets are never nested; at most one level of bullet points exists
+- [ ] Complete sentences terminate with a period (`.`) and never terminate with a colon (`:`)
+- [ ] Bullets are preceded by a complete sentence ending with a period, followed by a separate sentence fragment header ending with a colon (`:`)
+- [ ] Every bullet point grammatically completes the preceding fragment lead-in into a coherent English sentence
+- [ ] Pseudo-code jargon is avoided: the term "optional" is never used, parameters state their purpose directly, and conceptual service capabilities describe inputs and outcomes in natural prose rather than procedural method signatures
+- [ ] The term "flag" is avoided; boolean choices express domain actions or conditions directly
+- [ ] Features, modes, and options express purpose rather than enablement; phrasing requirements around whether a feature is "enabled" or "disabled" is prohibited
+- [ ] Requirements state capabilities and invariants declaratively, avoiding procedural step-by-step recipes or chronological narratives
+- [ ] Prose paragraphs are concise and focused on a single responsibility or concept, containing at most three sentences; paragraphs never aggregate four or more sentences into dense prose blocks
+- [ ] Multi-sentence branching conditions, operational rules, parameter catalogs, or parallel behavioral constraints are decomposed into single-level bullet lists rather than compressed into narrative paragraphs
+- [ ] Every property, operational parameter, and dependency must have an explicit derivation path from known inputs, process environment, CLI flags, build manifests, upstream node data, or collaborators in scope
+- [ ] Failure content provides actionable diagnostic messages and guidance on how to call the service correctly
+- [ ] Operational feedback, error messages, and reminders communicate declaratively and impersonally without second-person pronouns ("you", "your")
+- [ ] Injected model reasoning communicates thoughts from a first-person perspective ("I", "let me")
+
+## Common pitfalls
+
+- [ ] Dual-term divergence — using different terms for different sides or polarities of the same concept instead of a single canonical term with negation
+- [ ] Synonym drift — alternating between competing verbs or nouns for the same concept
+- [ ] Over-italicization — italicizing common descriptive adjectives, outcome states, or general service inputs that do not represent newly introduced domain concepts or formal tool parameters
+- [ ] Re-italicizing references — italicizing terms on subsequent mentions or when imported from upstream components
+- [ ] Italicizing built-in constructs — italicizing lifecycle tiers, execution phases, or framework concepts that are built-in rather than introduced by the component
+- [ ] Definition-only phantoms — introducing an entity, property, or configuration without a concrete derivation path for its runtime value
+- [ ] Omitted edge-case branches — leaving non-standard outcomes, empty inputs, or boundary cases unhandled in the specification, forcing downstream implementations to guess behavior
+- [ ] Floating directives — specifying that a component loads or resolves data without identifying the source or the mechanism that binds it
+- [ ] Tier custody violations — an ancestor tier service holding direct references to descendant tier services without parameter passing
+- [ ] Pseudo-code jargon — using "optional", "flags", procedural method signatures, or artificial parameter italics for conceptual services instead of declarative literate prose
+- [ ] Enablement phrasing — writing "whether X is enabled" instead of stating the purpose or domain action of the feature
+- [ ] Listing type names or polymorphic types in implements — including type names or polymorphic types rather than concrete interface component names in front-matter
+- [ ] Incomplete interface closure — declaring an interface in implements without implementing all of its singleton types
+- [ ] Overlapping imports and implements — listing an implemented interface component in imports
+- [ ] Procedural recipes — describing chronological step-by-step algorithms or start/stop imperatives instead of declarative invariants
+- [ ] Dangling lead-ins — writing bullets that clash grammatically with the introductory fragment lead-in
+- [ ] Colon after complete sentence — ending a complete sentence with a colon before a bullet list
+- [ ] Nested bullets — creating multi-level bullet trees instead of flat single-level bullet paragraphs
+- [ ] Collaborator leakage in out of scope — naming specific components in out of scope instead of in delegated
+- [ ] Bolding types — using `**term**` instead of `*term*` for introductions
+- [ ] Spatial containment — writing "inside service X" instead of peer tier membership
+- [ ] "Is-a" lifecycle classification — writing "service X is a system service" or "coordinator Y is a render session service" instead of natural possessive or containment phrasing ("A system's service X...", "The coordinator Y of a render session...", "A render session's coordinator Y...")
+- [ ] Redundant gloss — appending wordy explanatory clauses that merely restate what a self-evident type or variant name already conveys (e.g., adding "synchronized with repository storage" to "synced document") or anticipating downstream component enforcement rules
+- [ ] Second-person feedback — specifying failure feedback, error diagnostics, or reminders using second-person pronouns ("you", "your") instead of declarative, impersonal constraints
+- [ ] Monolithic narrative paragraphs — packing multiple responsibilities, branching conditions, or operational outcomes into dense prose paragraphs of four or more sentences instead of decomposing them into concise paragraphs or declarative bullet points
+- [ ] Assembly-level logic — placing operational behavior, extension registration, or algorithm logic inside an assembly component instead of delegating to constituent implementation components
+- [ ] Ungrounded host file names — mentioning concrete host file names or persistence files without defining them in a dedicated external boundary specification (`high/<name>_ext.md`)
+- [ ] Dead implementation imports — declaring imports in an implementation specification that are neither used in low AST nor cited in `GROUNDING:` sections
+
+<!-- CLEANROOM METADATA
+LAST_CLEANED: 2026-10-07T05:04:27Z
+LAST_CHANGED: 2026-10-04T02:03:40Z
+CHANGE: Clarify that cleanroom metadata headers are managed automatically by submit
+CODE_HASH: 8954564f670a
+-->