autofab 0.2.0__py3-none-any.whl

autofab/README.md

@@ -0,0 +1,5 @@
+Run with:
+
+```sh
+bazel run //update_with_ai/tests/example:sample_node_2_clean -- --config //model_configs:default
+```

autofab/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/guides/low_to_lib.md

@@ -0,0 +1,89 @@
+# Guide: Low-Level Specification to Library Implementation Alignment
+
+## Summary
+
+The artifact is a Python library module (`lib/<name>.py` or `lib/<name>_impl.py`) that formalizes `low/<name>.pyi` (and `low/<name>_impl.pyi`), submitted via `submit(target="<target_file>", change_summary="...")`. In multi-node sessions, multiple library modules are processed together by package-relative alias path. Cleanroom metadata blocks at the bottom of the file (under `# --- CLEANROOM METADATA ---` and `# --- END CLEANROOM METADATA ---`) are managed automatically by Cleanroom tooling upon `submit(change_summary=...)`; direct edits to metadata blocks are prohibited and rejected by editing tools. Library modules categorize into interface modules (`lib/<name>.py`) and implementation modules (`lib/<name>_impl.py` or concrete service modules). Interface modules define abstract protocol types, structural stubs, passive data types, and type aliases; service protocols in interface modules subclass `Protocol` and inherit `Singleton[TierType]` matching `low/<name>.pyi`, containing strictly `...` stubs without private backing state, and without `__initialize__`. Interface protocols are implemented by concrete implementation components (`_impl`) that may reside in other components or parts. Classes decorated with `@poly_type` are purely abstract and cannot be refined by a poly type with the same short name (though they may be extended by other poly types to create new abstract object types); only singletons and data types can be instantiated. An `_impl` component with no singletons has nothing to test; implementation components realize active service specifications as concrete `@singleton_type` classes implementing the interface protocol with their declared class-level `tier`. As an edge case, `@data_type` classes extending a `@poly_type` protocol must be concretely implemented in whatever component defines them (including interface modules); these data types are the only types implemented in an interface module.
+
+Implementation modules (`lib/<name>_impl.py` or concrete service modules) translate the structural stubs and behavioral contracts in `low/<name>.pyi` and `low/<name>_impl.pyi` into a complete runtime implementation incorporating real control flow, input validation, iteration sweeps, exception handling, and error response branching. Implementation classes implement their companion interface protocol directly (which already inherits `Singleton[TierType]`), faithfully matching the base class hierarchy in `low/<name>_impl.pyi` without redundantly subclassing `Singleton` or duplicating erased type parameters. Implementation classes define their declared class-level `tier` attribute matching their lifecycle tier and provide concrete private backing state. Modules register singletons into the lifecycle registry via auto-generated module-level `__initialize__(registry=None) -> None`; classes never define `__initialize__`. Singleton instances initialize their private backing state (e.g. locks, collections, caches) in standard `__init__(self) -> None` or the optional inherited lifecycle post-creation hook `def initialize(self) -> None:`. Ad-hoc multi-phase configuration methods (`configure()`, `setup()`) not declared in specifications are prohibited, and implementation classes declare only contracted public members, standard dunder methods, and the optional inherited hook `def initialize(self) -> None:`. Lifecycle registration (`__initialize__`) in implementation modules is auto-generated and maintained by Cleanroom tooling under the `# --- CLEANROOM AUTO-GENERATED: DO NOT EDIT ---` delimiter; manual modification of auto-generated blocks is prohibited. Postconditions (`POSTCONDITIONS:`) specifying unconditional guarantees (`MUST <outcome>.`) and conditional outcomes (`WHEN <condition>, MUST <outcome>.`) are realized as concrete runtime branching (`if/else`), error handling (`try/except`), and exact quoted diagnostic string formatting. Caller assumptions (`ASSUMPTIONS:`) are accepted axiomatically without defensive checks or error branches. Implementation methods and key control-flow branches include brief inline comments indicating how they correspond to the contractual postconditions, invariants, or sequencing specified in `low/<name>.pyi`. Subtypes fulfill the full transitive contract of their supertypes even when low-level specification stubs omit redundant docstring boilerplate. Collaborator singletons are resolved on demand via `get_singleton(...)` respecting lifecycle tier boundaries. Target classes share the exact class names specified in the interface, and obsolete legacy members or uncontracted surplus types are pruned. When low-level specifications reference cross-package types omitted from read-only build dependencies, interface modules isolate them in private fallback containers (e.g. `class _Types: Foo = NewType("Foo", str); pkg = _Types`) and paired implementation modules alias the exact interface container (`pkg = interface_module.pkg`) to preserve nominal identity. When addressing verification feedback or blame reports from downstream roles, all sibling methods, branches, and related operations in the module must be audited for the same failure pattern before submitting, preventing narrow single-defect patches and multi-round ping-pong loops. Unreachable code is pruned or restructured to eliminate dead logic; if unreachable code cannot be otherwise changed (such as defensive branches required by static type checking, runtime protocol conformance, or assertions protecting internal invariants guaranteed by caller assumptions), it is ignored for test coverage by annotating it with `# pragma: no cover (assumption: <reason>)`.
+
+> META: "Library modules translate low-level interface stubs and contracts into abstract protocols for interface components and full runtime execution for implementation components."
+
+## Lint checks
+
+- [ ] Every class and member declared in `low/<name>.pyi` is represented in `lib/<name>.py` with identical names and compatible signatures
+- [ ] In interface modules, service protocols subclass Protocol and inherit Singleton[TierType] matching low/<name>.pyi, contain strictly ellipsis ... member stubs, never declare private state storage, and never define __initialize__
+- [ ] In implementation modules, service classes implement interface protocols faithfully matching the base class hierarchy in `low/<name>_impl.pyi`, define class-level `tier` matching their declared lifecycle tier, and never append bare `Singleton` or duplicate `Singleton[TierType]` base classes; classes decorated with `@poly_type` are purely abstract and can never be directly instantiated in library code
+- [ ] In implementation modules, every singleton class specifies its `tier` attribute matching its declared lifecycle tier
+- [ ] In implementation modules, lifecycle registration (`__initialize__`) is maintained under the `# --- CLEANROOM AUTO-GENERATED: DO NOT EDIT ---` delimiter; interface modules omit `__initialize__`
+- [ ] Data types (`@data_type`) extending a poly type (`@poly_type`) are concretely implemented in whatever component defines them; these are the only types implemented in an interface module
+- [ ] Leaf `@data_type` and `@variant` classes are frozen dataclasses (`@dataclass(frozen=True)`) defining fields matching `low/<name>.pyi`
+- [ ] Subclassed `@data_type` and `@variant` records follow Python dataclass field ordering constraints across inheritance hierarchies, ensuring non-default fields never follow inherited fields that specify default values; default diagnostic formatting belongs in `__post_init__` rather than conflicting field overrides
+- [ ] External libraries are imported only as documented in `low/<name>_ext.pyi`
+- [ ] Pyright type checking passes cleanly with zero errors across all classes
+- [ ] Obsolete public types, type aliases, and class properties not declared in `low/<name>.pyi` or `low/<name>_impl.pyi` are pruned to maintain strict contract alignment and avoid public API pollution
+- [ ] Implementation classes implementing specification protocols declare only contracted public members, standard dunder methods (`__init__`, `__len__`, etc.), and the optional inherited lifecycle hook `def initialize(self) -> None:`; uncontracted public methods (such as ad-hoc `configure()` or `setup()` methods) and class-level `__initialize__` methods are prohibited
+- [ ] In assembly modules (`lib/<name>_asm.py`), `CONSTITUENTS` is defined as a non-empty tuple containing all constituent modules declared under `CONSTITUENTS:` in `low/<name>_asm.pyi`
+- [ ] In assembly modules (`lib/<name>_asm.py`), `__initialize__(registry=None)` is defined and iterates through `CONSTITUENTS` to invoke each constituent module's initialization routine
+
+## Document layout and imports
+
+- [ ] Implementation modules import standard library collections and typing utilities (`Any`, `Callable`, `Dict`, `List`, `Mapping`, `Optional`, `Sequence`, `Set`, `Tuple`)
+- [ ] Implementation and interface modules may import specification framework decorators and types (`singleton_type`, `poly_type`, `data_type`, `variant`, `operation`, `override`) from `support.lib.framework`
+- [ ] Implementation modules import lifecycle infrastructure (`LifecycleRegistry`, `get_default_registry`, `get_singleton`) from `support.lib.lifecycle` (and `Singleton` only when explicitly declared in `low/<name>_impl.pyi`); interface modules import typing, data type dependencies, and `Singleton` / lifecycle tier types matching `low/<name>.pyi`
+- [ ] Domain data types and error classes are imported from interface modules or defined with exact structural parity
+- [ ] Collaborator interfaces are imported directly using package-relative imports
+- [ ] Implementation classes are separated by two blank lines, and class members are separated by one blank line
+- [ ] Cross-package types omitted from read-only build dependencies are isolated in private dummy containers in interface modules (e.g. `class _Types: Foo = NewType("Foo", str); pkg = _Types`), and paired implementation modules alias the exact container from the interface module (`pkg = interface_module.pkg`) to preserve nominal identity
+- [ ] Assembly modules (`*_asm.py`) import all constituent modules declared under `CONSTITUENTS:` in `low/<name>_asm.pyi`, using relative imports for sibling constituents and full package paths (e.g. `from <package_scope>.parts.<pkg>.lib import ...`) for cross-package constituents; bare partial 'parts' imports are strictly disallowed
+
+## Contract realization and control flow
+
+- [ ] In implementation modules, the library realization fulfills the operation sequencing and dataflow dependencies specified in `low/<name>.pyi`
+- [ ] In implementation modules, contractual postconditions (`WHEN <condition>, MUST <consequent>`) in `low/<name>.pyi` are realized as concrete runtime conditionals (`if/else`)
+- [ ] In implementation modules, unconditional postconditions (`MUST <outcome>.`) in `low/<name>.pyi` are realized as runtime assertions, state transformations, or return values
+- [ ] Implementation methods and key conditional branches contain brief comments indicating how they correspond to the postconditions, invariants, or sequencing in `low/<name>.pyi`
+- [ ] When addressing feedback from downstream verification, implementation code fulfills the behavioral contracts and resolves the runtime defect cited in the feedback rather than relying on static compilation alone; sibling methods, branches, and related operations across the module are audited for the same defect pattern before submitting, preventing multi-round ping-pong loops
+- [ ] Caller assumptions under `ASSUMPTIONS:` in `low/<name>.pyi` are accepted axiomatically without defensive validation, exception branching, or error returns
+- [ ] Unreachable code is pruned or restructured to eliminate dead logic; unreachable code is ignored for test coverage using `# pragma: no cover (assumption: <reason>)` only if it cannot be otherwise changed (such as defensive branches required by static type checking, runtime protocol conformance, or assertions protecting internal invariants guaranteed by caller assumptions)
+- [ ] Implementation classes fulfill all inherited supertype contracts and postconditions transitively across the inheritance hierarchy, even when low-level specification stubs omit redundant docstring copy-down
+- [ ] Top-level unbound postconditions declared under `__orphan__()` in `low/<name>.pyi` are realized by the appropriate module service logic
+- [ ] Iterative sweeps and comprehensions process collections, dictionaries, and sequences according to contract requirements
+- [ ] When specifications mandate deterministic ordering or tie-breaking (such as topological sorting or priority queueing where items have identical rank), implementation code uses explicit stable keys (such as ascending alphabetical or lexicographical order) matching low specifications
+- [ ] Happy-path outputs construct and return concrete response records or values matching declared return types in `low/<name>.pyi`
+- [ ] Return values, dataclass parameters, and collaborator method arguments typed as domain NewTypes are explicitly wrapped (e.g. `MyNewType(val)`) rather than passed as bare primitives (`str`, `int`, `float`)
+- [ ] Wire-format type aliases using Python 3.12 syntax (`type WireType = ...`) declared in `low/<name>.pyi` are preserved and re-exported
+- [ ] In interface modules, service protocols retain `...` stubs and dynamic control flow logic is omitted, except for data types extending polytypes which are concretely implemented
+
+## Validation and error branching
+
+- [ ] Missing required parameter checks are implemented where contracts specify missing parameter postconditions in implementation modules
+- [ ] Default value fallbacks are applied where contracts specify default value postconditions in implementation modules
+- [ ] Missing message diagnostic functions are called where contracts specify missing note postconditions in implementation modules
+- [ ] Wire conversions are wrapped in `try/except ParameterConversionError` blocks where contracts specify parameter conversion postconditions in implementation modules
+- [ ] Diagnostic failure responses are formatted using the exact error templates specified in `low/<name>.pyi` postconditions in implementation modules
+- [ ] Custom exception classes realized with `@dataclass` or frozen dataclass semantics implement `def __str__(self) -> str: return self.message` (or call `Exception.__init__(self, message)`) so that `str(exc)` returns the intended human-readable message in test assertions
+- [ ] Value objects realized with `@dataclass` or custom classes representing values, specifications, or identifiers (e.g. `Version`, `VersionRange`, `Label`) implement `def __str__(self) -> str` delegating directly to their canonical string representation or `format()` method so that `str(obj)` seamlessly coerces to the canonical string in string interpolations, logs, and assertions
+- [ ] When contracts specify domain error exceptions (e.g. classes extending `ValueError` or `RuntimeError`), operations raise them with exact quoted messages, and coordinating services catch them to format responses
+- [ ] Catching broad exceptions (such as `except Exception:`) without re-raising is prohibited; task runners, executors, and retry handlers that contractually reify caught exceptions into result records or error attributes (e.g. `_result.error = exc`, `NodeResult(error=exc)`) capture the exception instance, or mark boundary handlers with `# cleanroom: allow-broad-exception`
+- [ ] Collaborator response failures are checked and propagated where contracts specify failure propagation postconditions in implementation modules
+
+## State management and lifecycle integration
+
+- [ ] Stateful singletons in implementation modules declare private instance attributes (`self._tools`, `self._storage`) providing concrete backing storage
+- [ ] Modules register singletons via module-level `__initialize__(registry=None) -> None`; classes never define `__initialize__`; singleton instances initialize backing state via standard `__init__(self) -> None` or the optional inherited lifecycle post-instantiation hook `def initialize(self) -> None:` (invoked automatically by the lifecycle framework for self-registration with managers); uncontracted multi-phase initialization methods (such as ad-hoc `configure()` or `setup()` methods) on classes are prohibited
+- [ ] Phase-level configuration (such as parameterizing session metadata before dependent singletons start) is performed through `enter_phase(phase, setup=...)` using contracted operations (e.g. `RoleConfig.set_role`); inventing uncontracted configuration methods to inject dependencies is prohibited
+- [ ] Dependencies required across singleton operations are resolved on demand via `get_singleton(...)` or passed as contracted method arguments; inventing uncontracted configuration methods to inject dependencies is prohibited
+- [ ] Unreachable defensive branches or assertions protecting internal implementation assumptions are ignored for test coverage using `# pragma: no cover (assumption: <reason>)` only if they cannot be otherwise changed or pruned
+- [ ] In interface modules, service protocols remain purely abstract without instance attributes, backing storage, or mutators
+- [ ] Mutator operations in implementation singletons update internal state collections while enforcing contracted type-level invariants (`INVARIANTS:`), and dynamically synchronize dependent internal tracking state (such as dynamic scheduling queues or lifecycle state mappings) upon structural mutations (such as removals) so that state queries remain synchronized
+- [ ] Getter properties in implementation singletons expose defensive copies or read-only views (`dict(self._tools)`) of internal state
+- [ ] Services in implementation modules resolve peer or ancestor singletons via `get_singleton(...)` on demand rather than caching stale instances in global variables
+- [ ] In implementation modules, `__initialize__` is maintained under the auto-generated block delimiter (`# --- CLEANROOM AUTO-GENERATED: DO NOT EDIT ---`) and left untouched; interface modules omit `__initialize__`
+- [ ] Assembly modules (`*_asm.py`) aggregate and initialize all constituent modules via `CONSTITUENTS` in `__initialize__(registry=None)`, delegating initialization to each constituent module
+
+<!-- CLEANROOM METADATA
+LAST_CLEANED: 2026-10-07T05:04:27Z
+LAST_CHANGED: 2026-10-29T01:10:00Z
+CHANGE: Specify that unreachable code is ignored for coverage only if it cannot be otherwise changed
+CODE_HASH: 17ba67fd84f1
+-->

autofab/guides/meta_guide.md

@@ -0,0 +1,146 @@
+# Guide: Writing Guides for LLM Readers
+
+## Summary
+
+A guide is read by an LLM that produces an artifact satisfying the guide's constraints. This guide states how to write a guide an LLM can follow, and applies its own rules to itself. Every guide has two parts: a Summary that states the initial requirements, and checklist sections that state the fine-grained requirements.
+
+The reader is an LLM consuming the guide through tool reads; it has only the current message and the artifact, and it takes every sentence literally. Every line must be actionable.
+
+The Summary drives the initial write or edit in one or at most two concise paragraphs: it states the high-level subject and core constraints completely so the initial revision is accurate in substance, without detailing fine-grained checks that checklist sections verify. Its purpose is twofold: (a) preserve an already working artifact without unnecessary edits, and (b) when an artifact is missing or starting from a template, establish a minimal valid artifact that passes initial verification before advancing, delegating expanded coverage and fine-grained refinement to progressive checklist steps. Initial creation and bootstrapping instructions belong as comments directly inside templates rather than in the Summary; checklist sections verify that template instruction comments are deleted from the final artifact. Because linters run immediately upon advancing, structural problems are exposed early, keeping the Summary light and focused on core constraints rather than deep rule duplication.
+
+A guide never triggers. The prompt asks for alignment or conformance with the guide and the other input files, and it drives the loop; the guide stakes constraints and requirements only. Directive verbs aimed at the reader ("ensure", "produce", "apply", "verify the checklist", "call advance") are prohibited; declarative constraints ("the module must", "X matches Y") are the rule. Guides and prompts never advise about tool arguments: they can refer to advance, but they cannot refer to tool arguments or the content of advance. Prompts state what the artifact is, never what it is not. Prompts never provide negative instructions, never speculate about other modules or unreadable files, and never instruct on editing mechanics or tool usage. Prompts state the target artifact. Environmental communication to the agent (guides, prompts, tool outputs, reminders, and errors) is declarative and impersonal, stating objective state, invariants, and constraints; second-person pronouns ("you", "your") are prohibited so the agent treats the environment as an execution runtime rather than a conversational partner. Conversely, synthetic assistant steps or injected reasoning designed to steer agent cognition employ the first-person perspective ("I", "let me"), matching the assistant's internal monologue for natural token continuation into tool calls. The ambiguous term "turn" is strictly prohibited across all guides, prompts, and specifications; "step" refers exclusively to a single prompt/tool interaction cycle, and "round" refers to a full Cleanroom role dispatch wave.
+
+Every guide follows this structure:
+
+- `# Guide: <title>`, then `## Summary`, then optional non-step sections (`## Verification failure`, `## Lint checks`), then `## <checklist sections>`.
+- The first `##` heading is the Summary.
+- An optional `## Verification failure` section defines failure-recovery rules and diagnostic-handling constraints delivered only upon verification failure; it is never delivered as a progression step.
+- If the artifact has a linter, a `## Lint checks` section describes what is checked; it is never delivered as a progression step.
+- The boundary is positional: the Summary runs to the next `##` heading; each checklist section runs to the next `##` heading or end of file.
+- Checklist sections contain only `- [ ] <item>` lines.
+- Meta notes in guides are expressed as single-paragraph blockquotes: `> META: "one paragraph of meta note."`. Meta notes provide context or rationale for human authors and tooling, and express information blockades (file and role isolation boundaries); they are filtered out by file readers when read by an LLM agent so the agent is never confused by blockade instructions that the completed system enforces mechanically.
+- The guide reads coherently whole (Summary then sections in order) and sectioned (Summary first, then one section at a time).
+
+> META: "Guides are written for LLM readers that take every sentence literally; meta notes provide guidance for human authors, tooling, and information blockades while remaining invisible to the agent during execution. For the Markdown template format used to structure initial templates with HTML comment directives and parameters, see design-docs/template_format.md."
+
+## Guide structure
+
+- [ ] File is `# Guide: <title>` → `## Summary` → optional non-step sections (`## Verification failure`, `## Lint checks`) → `## <section>` headings, in that order
+- [ ] The first `##` heading is the Summary
+- [ ] An optional section titled `## Verification failure` states instructions or restrictions that apply only when verification fails; it is never delivered as a progression step
+- [ ] If the artifact has a linter, a section titled `## Lint checks` describes what the linter checks; it is never delivered as a progression step
+- [ ] Meta notes are expressed as single-paragraph blockquotes starting with `> META: "one paragraph of meta note."`
+- [ ] Meta notes contain guidance, rationale, or information blockades intended for human authors and meta-tools, never normative requirements or constraints for the agent (since agent readers filter out `> META:` paragraphs)
+- [ ] Information blockades restricting access to other files or roles are expressed strictly as meta notes; direct blockade constraints in the guide are prohibited because the completed system enforces them mechanically, and direct statements confuse the agent
+- [ ] Checklist sections contain only `- [ ] <item>` lines — no prose, no nested headings
+- [ ] The guide reads coherently whole and sectioned
+
+## Summary
+
+- [ ] The Summary states the guide's subject declaratively: an alignment guide names the artifact and its source ("The module implements `low/<name>.md`"); a conformance guide names the artifact ("The artifact conforms to this guide")
+- [ ] The Summary is concise (one or at most two paragraphs), stating complete high-level requirements so the initial write or edit is accurate in substance, while leaving fine-grained rules to checklist sections
+- [ ] The Summary serves two purposes: (a) preserving an already working artifact without edits when contracts and verification pass, and (b) establishing a minimal valid artifact that passes initial verification when starting from scratch or a template, delegating expanded coverage to checklist steps
+- [ ] File references and multi-node session targets use package-relative file alias relative paths (e.g. `high/<name>.md`, `grounding/<name>.pyi`, `lib/<name>.py`, `tests/<name>_test.py`) and never expose host repository filesystem paths
+- [ ] Rules governing the editing process, tool usage, incremental editing strategy, or write permissions belong in the `## Summary` (which is visible before editing begins and throughout all steps in step mode); checklist items verify the artifact after changes are made and show up too late to control how editing is done; rules that apply specifically and exclusively to recovering from verification failure belong in `## Verification failure`
+- [ ] Applicability restrictions and not-applicable conditions (e.g. only applying to implementation specs whose name ends in `_impl.md`) are never in the Summary; they belong in `## Lint checks`
+- [ ] No directive framing — never "ensure", "produce", "transform" (the file pre-exists; the prompt triggers, the guide constrains)
+- [ ] Environmental communication to the agent (guides, prompts, tool outputs, reminders) is declarative and impersonal, stating environmental facts and constraints without second-person pronouns ("you", "your")
+- [ ] Injected reasoning text representing agent cognition uses the first-person perspective ("I", "let me") to match the assistant monologue and drive action continuation
+- [ ] Build-critical requirements come first (BUILD entries, required structure) — nothing builds without them
+- [ ] The guide's requirements are satisfiable from the guide alone: no reliance on the artifact's starting state — the file's existing content (a template, a prior version) is at most an efficiency boost, never the source of required structure
+- [ ] No instruction to run or interpret verification; verification is transparent and the reader's only verification action is calling `advance`; guides and prompts never advise about tool arguments: they can refer to advance, but they cannot refer to tool arguments or the content of advance
+- [ ] Prompts state what the artifact is, never what it is not: no negative instructions, no speculation about other modules, and no editing or tool advice
+- [ ] No instruction to do what the reader cannot do — the reader's capabilities are fixed (file reads, edits, and advance; the search tool is never installed; no execution, no shell, no test runs); a capability the reader lacks is never stated as a requirement and never as a prohibition — the reader already knows it lacks it
+- [ ] No reference to files the reader cannot read (other guides, HLS files, implementations); a label in the source material that names an unreadable file gets one sentence saying it carries no requirements; information blockades are expressed exclusively as meta notes rather than direct reader prohibitions that confuse the agent
+- [ ] External domain knowledge and foreign formats (third-party APIs, foreign serialization formats, runtime identifiers) are excluded from guides; external boundaries are specified in dedicated external boundary specifications (`low/<name>_ext.md`)
+- [ ] Templates provide initial creation and bootstrapping guidance through inline instruction comments; checklist sections verify that template instruction comments are deleted before final artifact completion
+- [ ] Templates follow the Markdown template format in design-docs/template_format.md, using HTML comment directives and placeholder parameters that remain readable without bindings
+- [ ] The Summary mentions templates at most once to describe initial bootstrapping ("When starting from a template, the template's inline instructions guide creating a minimal artifact...")
+- [ ] No meta-commentary, no rationale, no examples — state the constraint
+
+## Checklist sections
+
+- [ ] Each item is one independently verifiable constraint on the artifact; no cross-item reasoning ("see above")
+- [ ] Checklist items constrain the post-edit artifact state (what the artifact contains), never the editing process or tool mechanics (how editing is performed) — process, tool, and editing constraints belong in `## Summary`
+- [ ] Items carry the precision: exact spellings, required forms, conformance checks — never style preferences the source already dictates
+- [ ] Each item is checkable given the Summary, the section, and the artifact
+- [ ] Sections are ordered fine-grain-first (layout, imports, types, contracts, pitfalls)
+- [ ] File references in all sections use package-relative file alias relative paths and never expose host repository filesystem paths
+- [ ] If the artifact has a linter, a `## Lint checks` section (with the exact title "Lint checks") describes what is checked
+- [ ] All checklist items that can be deterministically verified by verifying the presence or absence of a specific string, marker, or token belong in `## Lint checks` (and are implemented by the artifact's linter), never in judgment-based content sections
+- [ ] The `## Lint checks` section contains only linter-verified checks and applicability constraints (e.g., target spec must end in `_impl.md`) — no human judgment points
+- [ ] A point only partly linter-verified is split: the linter-verified part goes in `## Lint checks`, the judgment part stays in its content section
+
+## Step mode
+
+- [ ] In step mode the reader sees the Summary and one section at a time; earlier sections are stubbed — each section is self-sufficient: a rule the section depends on appears in that section or in the Summary
+- [ ] Checklist sections are delivered after edits are made and an advance is called: they cannot control how editing is done because they show up too late; all editing workflow and tool rules live in `## Summary`
+- [ ] Since guide delivery does not advance to subsequent sections until verification passes, checklist items cannot help the reader resolve verification errors; rules that govern resolving verification failures belong in `## Verification failure`
+- [ ] A rule with no document region (it constrains the whole artifact) lives in the Summary, never in a section
+- [ ] All items in a section concern one step of producing the artifact; if the items split into two concerns, split the section
+- [ ] If one item can undo another, they are one item stating both constraints, or two items in the same section with the clobbered rule first
+- [ ] Sections are named after the document regions they govern, in document order
+- [ ] A rule that applies to every instance in a region is stated once, generically ("every operation", "every alias")
+
+## Size
+
+- [ ] Whole guide under the read-size limit (20,000 bytes in this repo) so whole-guide mode reads it in one read
+- [ ] Cut anything that does not change what the reader produces: restated rules, meta-commentary, duplicate examples
+- [ ] Smaller is not automatically better; cutting an exception the reader needs is worse than a few extra lines
+
+## Wording
+
+- [ ] Headers and lists over tables; one fact per line; each line complete on its own
+- [ ] Second-person pronouns ("you", "your") are prohibited in all agent-facing environmental messages (guides, prompts, tool outputs, reminders, errors); constraints and states are stated impersonally and declaratively
+- [ ] First-person perspective ("I", "let me") is used when injecting synthetic assistant reasoning to simulate internal agent cognition and prime tool execution
+- [ ] Standard terminology: the ambiguous term "turn" is strictly prohibited; "step" is used exclusively for single prompt/tool interaction cycles, and "round" is used exclusively for full Cleanroom role dispatch waves
+- [ ] "must", "never", "only" — never "should consider", "ideally"
+- [ ] Never state a rule as "X or Y" when the reader must choose; state the condition of the choice
+- [ ] Say what is an error and what is merely discouraged; the reader treats both as prohibitions unless told otherwise
+- [ ] State exceptions beside their rules; the reader over-generalizes prohibitions
+- [ ] Distinguish REQUIRED structure ("must contain") from CONTENT rules; the reader deletes redundant-looking required structure unless told it is required
+- [ ] Define terms once; never introduce synonyms for one concept
+- [ ] State each rule once within a section; a section never relies on a rule stated only in an earlier section (step mode stubs it) — repeat the rule or state it in the Summary
+
+## Examples
+
+- [ ] One strong example per rule beats three similar ones
+- [ ] Every example obeys the guide's own rules
+- [ ] Anti-examples paired with their fixes
+- [ ] Examples never come from the current problem under work: no type names, components, or phrases from the specs, code, or conversation being guided; every example is a clean synthetic one invented for the guide
+
+## Self-check
+
+- [ ] Truncation test: cut at any line; every line before the cut remains a complete fact
+- [ ] Action test: an LLM can derive a constraint from each sentence
+- [ ] Section test: given the Summary, one section, and the artifact, the reader can check that section's items
+- [ ] One-read test: given the whole guide in one read, the reader produces the required structure and applies the rules
+- [ ] No-trigger test: no sentence directs the reader to do something the prompt already drives ("ensure", "produce", "call advance")
+- [ ] Capability test: every action the guide names is one the reader can perform with its tools — no test runs, no shell, no unreadable files
+- [ ] Perspective test: all environmental communications to the agent are declarative and impersonal without second-person pronouns ("you", "your"); injected assistant reasoning uses the first-person perspective ("I", "let me")
+- [ ] Path test: no host filesystem paths appear anywhere in the guide; only package-relative file alias relative paths appear (such as `high/<name>.md`, `grounding/<name>.pyi`, `lib/<name>.py`, `tests/<name>_test.py`)
+- [ ] Linter test: if a linter exists for the artifact, a section titled `## Lint checks` lists all automated and applicability checks, and no applicability rules appear in the Summary
+- [ ] Deterministic test: every check verifiable by verifying presence or absence of a specific string or token is listed in `## Lint checks`
+
+## Common pitfalls
+
+- [ ] Bloat — restated rules, meta-commentary, duplicate examples — cut each fact once
+- [ ] Chunk-fragile structure — tables, header-dependent lines, "as above" — one fact per line; lists over tables
+- [ ] Second-person environmental address — using "you" or "your" in guides, prompts, tool responses, or reminders instead of declarative, impersonal constraints; or failing to use first-person perspective when injecting assistant reasoning
+- [ ] Ambiguity — "should", "can optionally" — "must", "never", "only"
+- [ ] Buried rules — the load-bearing constraint after examples — front-load; examples after rules
+- [ ] Exposing file paths — using host or repository filesystem paths (e.g. `specs/low/<name>.md` or `testing/parts/...`) instead of package-relative file alias relative paths (e.g. `high/<name>.md`, `grounding/<name>.pyi`)
+- [ ] Applicability in Summary — stating not-applicable conditions or spec filters in the Summary instead of `## Lint checks`
+- [ ] Mixed lint/judgment points — a point the linter half-checks left whole — split: the linter part in `## Lint checks`, the judgment part in its content section
+- [ ] Deterministic checks outside Lint checks — placing string-presence or string-absence checks in content sections instead of `## Lint checks`
+- [ ] Process rules in checklist — placing editing strategy, tool usage, or step-by-step modification rules in checklist sections instead of `## Summary` where they are visible before editing
+- [ ] Failure recovery in Summary or checklist — placing verification-failure recovery rules (such as fail-tool escalation or diagnostic triage) in `## Summary` or checklist sections instead of `## Verification failure`
+- [ ] Missing Lint checks section — omitting `## Lint checks` when a linter is present
+- [ ] Implicit requirements — required structure shown only by example — say "must contain"; list the structure
+- [ ] Over-general rules — a prohibition without its exception — state the exception beside the rule
+- [ ] Rule-breaking examples — a snippet that violates the guide — every example must conform
+- [ ] Context examples — a snippet lifted from surrounding code or specs — use synthetic examples that obey the guide's rules
+- [ ] Triggering — a sentence that instructs the reader ("ensure the module...") — the guide constrains; the prompt triggers
+- [ ] Checklist items helping with verification — attempting to use checklist sections to guide the reader through resolving verification errors; because guides do not advance until verification passes, checklist items cannot help the reader fix verification failures
+- [ ] Capability noise — telling the reader to run or interpret checks it has no tool for, or stating what it cannot do — the reader's capabilities are fixed; mention only actions the reader can take
+- [ ] Direct information blockades — stating information blockades or unreadable file prohibitions directly in guide text or checklist items instead of expressing them exclusively as meta notes (`> META: "..."`); the completed system enforces file isolation mechanically, and direct blockade statements confuse the agent

autofab/parts/__init__.py

@@ -0,0 +1,3 @@
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)

autofab/parts/agent/description.md

@@ -0,0 +1,31 @@
+# Agent Part (`update_with_ai/parts/agent`)
+
+## Purpose
+
+The **agent** part establishes the foundational session abstractions, operational policies, virtualized file addressing, and target-level execution configurations governing autonomous AI agent interactions in Cleanroom.
+
+Rather than exposing physical host paths and ambient machine environments directly to language model agents—which causes hallucinated paths, cross-environment drift, and context pollution—the agent part creates a secure, virtualized execution boundary. It defines the lifecycle scope for individual agent sessions, restricts file interactions through virtual file aliases with explicit read/write permission tiers, parses and extracts model configuration parameters, and models task prompts and node definitions for dependency-directed workflows.
+
+## Key Components & Specifications
+
+According to the high-level specifications in [`update_with_ai/parts/agent/high/`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high):
+
+- [`session.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/session.md): Defines the canonical lifecycle tier identifying agent session boundaries beneath the system-wide application environment. It ensures that ephemeral conversation state, session configurations, and tool allocations do not leak across distinct agent runs.
+- [`agent_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/agent_config.md): Formalizes system-level operational policies and execution limits for agent sessions, including conversation turn limits, trailing character limits for superseded arguments (`supersede arg keep`), follow-up tool call injection, progressive guide delivery (`step mode`), startup file inspection, and delta-based edit reporting.
+- [`file_alias.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/file_alias.md): Decouples agent session file operations from physical filesystem paths. It provides the `FileAlias` abstraction distinguishing *bound files* (mapped to workspace files with an owning node, categorized as *read-only* or *read-write*) from *unbound files*. It provides the `AliasManager` which resolves relative string paths to file aliases and sanitizes agent-visible text by masking host filesystem paths.
+- [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md): Unifies node-level execution configurations for an active session. It models `RoleConfig` (the active role, sequence of nodes being cleaned, and execution version counter) and `SessionConfig` (resolved read-only and read-write files, step-by-step guides, starter templates and template parameters, verification checks, blame targets, and incoming defect feedback).
+- [`node_storage.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_storage.md): Extends DAG storage with target manifest metadata. It preserves target definitions, task prompts, and dependency relationships, and evaluates node dirtiness dynamically by comparing in-band source file metadata against dependency change timestamps.
+
+## How It Is Used by Other Parts
+
+The `agent` part is a central domain contract consumed across the entire Cleanroom ecosystem:
+
+- **`control`**: Uses [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md), [`file_alias.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/file_alias.md), and [`node_storage.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_storage.md) to set active session roles, discover ready dirty tasks, synthesize task prompts with user-facing aliases, evaluate verification checks, and attribute defects back to culprit upstream nodes.
+- **`sandbox`**: Relies on [`file_alias.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/file_alias.md) and [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md) to enforce read-only vs. read-write permissions during file reads and edits, deliver progressive guides, evaluate verification checks in `check_files`, and validate blame targets during `submit`, `fail`, or `blame`.
+- **`workspace`**: Uses [`file_alias.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/file_alias.md) and [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md) to map declared bound files, scaffold initial project trees, populate starter templates, and synchronize files between isolated role workspaces and the canonical workspace.
+- **`subagent`**: Uses [`session.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/session.md), [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md), and [`node_storage.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_storage.md) to configure session scopes and task instructions when dispatching roles to autonomous subagents.
+- **`antigravity` & `dsh`**: Use [`session.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/session.md) and session config types to bind execution turns to isolated role environments in Google Antigravity and DeepSeek Harness.
+- **`loop` & `openai`**: Use [`session.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/session.md), [`agent_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/agent_config.md), and [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md) to enforce conversational turn limits, assemble prompt messages, and manage driver execution.
+- **`workspace_cli`**: Uses [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md) and [`file_alias.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/file_alias.md) to implement workspace CLI commands (`get-work`, `check-files`, `submit`, `blame`).
+- **`uv`**: Implements [`node_config.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_config.md) from Python build targets and manifest definitions.
+- **`metadata`**: Implements [`node_storage.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_with_ai/parts/agent/high/node_storage.md) through source file in-band comment metadata.

autofab/parts/agent/high/agent_config.md

@@ -0,0 +1,34 @@
+# agent_config interface component
+
+## Purpose
+
+The agent_config interface component defines execution limits, interaction modes, and read policies governing agent sessions.
+
+Autonomous agent workflows require explicit bounds on conversational depth, automated tool chaining, instructional delivery modes, and session initialization. Without centralized agent operational policies, individual drivers and execution environments risk unbound execution loops, inconsistent instruction pacing, and uncoordinated file reads. The agent_config interface component establishes a unified system service that exposes conversational turn limits, follow-up injection policies, step-by-step guidance modes, and startup file read rules.
+
+**Out of scope:** The agent_config interface component does not manage API credentials, parse build manifests, or compute graph schedules; these are handled by other components.
+
+## Types and Behavior
+
+A system's *agent config* provides execution parameters for agent sessions.
+
+A *conversation limit* bounds the number of model interaction turns permitted in an agent run. A *supersede arg keep* limit bounds the number of trailing characters of a superseded string argument retained as a recognizable hint, resolving from agent session configuration.
+
+An agent config also provides operational policies governing how the agent behaves during an agent run.
+
+The policies of an agent config are:
+
+- A *follow-up injection* policy directing the agent to execute the follow-up tool calls that tool responses specify.
+
+- A *step mode* policy permitting the agent to receive a guide progressively.
+
+- A *startup read* policy directing the agent to inspect declared files at session start.
+
+- A *delta output* policy directing editing tools to report the changes they make rather than complete file content.
+
+<!-- CLEANROOM METADATA
+LAST_CLEANED: 2026-10-15T17:42:46Z
+LAST_CHANGED: 2026-10-11T01:39:02Z
+CHANGE: Replace the fragment policy lead-in with declarative policy properties and canonicalize policy terminology
+SPEC_QA_AUDIT: 2026-10-15T17:42:46Z
+-->