# Intent and Evidence Project Engine — FULL RESEARCH CORPUS (share wrapper) Abbreviation: iepe Version: v0.2.0 Bundle name: llm-full-docs-iepe Upstream artifact: .agents/llms-full-iepe-v0.2.0.txt Generated: unspecified ======================================================================== # INTENT AND EVIDENCE PROJECT ENGINE (IEPE): CONSOLIDATED MASTER RESEARCH & CODEBASE CORPUS Protocol Root Version: v0.2.0 (2026-09-29) | Modules: 128 | Total Lines: 7,663 Protocol Identity: IEPE Core Protocol: v0.2.0 (0970d35) Corpus Payload SHA-256 (excluding this field): 2ed985740fef0bcccee91c7b37109f2ca492a381bac46d942e3dc9b470f2dea8 TABLE OF CONTENTS & SUBSYSTEM SUMMARY: - Protocol Architecture, Doctrine & Governance: 23 files - Canonical Contract Schemas & Protocol Definitions: 16 files - Core Reference Implementation (iepe_core): 7 files - Core Tools & Utilities: 3 files - Examples & Protocol Fixtures: 38 files - TestSuite & Verification Gates: 7 files - Operational Work Graph & Issues: 15 files - Verification & Execution Evidence: 17 files - Other Protocol Modules: 2 files ======================================================================== ======================================================================== ## SUBSYSTEM: PROTOCOL ARCHITECTURE, DOCTRINE & GOVERNANCE (23 files) ======================================================================== --- FILE: .agents/AGENTS.md (74 lines, 2.5 KiB) --- # IEPE Core Agent Operating Contract This repository develops the project-agnostic Intent and Evidence Project Engine. ## Authority Resolve conflicts in this order: ```text 1. docs/PROTOCOL.md 2. Approved decision records 3. JSON schemas 4. Coordinator and adoption specifications (docs/COORDINATOR.md, docs/REFERENCE.md) 5. Issue contracts and acceptance criteria 6. Implemented code and templates 7. Generated artifacts and agent output ``` ## Single Agent Reference For the universal single-file cheat-sheet and adoption protocol, see [`docs/REFERENCE.md`](docs/REFERENCE.md). ```text Adopt IEPE for this repository. Target: ./ Pinned IEPE source: https://github.com/zachshallbetter/IEPE (v0.2.0) Project Intent: "" Project Mode: existing | new Mutation Authority: local-files ``` ## Required operating behavior Intent governs implementation. Issues authorize committed work. Project state belongs in the work graph. Agents execute only within bounded authority. Evaluation is independent from candidate authorship where practical. Promotion requires declared evidence. Every material change must preserve: ```text intent -> epic -> issue -> artifact -> evidence -> qualification -> promotion ``` ## Ticket-first rule Committed changes require a complete issue contract with intent, objective or hypothesis, owner, parent, dependencies, acceptance, evidence, constraints, permissions, budget, and stop conditions. ## Maturity Keep these dimensions separate: ```text Backlog -> Ready -> In progress -> In review -> Done -> Verified Documented != Implemented != Tested != Empirically Validated Intent -> Explored -> Specified -> Prototyped -> Implemented -> Observed -> Validated ``` ## Stop rule Continue while authority, context, ownership, dependencies, permissions, and evidence remain valid. Stop at unverified boundaries. ## Generalization rule Core artifacts must remain domain-neutral. Domain-specific terminology, integrations, evaluators, and policies belong in adoption profiles or adapters. ## Process routing Use the narrowest applicable project-local skill: - `initialize-iepe-project` for new and existing project adoption. - `reconcile-iepe-project` for first-cycle and stale-state reconciliation. - `operate-iepe-project` for the coordinator execution loop. - `qualify-iepe-outcome` for evidence and promotion review. - `stress-test-iepe-candidate` for designed unknown-variable trials. - `maintain-iepe-package` for package compilation and protocol updates. --- FILE: .agents/skills/initialize-iepe-project/SKILL.md (27 lines, 1.8 KiB) --- --- name: initialize-iepe-project description: Initialize a new project under IEPE or inspect an existing project for adoption. Use when starting a project, creating its agent operating layer, adopting IEPE, generating a project profile, or preparing the first agent cycle. --- # Initialize an IEPE Project Read `docs/INITIALIZATION.md` and `docs/UPSTREAM_REFERENCE.md` from the pinned IEPE Core source. IEPE adoption follows a two-stage pattern: **reconcile first, then apply**. ### Universal Inputs Required - `target_project`, `project_mode` (`new` | `existing`), `iepe_source`, `iepe_revision` (immutable tag/digest), `project_intent`, `work_graph_provider`, `mutation_authority`, `protected_actions`. ### Existing Project Adoption (Two-Stage) 1. **Stage 1 (Reconcile):** Execute read-only discovery using `tools/init_project.py existing --project-root `. Reconstruct intent provenance (established, inferred, proposed, observed, unresolved), map authority, reconcile work graph, and propose the IEPE overlay. Do not modify files. 2. **Stage 2 (Apply):** Once the reconciliation report and adoption plan are approved, apply the overlay under explicit mutation authority on an isolated branch. Preserve existing valid local authority. ### New Project Initialization 1. Require project ID, name, originating intent, IEPE source, and immutable revision. 2. Run `tools/init_project.py new` from the pinned IEPE source. 3. Preserve existing files unless the user explicitly authorizes replacement. 4. Validate the protocol reference and project profile. 5. Complete the initialization gates before making an issue Ready. 6. Hand off to the first operational agent with `.agents/NEW_AGENT_PROMPT.md` for read-only reconciliation. Return created or inspected artifacts, unresolved authority, evidence gaps, and the next authorized action. --- FILE: .agents/skills/maintain-iepe-package/SKILL.md (14 lines, 1.0 KiB) --- --- name: maintain-iepe-package description: Compile, validate, or update an IEPE Agent Project Package and its upstream protocol pin. Use when canonical sources, skills, adapters, schemas, or IEPE versions change, or when generated context is stale. --- # Maintain an IEPE Package Read `docs/AGENT_PROJECT_PACKAGE.md` and `docs/UPSTREAM_REFERENCE.md` from the pinned source. Repair contradictions in canonical project sources, then compile the package. Never edit generated context as an authority fix. Retain source roles, ranks, state, hashes, skills, adapters, exclusions, protocol identity, and revision. For a protocol update, compare revisions, run upstream conformance, validate the local profile, reconcile schema and adapter changes, and exercise one reversible coordinator cycle. Change the pin only after qualification. Release classification requires clean declared source state. Package integrity does not prove semantic correctness or empirical validity. --- FILE: .agents/skills/operate-iepe-project/SKILL.md (19 lines, 1.0 KiB) --- --- name: operate-iepe-project description: Run the IEPE coordinator loop for authorized project work. Use when selecting, claiming, dispatching, evaluating, recording, and closing agent-executed issues under a project profile. --- # Operate an IEPE Project Read `docs/COORDINATOR.md` from the pinned IEPE source and the local `PROJECT_PROFILE.json`. Run the state sequence: ```text preflight -> reconcile -> select -> validate -> claim -> assemble context -> dispatch -> observe -> evaluate -> disposition -> record -> close loop ``` Require a complete Ready issue before a claim. Bind each dispatch to issue, claim, context digest, worker, role, permissions, and attempt. Do not expand permissions through an adapter. Preserve negative and inconclusive results. Release the claim at terminal disposition. Stop with a typed blocker when any gate loses authority, context, ownership, dependency validity, permission, evaluator availability, provider health, or recovery. --- FILE: .agents/skills/qualify-iepe-outcome/SKILL.md (18 lines, 1.0 KiB) --- --- name: qualify-iepe-outcome description: Qualify IEPE artifacts and worker results against declared evidence before status or maturity promotion. Use for completion review, evidence intake, promotion decisions, release readiness, or claims that work is done, tested, verified, or validated. --- # Qualify an IEPE Outcome Bind every assertion to the issue, candidate, environment, evaluator, provenance, and reproduction method. Distinguish artifact existence from evaluation and evaluation from empirical validation. Use the weakest justified maturity when evidence differs across dimensions: ```text Documented != Implemented != Tested != Empirically Validated ``` Missing provenance, required dimensions, evaluator independence, reproduction, or protected-action authority blocks promotion. Retain failed, negative, bounded, and inconclusive outcomes. Return an evidence bundle, qualification, limitations, evidence gaps, promotion recommendation, and named authority required for any next promotion. --- FILE: .agents/skills/reconcile-iepe-project/SKILL.md (14 lines, 1.1 KiB) --- --- name: reconcile-iepe-project description: Reconcile an IEPE project's canonical documents, work graph, claims, implementation, reviews, deployments, and evidence. Use for a new agent's first cycle, stale project state, migration, contradiction review, or selecting the next Ready issue. --- # Reconcile an IEPE Project Begin read-only. Verify the pinned protocol, local profile, authority chain, repository or workspace identity, work graph, dependency state, claims, implementation, reviews, deployments, and evidence. Classify findings as established, inferred, proposed, observed, or unresolved. Observation does not grant authority. Record contradictions, stale claims, incomplete issue contracts, unsupported maturity, and protected actions. Return a typed reconciliation result with verified identities, discrepancies and provenance, blockers and required authority, material unknowns, the first candidate Ready issue, and mutations that remain unauthorized. Do not repair state during the reconciliation pass unless mutation authority was explicitly included in the issue contract. --- FILE: .agents/skills/stress-test-iepe-candidate/SKILL.md (12 lines, 0.9 KiB) --- --- name: stress-test-iepe-candidate description: Apply IEPE epistemic stress testing to a frozen candidate using designed perturbations and sealed World Cards. Use when consequential results may depend on unknown variables, hidden conditions, alternate environments, or untested assumptions. --- # Stress Test an IEPE Candidate Read `docs/EPISTEMIC_STRESS_TESTING.md` from the pinned IEPE source. Freeze the qualified candidate before revealing designed perturbations. Define protected invariants, surprise budget, evaluator, evidence, and stop conditions. Use sealed World Cards when the test depends on withheld conditions. Record each result as robust, adaptable, bounded, fragile, unsafe, or unknown. Update the unknown-variable ledger and robustness profile. Do not use synthetic trials to claim human outcomes. Stop when a perturbation crosses consent, safety, identity, factual, or promotion boundaries. --- FILE: AGENTS.md (73 lines, 2.5 KiB) --- # IEPE Core Agent Operating Contract This repository develops the project-agnostic Intent and Evidence Project Engine. ## Authority Resolve conflicts in this order: ```text 1. docs/PROTOCOL.md 2. Approved decision records 3. JSON schemas 4. Coordinator and adoption specifications (docs/COORDINATOR.md, docs/REFERENCE.md) 5. Issue contracts and acceptance criteria 6. Implemented code and templates 7. Generated artifacts and agent output ``` ## Single Agent Reference For the universal single-file cheat-sheet and adoption protocol, see [`docs/REFERENCE.md`](docs/REFERENCE.md). ```text Adopt IEPE for this repository. Target: ./ Pinned IEPE source: https://github.com/zachshallbetter/IEPE (v0.2.0) Project Intent: "" Project Mode: existing | new Mutation Authority: local-files ``` ## Required operating behavior Intent governs implementation. Issues authorize committed work. Project state belongs in the work graph. Agents execute only within bounded authority. Evaluation is independent from candidate authorship where practical. Promotion requires declared evidence. Every material change must preserve: ```text intent -> epic -> issue -> artifact -> evidence -> qualification -> promotion ``` ## Ticket-first rule Committed changes require a complete issue contract with intent, objective or hypothesis, owner, parent, dependencies, acceptance, evidence, constraints, permissions, budget, and stop conditions. ## Maturity Keep these dimensions separate: ```text Backlog -> Ready -> In progress -> In review -> Done -> Verified Documented != Implemented != Tested != Empirically Validated Intent -> Explored -> Specified -> Prototyped -> Implemented -> Observed -> Validated ``` ## Stop rule Continue while authority, context, ownership, dependencies, permissions, and evidence remain valid. Stop at unverified boundaries. ## Generalization rule Core artifacts must remain domain-neutral. Domain-specific terminology, integrations, evaluators, and policies belong in adoption profiles or adapters. ## Process routing Use the narrowest applicable project-local skill: - `initialize-iepe-project` for new and existing project adoption. - `reconcile-iepe-project` for first-cycle and stale-state reconciliation. - `operate-iepe-project` for the coordinator execution loop. - `qualify-iepe-outcome` for evidence and promotion review. - `stress-test-iepe-candidate` for designed unknown-variable trials. - `maintain-iepe-package` for package compilation and protocol updates. --- FILE: LICENSE (176 lines, 9.9 KiB) --- Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS --- FILE: README.md (148 lines, 5.8 KiB) --- # IEPE Core: Intent and Evidence Project Engine [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![Protocol Version](https://img.shields.io/badge/Protocol-IEPE--001%20v0.2.0-green.svg)](docs/PROTOCOL.md) [![Python Version](https://img.shields.io/badge/Python-3.11%20%7C%203.12-blue.svg)](pyproject.toml) **IEPE** (Intent and Evidence Project Engine) is a open-source, project-agnostic engine for **documentation-first, ticket-first, evidence-qualified AI software engineering**. It solves the fundamental failure modes of autonomous coding agents: **governance livelocks, infinite retry loops, phantom completions, unverified claims, and lost project context**. --- ## ⚡ Single Agentic Adoption Command To adopt IEPE on any new or existing project, copy and paste this single command block directly into your AI coding agent (Cursor, Antigravity, Claude, ChatGPT, Windsurf, Devin): ```text Adopt IEPE for this repository. Target: ./ Pinned IEPE source: https://github.com/zachshallbetter/IEPE (v0.2.0) Project Intent: "" Project Mode: existing | new Mutation Authority: local-files Execution sequence: 1. Preflight: Run workspace write capability probe once. 2. Reconcile: Perform read-only discovery of intent, files, and authority order. 3. Apply: Generate AGENTS.md, PROJECT_PROFILE.json, and .iepe/protocol-reference.json. 4. Validate: Run iepe-validate or python3 tools/validate.py. ``` --- ## 💡 What is IEPE? Modern AI agents write code fast, but without governance they drift from intent, claim completion on broken builds, overwrite existing invariants, or loop indefinitely on missing environment capabilities. IEPE provides a deterministic operating layer beneath any agent: 1. **Intent Governs Implementation:** Code exists to fulfill declared human intent, not arbitrary agent guesswork. 2. **Ticket-Bound Authority:** Agents execute bounded work contracts with explicit scope, permissions, and budget. 3. **Preflight Capability Probing:** Environment constraints (e.g. read-only filesystems) are detected *before* discovery to prevent governance livelocks. 4. **Evidence-Qualified Promotion:** Claims require empirical proof (tests, schemas, benchmarks) before work is promoted to `Done`. 5. **Status Honesty:** Strict operational boundary: `Documented != Implemented != Tested != Empirically Validated`. --- ## 🔗 The Governing Chain Every material change must preserve complete lineage from intent to promotion: ```text Intent -> Doctrine & Experience Contracts -> Portfolio Objectives & Epics -> Issue Contracts & Experiments -> Coordinated Agent Execution -> Artifacts & Empirical Observations -> Independent Evaluation -> Evidence-Qualified Promotion -> Retained Institutional Memory ``` --- ## 📖 Quick Links & Documentation Index | Document | Purpose | | :--- | :--- | | ⚡ [**Single Agent Reference**](docs/REFERENCE.md) | **One-page cheat-sheet** for human developers and AI agents | | 📖 [**Protocol Specification**](docs/PROTOCOL.md) | Canonical protocol invariants, condition taxonomy, and stop semantics | | 🚀 [**Adoption Guide**](docs/ADOPTION.md) | Two-stage adoption pattern (`reconcile` then `apply`) | | 🛠️ [**Initialization Guide**](docs/INITIALIZATION.md) | Step-by-step onboarding for greenfield and existing projects | | 🔄 [**Coordinator Specification**](docs/COORDINATOR.md) | Coordinator state machine, preflight sequence, and blocker deduplication | | 🧪 [**Epistemic Stress Testing**](docs/EPISTEMIC_STRESS_TESTING.md) | Designed perturbation trials and unknown-variable discovery | | 📜 [**Negative Results Register**](docs/NEGATIVE_RESULTS.md) | Institutional memory of disproven hypotheses and protocol lessons | --- ## 🛠️ Quickstart CLI ### Installation ```bash pip install -e .[dev] ``` ### 1. Stage 1: Reconcile (Existing Project Discovery) Inspect an existing repository without making any file modifications: ```bash iepe-init existing --project-root /path/to/project --report /path/to/report.json ``` ### 2. Stage 2: Apply (Initialize Operating Layer) Establish the project-local operating layer: ```bash iepe-init new \ --project-root /path/to/project \ --project-id project.example \ --project-name "Example Project" \ --intent "The core outcome this project exists to cause." \ --protocol-source "https://github.com/zachshallbetter/IEPE" \ --protocol-revision "v0.2.0" ``` ### 3. Conformance Validation Run the full validation suite (schemas, issue templates, skills, evidence bundles, and domain neutrality): ```bash iepe-validate ``` Or execute unit tests directly: ```bash pytest -v ``` --- ## 📊 Current Engine Maturity ```text Documented != Implemented != Tested != Empirically Validated ``` | Capability | Maturity | Evidence / Location | | :--- | :--- | :--- | | Core Protocol (`IEPE-001`) | **Tested** | [`docs/PROTOCOL.md`](docs/PROTOCOL.md) | | Preflight Capability Probing | **Tested** | [`iepe_core/bootstrap.py`](iepe_core/bootstrap.py) | | Blocker Fingerprinting & Livelock Fix | **Tested** | [`iepe_core/coordinator.py`](iepe_core/coordinator.py) | | `WAITING_EXTERNAL` Parked State | **Tested** | [`tests/test_coordinator.py`](tests/test_coordinator.py) | | Provisional Profile Generation | **Tested** | [`tests/test_bootstrap.py`](tests/test_bootstrap.py) | | Contract Schema Suite (16 Schemas) | **Tested** | [`schemas/`](schemas/) | | GitHub Issue Templates (8 Templates) | **Tested** | [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/) | | Conformance Suite (`iepe-validate`) | **Tested** | [`tools/validate.py`](tools/validate.py) | | Agent Project Package Compiler | **Tested** | [`tools/compile_package.py`](tools/compile_package.py) | --- ## 📄 License IEPE Core is open-source software licensed under the [Apache License, Version 2.0](LICENSE). --- FILE: ROADMAP.md (85 lines, 3.2 KiB) --- # IEPE Core Roadmap ## Project intent Make rigorous agentic project operation portable across domains without forcing every project to invent its own coordination, evidence, and promotion model. ## M1: Adoption Kit Goal: make IEPE installable as a documentation and GitHub workflow profile. - Refine the protocol vocabulary and boundaries. **In progress** - Validate issue and evidence schemas. **Tested** - Add design, evaluation, decision, incident, and promotion templates. **Tested** - Define the minimum project profile. **Tested as schema** - Provide a reproducible conformance command and fixture suite. **Tested locally** - Define migration from an existing ticket system. **Tested synthetically** - Produce one complete example project. **Tested synthetically** - Specify new-project and existing-project initialization. **Documented** - Implement reference-pinned command-line initialization. **Tested locally** - Implement conversational initialization. - Compile canonical sources into Agent Project Packages. **Tested locally** Exit evidence: an unrelated pilot can adopt the protocol and create a valid work graph without additional doctrine. ## M2: Coordinator Reference Goal: implement a provider-neutral coordinator state machine. - Project preflight and reconciliation. **State gates tested locally** - Readiness validation. **Typed assertion gates tested locally** - Claim and capacity management. **Tested locally** - Context-packet assembly. **Tested locally** - Worker dispatch interfaces. **Tested locally** - Evidence intake and qualification. - Stop-state enforcement. **Tested locally** - Receipt persistence and replay. **Tested locally** - Epistemic stress testing. **Tested synthetically with sealed World Cards** - Promotion recommendation. Exit evidence: a coordinator can complete a simulated delivery issue and experiment while rejecting invalid transitions. ## M3: GitHub Adapter Goal: make GitHub Issues and Projects a complete IEPE work-graph adapter. - Native hierarchy and dependency mapping. - Field and status synchronization. - Branch, commit, pull request, and deployment lineage. - Evidence comments and reconciliation. - Portfolio and focused-project projections. Exit evidence: an end-to-end pilot completes through a real GitHub project. ## M4: Experience and Design Qualification Goal: prove that intent and design survive agentic decomposition. - Experience-contract schema. - Journey and interaction references. - Automated UI evidence adapters. - Human observation records. - Design maturity enforcement. Exit evidence: a user-facing change remains traceable from intent through observed production behavior. ## M5: Cross-Domain Validation Goal: validate IEPE outside software engineering. - Research pilot. - Writing or editorial pilot. - Business-operations pilot. - Creative-production pilot. Exit evidence: the core remains unchanged while domain profiles supply appropriate evaluators and promotion rules. ## Initial epics 1. Protocol and terminology refinement. 2. Contract and schema suite. 3. Coordinator state machine. 4. GitHub adapter. 5. Experience and design evaluation. 6. Project memory and negative-result retention. 7. Pilot and conformance suite. --- FILE: The-Project-Is-the-Benchmark.md (115 lines, 16.8 KiB) --- # The Project Is the Benchmark ## What a 232x GPU optimization result reveals about the future of agent-run work In June 2026, a developer named Sankalp entered an unusual GPU programming contest. The assignment was to implement a batched QR decomposition, the kind of numerical routine whose practical performance depends on details most software developers can safely spend a career avoiding: Householder reflections, memory movement, launch overhead, precision tolerances, kernel specialization, and the peculiar appetite of tensor cores for matrix-shaped work. The contest was organized by GPU Mode with Core Automation. Its infrastructure made the problem unusually legible to an agent. A command-line tool could submit a candidate, check its correctness, benchmark it across multiple matrix shapes, and return shape-specific timings. Incorrect implementations were rejected. Correct implementations were ranked by their geometric mean runtime. The problem had a strict contract, a quantitative objective, and a machine-readable verdict. Sankalp used Codex to work inside that environment. The result was a final tracked runtime of 1,805 microseconds, compared with a rough baseline of 419,000 microseconds: a 232-fold speedup. He placed twelfth among 183 participants despite describing himself as an experienced enthusiast rather than a professional GPU-kernel engineer. The developer immediately above him on the leaderboard was a principal engineer at NVIDIA. The number is spectacular. The process behind it is more consequential. According to [Sankalp’s account of the experiment](https://sankalp.bearblog.dev/autoresearch/), Codex made more than 1,500 submissions over fourteen days. It wrote implementations, submitted them, read the timings, profiled bottlenecks, revised the code, preserved promising branches, and tried again. Some goal-directed runs continued for more than a day. The surrounding harness kept a log of accepted and rejected ideas so that later sessions would not have to rediscover the same failures. This was not quite a machine working in a hermetically sealed room. Sankalp supplied the original problem framing, learned enough of the mathematics to ask better questions, checked in every few hours during parts of the contest, and intervened when the search settled into local maxima. Near the end, those interventions mattered. Progress below roughly 3,000 microseconds required more conceptual steering, more profiling, and more deliberate variation among candidate strategies. That qualification does not diminish the result. It identifies what was actually invented. The breakthrough was not merely that a language model could write an unusually fast kernel. It was the construction of an environment in which an agent could conduct a sustained empirical search. The harness converted performance engineering into an operational loop: > propose, execute, verify, measure, diagnose, revise, and retain what was learned. Once that loop existed, the model’s capacity to generate code became only one component. The larger capability came from the relationship between a bounded problem, executable tools, quantitative feedback, persistent memory, and permission to continue. The lesson reaches far beyond CUDA. ## From code generation to project operation Most discussion about coding agents still concentrates on the artifact they produce. Can the model write the function? Can it repair the test? Can it generate a pull request? These are useful questions, but they preserve the mental model of an assistant waiting for a human to specify the next action. The kernel experiment suggests a different unit of automation. The unit is not a line of code or even a task. It is a closed learning process. Many forms of work can be expressed as a search through possible solutions. Software performance makes this obvious because runtime supplies a clean numerical score. Yet product design, editorial work, research, operations, and business development also involve candidates, constraints, observations, and selection. Their evaluators are messier, and some outcomes cannot be established without human participation, but the underlying structure remains recognizable. A user-interface agent can generate several interaction models, render each one, inspect browser states, test keyboard access, compare visual regressions, and preserve the strongest candidate. An editorial agent can draft competing structures, check every factual claim against sources, measure redundancy and reading complexity, conduct adversarial reviews, and revise the piece. An operational agent can propose a workflow, simulate load and failure conditions, inspect cycle time, identify bottlenecks, and test a revised process. A research agent can maintain competing hypotheses, gather evidence, record negative results, and direct the next experiment toward the most consequential uncertainty. In each case, the quality of the output depends on more than the model. It depends on whether the project has made success observable. This is where many agentic projects fail. They automate production before formalizing judgment. The agent can generate a great deal of material, but the system cannot distinguish progress from motion. A test suite can establish that software behaves according to its specification. It cannot establish that the specification serves the intended person. A visual similarity score can detect an accidental layout change. It cannot decide whether the original layout expressed the right hierarchy. A conversion metric can show that more people completed an action. It cannot, by itself, tell us whether the action was informed, manipulative, or valuable. The benchmark must therefore be larger than the artifact. ## Intent before tickets A project capable of autonomous iteration needs a governing layer above its backlog. It needs an explicit account of what the project is trying to cause, who or what it serves, which qualities must survive implementation, what evidence can support a success claim, and who has authority to change those definitions. Without this layer, the issue tracker quietly becomes the strategy. Agents optimize whatever has been rendered most legible: passing tests, closing tickets, reducing latency, increasing clicks, or satisfying the latest instruction. These objectives may be useful, but each is a proxy. Left ungoverned, a sufficiently persistent agent will discover the distance between the proxy and the purpose. A project engine begins by separating intent from work. Intent defines the durable boundary. Epics and issues decompose that intent into executable units. Each unit carries an objective, dependencies, acceptance criteria, evidence requirements, permissions, exclusions, budgets, and stop conditions. Documentation preserves institutional memory. Tickets represent current operational state. Evidence connects what was done to what may honestly be claimed. The operational agent then behaves less like an omniscient manager and more like a coordinator with constrained authority. It reconciles the project state, selects a Ready issue, checks dependencies, creates a time-bounded claim on the relevant workspace, assembles the minimum sufficient context, and dispatches a worker. Overlapping write claims are rejected. Read-only investigations can coexist. Expired claims cannot authorize further work. Every release remains in the execution history. This machinery may sound bureaucratic when applied to a single kernel. At project scale, it becomes the condition that makes autonomy safe enough to be useful. An agent cannot be permitted to reinterpret the project every time it encounters resistance. Nor can several agents be allowed to modify the same conceptual or technical territory without a visible ownership model. The system needs to know which decisions are local, which are reversible, and which require promotion authority. ## The evaluation contract Sankalp’s kernel loop worked because correctness and speed were both executable. A candidate that returned the wrong decomposition could not compensate with a faster runtime. Among candidates that satisfied the mathematical checker, the benchmark selected the faster implementation. Every autonomous project loop needs an equivalent evaluation contract, but the contract must match the domain. Software may require unit tests, integration tests, security checks, runtime measurements, and browser evidence. Interface work may add interaction-state coverage, accessibility checks, design-system conformance, visual inspection, and observed use. Editorial work may require source verification, structural review, legal or sensitivity review, and audience testing. Research may require reproducibility, provenance, uncertainty estimates, and independent evaluation. These forms of evidence are not interchangeable. A system should distinguish among work that is documented, implemented, tested, and empirically validated. A candidate may be fully implemented and pass every automated check while its effect on people remains unknown. Preserving that distinction is not ceremonial caution. It prevents synthetic evidence from laundering itself into a claim about the world. The evaluator also needs relative independence from the candidate generator. If the same agent can modify the artifact, rewrite the criteria, and approve promotion in one uninterrupted action, failure becomes negotiable. The loop may continue producing cleaner explanations for why its current output should count as success. Stable criteria, explicit authority, and retained evidence make that maneuver visible. ## Escaping the local maximum The most revealing portion of the kernel account arrives after the easy gains. Codex rapidly reduced the runtime, but later iterations began circling small variations of the same ideas. Sankalp responded by keeping a beam of several candidates alive, encouraging ambitious structural changes, consulting stronger advisor models, clearing stale context, and steering experiments toward bottlenecks revealed by multiple profilers. This is a general project problem. Optimization tends to improve what the current model of the problem can already see. The better the loop becomes at exploiting its known evaluation surface, the more likely it is to settle into a locally coherent answer whose hidden assumptions remain untouched. The remedy is deliberate epistemic stress testing. After a candidate qualifies against its known contract, the project freezes it. A separate evaluator then reveals a previously sealed change in conditions, a World Card, designed to test an assumption the candidate was not optimized to satisfy. A dependency may disappear. Available time may collapse. A different affected person may enter the analysis. Evidence may become contradictory. The original team may no longer be present. A system designed for one hundred records may have to account for one hundred million. Two legitimate intentions, such as privacy and personalization, may collide. These are designed perturbations rather than random disruptions. Each preserves the project’s protected invariants while changing a controlled part of the world around the candidate. The purpose is to ask a precise question: what must remain true for this result to remain good? The resulting disposition is more informative than a binary pass or fail. A candidate may be robust and continue to qualify unchanged. It may be adaptable through a bounded correction. It may remain valid only within a narrower domain. It may prove fragile under a plausible condition, unsafe because it crosses a protected invariant, or unknown because the available evaluation cannot support a conclusion. This method gives formal shape to an activity good teams already perform unevenly through criticism, pre-mortems, red teams, design reviews, and experienced intuition. By giving perturbations a budget, an owner, a reveal gate, and a retained result, the project can direct attention toward unknown variables instead of repeatedly demonstrating what it already knows. ## Memory is part of the machine An agentic loop without memory is condemned to perform intelligence as repetition. Sankalp’s `log.md` recorded which kernel ideas had succeeded, which had failed, and how each shape responded. As the search became harder, that record became more valuable. Later sessions could begin from accumulated evidence rather than from a polished summary that omitted the dead ends. At project scale, this memory needs several forms. Operational memory records current issues, claims, dependencies, and state transitions. Institutional memory records intent, architecture, design reasoning, policies, and decisions. Negative-result memory preserves failed experiments and the conditions under which they failed. An unknown-variable ledger records what is controlled, unresolved, assumed but untested, observed only once, discovered through perturbation, or currently unknowable. Together, these records change the economics of agent work. A new worker does not need every prior conversation. It needs a bounded context packet assembled from authoritative sources: the current issue, governing intent, relevant decisions, active constraints, known failures, required evidence, permissions, and stop conditions. The project, rather than the chat transcript, becomes the durable mind. ## The human role moves upward It is tempting to describe the kernel result as evidence that the human can be removed from the loop. The actual record supports a more useful conclusion. Human work moves from performing every iteration to designing and governing the system in which iteration occurs. Sankalp chose the problem, established the harness, learned the domain, shaped the instructions, inspected the evidence, introduced candidate diversity, and intervened when the search lost conceptual range. Codex supplied extraordinary persistence and implementation capacity inside that structure. Neither contribution is well described by the old division between a person who thinks and a tool that executes. For general projects, the human role increasingly concerns intent, taste, legitimacy, and consequence. People decide which outcomes deserve optimization, which tradeoffs are acceptable, which affected perspectives must be represented, what kinds of evidence count, and which actions require consent. Agents can manage much of the resulting operation, including decomposition, execution, measurement, documentation, and repeated experimentation. The strongest systems will make that division explicit instead of hiding it behind the language of assistance. This also clarifies where autonomy should stop. External publication, spending, irreversible deletion, legal commitments, communication in another person’s name, and claims about human outcomes may require specific authority. The coordinator should halt when evidence is missing, permissions are ambiguous, protected invariants are threatened, or the next action would create an unauthorized consequence. A stop is a valid project result, not an agent failure. ## The project becomes a learning instrument The 232x speedup matters because it demonstrates the amount of search that becomes practical when implementation, execution, and measurement are joined in a persistent loop. Its broader significance lies in the architecture around that search. Once a project can state its intent, represent work as contracts, coordinate bounded agents, evaluate candidates independently, introduce designed perturbations, preserve negative results, and promote only what its evidence supports, the project itself becomes an executable learning system. The loop improves more than the artifact. It improves the project’s model of its own reality. Each iteration can reveal a faster implementation, a clearer interface, a stronger argument, a safer workflow, or a better experiment. Just as importantly, it can reveal where the current answer stops working, which assumption was carrying more weight than anyone realized, and which question the existing evidence still cannot answer. That is the transferable idea behind the kernel result. The future of agentic work will not be secured by asking models to produce larger volumes of finished material. It will come from building projects that can tell the difference between an output, an improvement, and a justified decision. In that environment, the benchmark is no longer a final test attached to the work. The project is the benchmark. ## Origin and further reading - Sankalp, [“Auto-research with Codex: How I achieved a 232x Faster Kernel over baseline”](https://sankalp.bearblog.dev/autoresearch/), July 8, 2026. - Machuca Valley Tech, [“The 232x Leap: How AI is Solving the ‘Nuclear Waste’ of Coding”](https://www.machucavalley.tech/blog/auto-research-codex-gpu-kernel-optimization/), August 16, 2026. - RightNow AI, [AutoKernel](https://github.com/RightNow-AI/autokernel), an open-source autoresearch system for generating optimized Triton kernels from PyTorch models. --- FILE: docs/ADOPTION.md (111 lines, 4.9 KiB) --- # IEPE Adoption Guide ## Two-Stage Adoption Pattern IEPE adoption follows a strict two-stage sequence: **reconcile first, then apply**. Existing projects always begin in a read-only discovery and reconciliation phase before any file mutations or configuration changes are authorized. New projects may initialize directly once originating intent and protocol authority are supplied. Approved adoption plans are applied in Stage 2 under isolated mutation authority. ### Universal Adoption Inputs Every IEPE adoption requires these baseline inputs: ```yaml target_project: "" project_mode: new | existing iepe_source: "" iepe_revision: "" # Immutable tag, commit, or content digest project_intent: "" work_graph_provider: local | github | other mutation_authority: read-only | local-files | repository | external protected_actions: [] ``` The pinned IEPE revision must be an immutable tag, commit, or content digest. ## Adoption Modes IEPE supports two entry modes. Both produce the same governed operating model, but they begin from different evidence. | Mode | Starting condition | Stage 1 Responsibility | Stage 2 Responsibility | | --- | --- | --- | --- | | New project | Intent exists but implementation and work history may not | Validate intent & protocol pin; establish zero-state baseline | Direct initialization of governing layer and package compilation | | Existing project | Artifacts, tickets, and behavior already exist | Read-only discovery, intent reconstruction, work-graph reconciliation | Apply approved overlay without replacing existing valid local authority | The complete procedures, standard triggers, and reference commands are defined in [`INITIALIZATION.md`](INITIALIZATION.md). ## Minimum Adoption Steps 1. **Reconcile (Stage 1):** Perform read-only inventory, reconstruct authority order, and reconcile work graph. 2. **Apply (Stage 2):** - Pin versioned IEPE authority in `.iepe/protocol-reference.json`. - Add the IEPE block to controlling `AGENTS.md`. - Create `PROJECT_PROFILE.json` with workspace, evaluator, and protected-action configuration. - Configure `.agents/package-source.json` and `.agents/NEW_AGENT_PROMPT.md`. - Install narrow process skills under `.agents/skills/`. 3. **Operational Handoff:** Execute the first agent cycle (read-only reconciliation) before running the pilot issue. This is the minimum structural installation. A project does not enter autonomous operation until it has established a baseline, selected a bounded pilot, declared evidence requirements, and identified protected actions. ## Required project profile ```yaml project: id: "" protocol: protocolId: IEPE-001 protocolVersion: "" source: "" revision: "" intent_refs: [] authority_order: [] work_graph: provider: github | other project_refs: [] repositories_or_workspaces: [] coordinator: identity: "" capacity: 1 evaluators: [] protected_actions: [] promotion_authorities: [] memory: operational: "" institutional: "" ``` ## `AGENTS.md` adoption block ```markdown ## Intent and Evidence Project Engine This project operates under `IEPE-001` from the source and immutable revision recorded in `.iepe/protocol-reference.json`. Intent governs implementation. Canonical documentation defines authority. Issues authorize committed work. The project graph owns live status and native dependencies. The coordinator claims ready work, assembles bounded context, dispatches worker agents, and routes results through evaluation. Agents may explore within their granted environment but may not promote, publish, deploy, spend, communicate externally, or alter authoritative state without explicit authority. Preserve traceability: `intent -> epic -> issue -> artifact -> evidence -> qualification -> promotion` Continue while authority, context, ownership, dependencies, permissions, and evidence remain valid. Stop at unverified boundaries. ``` The upstream relationship and update procedure are defined in [`UPSTREAM_REFERENCE.md`](UPSTREAM_REFERENCE.md). ## Migration rule Do not convert every historical ticket immediately. Apply IEPE to new committed work and selected active epics. Promote durable historical conclusions into institutional memory only when their provenance can be established. The complete incremental migration procedure is defined in [`MIGRATION.md`](MIGRATION.md). Existing-project initialization begins with a read-only inventory. Discovery does not authorize the coordinator to rewrite documentation, close tickets, change project fields, or reinterpret undocumented behavior as governing intent. ## Pilot selection Choose a pilot that is meaningful, bounded, reversible, measurable, and representative of normal work. Avoid the most politically sensitive, financially consequential, or architecturally ambiguous project as the first validation case. The pilot must exercise one complete trace: ```text intent -> authorized issue -> claim -> context -> execution -> evaluation -> evidence -> disposition -> promotion ``` --- FILE: docs/AGENT_PROJECT_PACKAGE.md (78 lines, 3.8 KiB) --- # Agent Project Package ## Definition An Agent Project Package is a versioned, reproducible operating bundle compiled from a project's canonical sources. It gives coordinators and workers a governing contract, searchable context, installed procedures, provider adapters, provenance, and integrity metadata without making generated artifacts authoritative. ```text canonical sources -> package compiler -> operating contract -> context index -> compiled corpus -> skill and adapter inventory -> package manifest and digest ``` ## Authority boundary The package preserves this order: ```text canonical intent and doctrine -> ontology and formal contracts -> implementation sources -> generated package artifacts ``` Generated output is a projection. A contradiction is repaired in the canonical source and then recompiled. Generated context must never be edited to overrule its source. ## Package planes | Plane | Purpose | | --- | --- | | Governance | Compiled operating contract and authority order | | Context | Compact source index and selectively readable full corpus | | Procedure | Narrow skills with declared triggers and operating boundaries | | Adapter | Provider-specific translation for work graphs, repositories, deployments, or evidence systems | | Runtime | Coordinator configuration, worker roles, claims, and gates | | Integrity | Source versions, state, exclusions, hashes, and manifest | The manifest also binds the package to its upstream IEPE protocol source, version, and immutable revision. Identical local sources compiled under different protocol revisions are different operating packages even when their generated context bytes happen to match. Skills describe reusable procedures. Adapters translate provider operations. Project profiles bind both to project-specific vocabulary, identifiers, authority, and protected actions. A reusable skill must not require a particular repository name, board number, or product ontology. ## Required outputs - `AGENTS.md`: compiled or selected project operating contract - `context-index.md`: compact source-routing manifest - `context-full.md`: deterministic concatenation of selected sources - `agent-package-manifest.json`: package identity, provenance, inventories, outputs, exclusions, and payload digest - `.iepe/protocol-reference.json`: project-local pin to the governing IEPE source and revision Projects may add role prompts, scripts, schemas, and assets. Every included artifact must be declared in the manifest or traceable through a declared source. ## Compiler requirements The compiler must: - resolve paths beneath the declared project root - reject missing, absolute, or escaping paths - require one operating-contract source - retain explicit source roles and authority ranks - generate stable ordering - hash canonical inputs and generated outputs - retain the IEPE protocol identity, source, version, and revision - disclose clean, dirty, unknown, or provisional source state - reject release classification when source state is not clean - exclude machine metadata, bytecode, caches, secrets, and undeclared files - avoid timestamps or nondeterministic values unless supplied as versioned input - produce byte-identical output for identical declared input ## Context use Workers consult the compact index first. The full corpus is a searchable source, not routine prompt payload. The coordinator assembles a bounded context packet from the package according to the claimed issue, authority references, dependencies, evidence requirements, and stop conditions. ## Maturity A conforming package proves that declared sources were compiled reproducibly. It does not prove that the sources are correct, the skills are effective, the adapters are operational, or project outcomes are empirically valid. Those remain separate evidence claims. --- FILE: docs/COORDINATOR.md (148 lines, 4.7 KiB) --- # Operational Coordinator Specification ## Role The coordinator is a persistent project-management agent. It connects authority, work state, worker execution, evaluation, and project memory. It does not become the source of truth for those systems. ## State machine ```text PREFLIGHT (Capabilities & Environment Probe) -> RECONCILE -> SELECT -> VALIDATE -> CLAIM -> ASSEMBLE_CONTEXT -> DISPATCH -> OBSERVE -> EVALUATE -> DISPOSITION -> RECORD -> CLOSE_LOOP -> WAITING_EXTERNAL (Parked on Non-Retryable Blocker) ``` Any state may transition to `STOPPED` when an unrecoverable stop condition occurs, or `WAITING_EXTERNAL` when an external capability or authorization condition is pending. ## Preflight Execution Sequence Environment capabilities must be tested **before** discovery or preparation: ```text resolve project -> inspect instructions -> test required capabilities (e.g. write-probe) -> perform discovery -> prepare changes -> mutate ``` ### Preflight Verify environment capabilities (e.g. testing workspace write capability using a temporary probe file before constructing overlays), providers, credentials, tools, repository identity, project identity, context version, capacity, and resource limits. If required environment capabilities are missing (e.g. `CAPABILITY_MISSING`), emit a single `ENV_WORKSPACE_READ_ONLY` blocker and transition to `WAITING_EXTERNAL` without preparing mutations or retrying. ### Blocker Deduplication Rule If the current blocker fingerprint (`code:scope`) matches a previous non-retryable blocker: - Do not retry - Do not reread the objective - Do not consume attempts - Enter `WAITING_EXTERNAL` - Return control to user ### Reconcile Compare canonical documentation, project state, native relationships, active claims, implementation state, review artifacts, deployments, and evidence. ### Select Choose ready work using dependencies, milestone sequence, priority, capacity, risk, and expected information gain. ### Validate Validate the issue against the issue-contract schema and project-specific readiness policy. ### Claim Create one attributable, bounded claim. Enforce capacity and conflict limits. ### Assemble context Retrieve the minimum sufficient authority, history, baseline, constraints, and task evidence. Record context identity. ### Dispatch Select the worker role, environment, tools, permissions, budget, and return contract. ### Observe Monitor evidence, cost, iterations, regressions, and stop conditions. Avoid interrupting merely because progress is not immediately visible. ### Evaluate Run declared deterministic, agentic, expert, participant, or field evaluators. Preserve each result independently. ### Disposition Choose reject, retain, retry, revise, escalate, or prepare promotion. The coordinator may not fabricate a passing state when an evaluator is unavailable. ### Record Attach artifacts, evidence, limitations, negative results, costs, and lineage to the issue and experiment graph. ### Close loop Update authorized status, release claims, refresh projections, and propose institutional-memory updates. ## Stop states - missing or conflicting authority - stale context - ambiguous ownership - incomplete issue contract - unresolved dependency - invalid credentials or provider health - unexpected external side effect - exceeded permission or budget - unavailable required evaluator - unsupported status transition - unauthorized architecture change - irreversible action without explicit authority Stopping creates a structured blocker record with evidence and the authority required to resume. ## Receipt persistence and replay Terminal completed and stopped executions produce a versioned receipt envelope. The reference implementation serializes the receipt deterministically, retains typed assertion provenance and state history, and protects the payload with a SHA-256 digest. Replay validates: - receipt format and version - payload integrity - continuous and permitted transitions - terminal final state - required typed assertions - assertion subject, validity, issuer, and evidence references - complete stop records for stopped executions The digest is an integrity mechanism, not an identity signature. Projects requiring attested authorship must add a signing and trust adapter without weakening replay validation. ## Conversation adapter In a conversational interface, the coordinator maintains: ```yaml intent: "" mode: explore | define | plan | execute | evaluate desired_outcome: "" constraints: [] accepted_decisions: [] open_questions: [] active_work: [] evidence: [] blockers: [] authority_granted: [] next_action: "" ``` The state is shown when it improves understanding or when the user asks. It should not make ordinary conversation feel like project-board administration. --- FILE: docs/EPISTEMIC_STRESS_TESTING.md (86 lines, 3.4 KiB) --- # Epistemic Stress Testing ## Definition Epistemic stress testing uses **designed perturbations** to reveal assumptions, unknown variables, brittle dependencies, absent perspectives, and validity boundaries that ordinary optimization may not expose. The operating question is: > What must remain true for this result to remain good? ## Blind Counterfactual Trial After a candidate qualifies against its known evaluation contract, it is frozen. A sealed World Card is then revealed and the frozen candidate is evaluated under the changed conditions. ```text Known contract -> Candidate development -> Known evaluation -> Candidate freeze -> World Card reveal -> Counterfactual trial -> Robustness disposition -> Promotion decision ``` The candidate-producing worker must not see the World Card before the freeze gate. ## Protected invariants Perturbations may change context, constraints, evidence availability, actor perspective, time, dependency behavior, or scale. They may not silently remove: - governing project intent - safety and human-rights constraints - consent requirements - factual standards - identity boundaries - promotion authority ## Perturbation families | Family | Example | | --- | --- | | Context | different environment, audience condition, language, or interaction mode | | Constraint | reduced time, budget, tools, connectivity, or provider access | | Evidence | conflicting sources, delayed telemetry, missing provenance, invalid evaluator | | Actor | maintainer, purchaser, regulator, child, critic, or affected non-user | | Time | accumulated state, future dependency, absent original team, emergency repair | | Dependency | unavailable provider, read-only service, degraded integration | | Scale | one versus millions, local exception versus global process | | Intent collision | privacy with personalization, simplicity with expert control, speed with auditability | ## Surprise budget Projects reserve evaluation capacity for conditions hidden during candidate development. A project profile may define a percentage, minimum World Card count, required candidate visibility, and promotion classes that require stress testing. A starting reference profile is fifteen percent of evaluation capacity and at least two sealed World Cards before architecture freeze, production promotion, or an empirical-validation claim. ## Robustness dispositions | Disposition | Meaning | | --- | --- | | Robust | Candidate remains qualified without adaptation | | Adaptable | An authorized bounded adjustment restores qualification | | Bounded | Candidate remains valid only within a narrower declared domain | | Fragile | Candidate fails under a plausible changed condition | | Unsafe | Candidate crosses a protected invariant | | Unknown | Available evaluation cannot establish the result | A bounded result can remain useful. Stress testing should reveal validity conditions rather than demanding universal robustness. ## Unknown-variable ledger Unknowns are classified as: - known and controlled - known but unresolved - assumed but untested - observed only once - discovered through perturbation - currently unknowable The ledger guides future World Card selection toward neglected uncertainty classes. ## Authority The Perturbation Steward creates or selects World Cards independently from candidate authorship where practical. The steward does not redefine intent, approve promotion, or waive protected invariants. --- FILE: docs/INITIALIZATION.md (457 lines, 18.4 KiB) --- # Project Initialization Protocol ## Purpose This protocol installs IEPE as an operating layer for a new or existing project. It does not prescribe product architecture. The stable engine supplies coordination, claims, evidence, perturbation, promotion, and memory contracts. A project profile supplies domain-specific intent, authority, workspaces, evaluators, and protected actions. The installation references an immutable IEPE Core revision through `.iepe/protocol-reference.json`. See [`UPSTREAM_REFERENCE.md`](UPSTREAM_REFERENCE.md) for the authority and update boundary. ## Two-Stage Trigger Pattern IEPE adoption follows a two-stage pattern: **reconcile first, then apply**. Existing projects always begin in a read-only discovery and reconciliation stage before mutation authority is granted. New projects may initialize directly once originating intent and authority are supplied. Approved adoptions are applied in Stage 2 under explicit mutation authority. ### Universal Inputs Every IEPE adoption requires: ```yaml target_project: "" project_mode: new | existing iepe_source: "" iepe_revision: "" # Immutable tag, commit, or content digest project_intent: "" work_graph_provider: local | github | other mutation_authority: read-only | local-files | repository | external protected_actions: [] ``` The IEPE revision must be an immutable tag, commit, or content digest. A moving branch such as `main` is suitable only for provisional development. ### Repository Arrangement ```text workspace/ ├── IEPE-Core/ └── target-project/ ``` The target project references the pinned IEPE source. It does not redefine IEPE's claim, evidence, promotion, or stop semantics. Both initialization modes converge on the same operational condition: - governing intent is explicit - authority order is defined - work is represented as a dependency graph - the current baseline is recorded - claims can bound concurrent work - evidence requirements match the domain - protected actions require named authority - unknown variables and negative results are retained - one bounded issue is Ready for a complete coordinator cycle ## Mode A: New project ### A1. Capture the originating conversation The initializer separates statements into: | Class | Meaning | | --- | --- | | Intent | Outcome the project exists to cause | | Established decision | Choice already made by an authorized person | | Requirement | Condition the project must satisfy | | Preference | Desired quality that may permit tradeoffs | | Hypothesis | Testable explanation or proposed approach | | Constraint | Boundary on implementation or operation | | Exclusion | Work or outcome intentionally outside scope | | Unknown | Material variable not yet established | Conversation is input evidence, not automatic authority. The initializer presents inferred intent and consequential assumptions for correction before committing them to the governing layer. ### A2. Create the governing foundation A new project should begin with this minimum structure or an equivalent mapping: ```text project/ ├── AGENTS.md ├── INTENT.md ├── PROJECT_PROFILE.json ├── ROADMAP.md ├── .iepe/ │ └── protocol-reference.json ├── .agents/ │ ├── NEW_AGENT_PROMPT.md │ ├── package-source.json │ └── runtime/COORDINATOR.md ├── docs/ │ ├── EXPERIENCE.md │ ├── ARCHITECTURE.md │ ├── DECISIONS/ │ ├── RESEARCH/ │ └── NEGATIVE_RESULTS/ ├── evidence/ ├── experiments/ └── work/ ``` `INTENT.md` governs purpose, beneficiaries, protected qualities, exclusions, and success evidence. `PROJECT_PROFILE.json` binds the project to workspaces, work graphs, coordinator capacity, evaluators, protected actions, promotion authorities, and memory locations. `AGENTS.md` defines local operating instructions and validation commands. `ROADMAP.md` defines milestones through exit evidence rather than feature inventories. ### A3. Record the zero-state baseline The absence of implementation is valid evidence. Record what exists, what does not, what has been decided, what is proposed, and what remains unvalidated. Do not use a polished project description as evidence that demand, feasibility, usability, or outcomes have been established. ### A4. Define the first measurable milestone The milestone states an observable project capability and the evidence required to exit. Its issues form a dependency graph rather than an undifferentiated backlog. The first milestone should include: - an intent or experience contract - the smallest useful artifact or operational result - domain-appropriate evaluation - a reversible promotion decision - at least one material unknown scheduled for investigation ### A5. Select the first Ready issue Choose a bounded issue with one clear workspace, available dependencies, explicit permissions, reproducible evaluation, and a recovery path. The issue becomes the first end-to-end test of the project engine, not merely the first production task. ## Mode B: Existing project ### B1. Perform read-only discovery Inventory the project before changing it: - repositories and workspace structure - controlling agent instructions - documentation and architectural decisions - Git history, active branches, and releases - open and closed work items - project-board fields and dependencies - builds, tests, and validation commands - deployment configuration - design assets and experience documentation - available analytics, observations, and operational evidence Discovery does not authorize mutation. ### B2. Reconstruct intent with provenance Every proposed governing statement receives a provenance class: | Class | Treatment | | --- | --- | | Established | Explicit in a governing source | | Inferred | Repeated pattern or converging evidence | | Proposed | Future behavior described but not approved | | Observed | Current behavior without governing authority | | Unresolved | Unsupported or contradictory | Current implementation is evidence of behavior, not automatic evidence of intent. The owner or named authority approves the reconstructed intent before the coordinator uses it to reject or promote work. ### B3. Reconcile the work graph Classify existing work as active, blocked, superseded, completed but unverified, abandoned, duplicate, missing evidence, misaligned, or requiring review. Preserve original identifiers and provenance. Do not rewrite history to create artificial consistency. ### B4. Establish the operational baseline Run authorized diagnostics and record their environment, results, and limitations. Depending on the project, this may include builds, tests, type checks, browser flows, accessibility, performance, schema validation, documentation integrity, deployment inspection, or security analysis. Existing failures become baseline facts. They block adoption only when they prevent safe execution or invalidate the selected pilot. ### B5. Select a bounded intervention Choose a reversible, representative change that can exercise the full IEPE trace without requiring broad architectural repair or an unauthorized external consequence. Reconcile and automate the rest of the backlog incrementally after the pilot qualifies. ## Conversational initialization A person may initialize a project in natural language. The conversation is processed into a provisional package containing: - interpreted intent - intended beneficiaries and experience - constraints and exclusions - established decisions - risky assumptions - initial unknown-variable ledger - authority questions - proposed project profile - first milestone and work graph - evaluation and perturbation plan - permissions and stop conditions - first Ready issue The initializer must distinguish user statements from its own inferences. It requests confirmation only for ambiguities that would materially alter intent, authority, external consequences, or irreversible work. Example entry: ```text Start a new IEPE project for a browser-based aerodynamics visualization. It should help students understand how wing shape affects lift and drag. ``` The resulting profile might establish an educational purpose, require physically plausible behavior, exclude engineering certification, identify model fidelity as an unknown, and require separate evidence for technical correctness and student understanding. ## Project profile boundary The project profile makes the engine portable. It supplies project-specific configuration without changing core coordination semantics. Software profiles commonly add build, test, browser, deployment, code-ownership, and security evaluators. Editorial profiles add source, fact-checking, voice, legal-review, and publication requirements. Research profiles add hypotheses, datasets, reproducibility, provenance, statistical evaluation, and uncertainty. Design profiles add experience contracts, states, responsive conditions, accessibility, visual evidence, and human observation. Operational profiles add process owners, service levels, cost limits, approval chains, audit records, and affected parties. Domain profiles may extend evaluation and adapters. They may not silently replace project intent, claim semantics, evidence maturity, protected actions, or promotion authority. ## Initialization gates Initialization completes only when: 1. Intent and authority are explicit enough to govern the pilot. 2. The project profile conforms to the declared schema (or declares `"profileStatus": "provisional"` if promotion authority is unassigned). 3. The baseline records known failures and evidence gaps. 4. Work-graph relationships required by the pilot are reconciled. 5. Evaluators and evidence maturity are declared. 6. Protected actions and promotion authorities are named (or declared `"unassigned"` for provisional local initialization). 7. The unknown-variable ledger contains material assumptions. 8. A bounded, reversible issue is Ready. ### Preflight Workspace Capability Probe Before performing discovery or constructing an overlay, the initializer MUST run a single workspace write probe: 1. Test write capability by writing a temporary probe file (e.g. `.iepe-write-test`) inside the authorized workspace. 2. Remove or quarantine the probe immediately. 3. If writes succeed, proceed to discovery and overlay generation. 4. If writes fail (`CAPABILITY_MISSING`), stop ONCE with `ENV_WORKSPACE_READ_ONLY`, do not prepare full overlays, do not retry, and enter `WAITING_EXTERNAL`. ### Provisional Profiles & Promotion Decoupling Local initialization requires only local reversible action authorization. An unassigned promotion authority generates a provisional profile: ```json { "promotionAuthority": "unassigned", "profileStatus": "provisional", "promotionBlocked": true } ``` This permits creation of `AGENTS.md`, `PROJECT_PROFILE.json`, and `.iepe/protocol-reference.json` while blocking milestone promotion until a named authority is assigned. ### Compile the Agent Project Package After the initialization gates pass, compile the canonical sources into the Agent Project Package defined in [`AGENT_PROJECT_PACKAGE.md`](AGENT_PROJECT_PACKAGE.md). Validate its manifest and integrity before the coordinator uses it to assemble worker context. ## Operational handoff After initialization, the normal loop begins: ```text reconcile -> select Ready issue -> validate authority and dependencies -> claim scope -> assemble bounded context -> dispatch -> observe -> evaluate -> stress test when required -> record evidence -> disposition and promotion -> release claim -> select again ``` The coordinator continues until the milestone qualifies, the budget expires, evidence becomes unavailable, authority becomes ambiguous, a protected action is reached, or another declared stop condition occurs. ## Standard Triggers and Reference Commands For the full single-file agent cheat-sheet and copy-paste prompt block, see [`REFERENCE.md`](REFERENCE.md). ### Trigger for an Existing Project (Stage 1: Reconcile) Start the agent inside the target repository: ```text Adopt IEPE for this existing project. Target: Pinned IEPE source: Pinned IEPE revision: Use and strictly follow: /AGENTS.md /.agents/skills/initialize-iepe-project/SKILL.md /docs/INITIALIZATION.md /docs/UPSTREAM_REFERENCE.md /docs/MIGRATION.md Mode: existing project. Authority: read-only discovery and reconciliation. First cycle: 1. Read every applicable AGENTS.md, CLAUDE.md, and nested agent instruction. 2. Inspect repository identity, branches, workspaces, packages, documentation, architecture, decisions, tests, releases, deployments, issues, pull requests, and project boards. 3. Run IEPE existing-project discovery. 4. Reconstruct intent using these provenance classes: established, inferred, proposed, observed, and unresolved. 5. Identify the authority order for intent, terminology, experience, architecture, schemas, implementation, operations, and generated artifacts. 6. Reconcile the work graph, dependencies, claims, implementation state, reviews, releases, deployments, and evidence. 7. Identify contradictions, stale work, incomplete issue contracts, unsupported maturity, missing evidence, protected actions, and material unknowns. 8. Propose the project-specific IEPE profile. 9. Propose how IEPE should integrate with existing agent instructions without replacing valid local authority. 10. Select one bounded and reversible pilot issue. Do not modify files, create or change work items, alter project fields, push, merge, deploy, publish, spend, or communicate externally. Return: - discovery report - authority and provenance map - project baseline - proposed PROJECT_PROFILE.json - proposed protocol reference - proposed AGENTS.md integration - work-graph reconciliation - unknown-variable ledger - protected-action list - proposed overlay file map - first candidate pilot issue - blockers and decisions requiring human authority ``` The discovery command is: ```bash python3 /tools/init_project.py existing \ --project-root ``` To save the report without changing the project: ```bash python3 /tools/init_project.py existing \ --project-root \ --report /iepe-discovery.json ``` ### Trigger for a New Project A new project may initialize directly after its originating intent and protocol reference are supplied: ```text Initialize a new project under IEPE. Project root: Project ID: Project name: Originating intent: Pinned IEPE source: Pinned IEPE revision: Work-graph provider: Evaluator candidates: Promotion authority: Use: /.agents/skills/initialize-iepe-project/SKILL.md /docs/INITIALIZATION.md /docs/UPSTREAM_REFERENCE.md Initialize the project without claiming that beneficiaries, architecture, implementation, demand, usability, or outcomes are established. After initialization: 1. Validate the protocol reference and project profile. 2. Record the zero-state baseline. 3. Separate established decisions from agent inference. 4. Identify protected qualities and protected actions. 5. Create the initial unknown-variable ledger. 6. Define the first milestone through exit evidence. 7. Propose one bounded, reversible Ready issue. 8. Compile the Agent Project Package. 9. Return the generated files, validation evidence, unresolved authority, and first-agent prompt. Do not deploy, publish, spend, create external resources, or communicate externally. ``` The corresponding command is: ```bash python3 /tools/init_project.py new \ --project-root \ --project-id \ --project-name "" \ --intent "" \ --protocol-source "" \ --protocol-revision "" \ --work-graph-provider \ --project-ref \ --evaluator \ --promotion-authority ``` ### Trigger to Apply an Approved Existing-Project Adoption (Stage 2: Apply) After reviewing the reconciliation report and approving the adoption plan: ```text Apply the approved IEPE adoption plan. Target: Approved reconciliation: Mutation authority: local repository files on an isolated branch Preserve all existing project authority and unrelated changes. Integrate with existing agent instructions instead of replacing them. Create or update only the approved IEPE operating layer: - .iepe/protocol-reference.json - AGENTS.md - PROJECT_PROFILE.json - .agents/package-source.json - .agents/NEW_AGENT_PROMPT.md - .agents/runtime/COORDINATOR.md - .agents/skills/* - approved authority and memory documents - approved work-graph configuration Configure evaluators from actual project commands and evidence. Do not invent tests, providers, deployment targets, issue relationships, or authority. Compile the Agent Project Package and run IEPE plus project-native validation. Do not push, merge, deploy, publish, modify live work items, or communicate externally. Return: - complete diff - validation evidence - package manifest - unresolved evidence gaps - limitations - proposed pilot issue - next action requiring authorization ``` ### Trigger for the First Operational Agent Once the project overlay is installed: ```text Operate this project under its pinned IEPE protocol reference. Follow AGENTS.md, PROJECT_PROFILE.json, and the narrowest applicable skill under .agents/skills. Your first cycle is read-only reconciliation. Verify project identity, protocol revision, authority, work graph, dependencies, claims, evaluators, protected actions, and evidence. Return a typed reconciliation result and the first candidate Ready issue. Do not claim or implement work until the project is internally consistent and the issue contract is complete. ``` After that first cycle, the normal IEPE operational loop begins: ```text reconcile -> select -> validate -> claim -> assemble bounded context -> dispatch -> observe -> evaluate -> stress test when required -> record evidence -> disposition -> release claim -> repeat ``` This universal trigger pattern applies across software, research, writing, design, operations, physical production, and mixed-domain projects. Only the local project profile, adapters, evaluators, protected actions, and authority sources change. --- FILE: docs/MIGRATION.md (92 lines, 3.5 KiB) --- # Incremental Adoption and Migration Protocol ## Purpose This protocol brings an established project under IEPE without rewriting history, disrupting active delivery, or converting unsupported legacy claims into evidence maturity. ## Migration classes Every legacy item is placed into one of three classes. | Class | Meaning | Required treatment | | --- | --- | --- | | Historical | Closed or dormant work not required for current authority, dependency, or evidence | Preserve identity and source status; do not enrich by default | | Active | Work currently claimed, under review, blocked, or required by an active dependency | Reconcile intent, ownership, relationships, acceptance, evidence, permissions, and status | | New | Work committed after the adoption boundary | Require the complete IEPE issue contract before execution | Migration is demand-driven. Historical records are reconciled only when they become relevant to authority, dependency, incident analysis, promotion, or evidence. ## Adoption boundary The project records one adoption boundary containing: - effective time or project revision - governing protocol version - project profile - coordinator identity - provider and work-graph identity - migration owner - protected actions - rollback condition Items created after this boundary follow IEPE. Earlier items retain their original identity and status semantics. ## Reconciliation packet An active legacy item cannot become `Ready` until the migration process resolves: - governing intent or an explicit unresolved-intent blocker - owning project, repository, or workspace - native parent and dependency relationships - current actor or claim - acceptance criteria - evidence already present - evidence still required - side-effect permissions - stop conditions - mapping between source status and IEPE workflow status - claim maturity supported by existing evidence Missing provenance is recorded as missing. It is never reconstructed from confidence or status labels. ## Status mapping Source status and IEPE status are separate fields. A migration adapter may recommend a target workflow state, but it must retain the source value and mapping rationale. Examples: | Source condition | IEPE recommendation | | --- | --- | | Open with complete contract and no blocker | Ready | | Open with active claim | In progress after claim reconciliation | | Pull request awaiting review | In review when the PR relationship is proven | | Closed with merged artifact | Done only when repository gates are proven | | Deployed and observed | Verified only when required observation evidence is retained | | Closed without evidence | Historical source status retained; claim maturity remains unresolved | ## Migration sequence ```text Inventory -> Classify -> Preserve source identity -> Reconcile active work -> Validate new-work gate -> Audit relationships -> Record evidence gaps -> Pilot one vertical slice -> Activate adoption boundary ``` ## Rollback Migration adds IEPE metadata and relationships without deleting source identity. If the adoption fails, stop coordinator claims, preserve migration records, restore the previous operational workflow, and retain the failure as a negative result. ## Stop conditions - provider-native identity or relationships would be destroyed - a field mapping changes the meaning of source status - the owning workspace cannot be established - provenance required for a promotion claim is absent - automation would advance or close work without evidence - the coordinator cannot distinguish historical from active work --- FILE: docs/NEGATIVE_RESULTS.md (28 lines, 2.3 KiB) --- # Retained Negative Results and Incident Records > Governing Protocol: [`PROTOCOL.md`](PROTOCOL.md#condition-classification-taxonomy) > Retained Memory: Institutional Memory & Regression Fixtures --- ## Incident IEPE-INCIDENT-001: SES Governance Livelock ### Context & Description During initial adoption of the Semantic Expression System (SES) project under IEPE, an operational agent entered an indefinite governance livelock. The agent remained active across multiple attempts but could not advance state because: 1. Read-only discovery became an indefinite mode rather than a bounded first phase. 2. Initialization was coupled to named promotion authority (`promotionAuthorities`), blocking provisional local file creation. 3. User authorization and environment capability were conflated (user authorized work, but filesystem environment was read-only). 4. The coordinator lacked blocker deduplication, repeatedly discovering the same non-retryable blocker (`ENV_WORKSPACE_READ_ONLY`) and retrying without state change. ### Disproven Hypotheses - **Hypothesis 1:** Prompting an agent with expanded user authorization can resolve a physical filesystem capability restriction (`CAPABILITY_MISSING`). *Disposition:* Disproven. Environment capability checks MUST precede discovery/planning and fail fast (`ENV_WORKSPACE_READ_ONLY`). - **Hypothesis 2:** Promotion authority is required to initialize a local, reversible project operating layer. *Disposition:* Disproven. Initialization authority and promotion authority are separate. Unassigned promotion authority yields `"profileStatus": "provisional"`. - **Hypothesis 3:** Retrying a non-retryable blocker after re-reading the prompt will yield progress. *Disposition:* Disproven. Non-retryable blockers MUST be fingerprinted (`code:scope`) and immediately transition the coordinator to `WAITING_EXTERNAL`. ### Protocol Invariants Established - **Preflight Capability Probing:** Environment capability probes (e.g. workspace write test) must execute before discovery and preparation. - **Condition Classification Taxonomy:** Distinguishes `AUTHORIZATION_MISSING`, `CAPABILITY_MISSING`, `EVIDENCE_MISSING`, `INPUT_MISSING`, `WORK_UNAVAILABLE`, and `EXTERNAL_EVENT_PENDING`. - **Blocker Fingerprint Deduplication:** `code:scope` fingerprints halt retries immediately and transition the coordinator to `WAITING_EXTERNAL`. --- FILE: docs/PROTOCOL.md (199 lines, 7.0 KiB) --- # Intent and Evidence Project Engine Protocol > Protocol: `IEPE-001` > Version: `0.2.0` > Status: Draft reference protocol > Scope: Domain-neutral ## Definition IEPE is a governed process that converts project intent into authorized work, generates or implements candidate interventions, evaluates results against declared evidence, preserves learning, and promotes only qualified outcomes. ## Constitutional invariants 1. Intent governs implementation. 2. Canonical documentation defines project authority. 3. Tickets authorize committed work. 4. The project graph owns live status and dependencies. 5. Coordination, execution, evaluation, and promotion are distinct responsibilities. 6. Evidence qualifies claims. 7. Exploration authority may exceed promotion authority. 8. Negative results become project memory. 9. Metrics may inform intent but may not silently replace it. 10. Invalid authority, context, ownership, permissions, or evidence is a stop state. 11. Environmental capability checks must precede discovery and preparation. 12. Non-retryable blockers must fingerprint, emit once, and enter a parked state (`WAITING_EXTERNAL`) to prevent livelocks. ## Engine planes | Plane | Responsibility | | --- | --- | | Intent and Authority | Purpose, values, doctrine, terminology, constraints, decisions | | Experience and Design | Human outcomes, journeys, interactions, accessibility, design system | | Coordination | Work graph, dependencies, claims, budgets, scheduling, dispatch | | Execution | Research, design, implementation, testing, and bounded operations | | Evaluation and Evidence | Verification, observation, comparison, qualification, lineage | ## Condition classification taxonomy The coordinator distinguishes unresolved conditions into six explicit types: | Condition | Meaning | Coordinator Response | | --- | --- | --- | | `AUTHORIZATION_MISSING` | User has not permitted the action | Ask one precise question | | `CAPABILITY_MISSING` | Environment cannot perform the action | Stop once; identify the required capability | | `EVIDENCE_MISSING` | Promotion cannot yet be justified | Continue allowed preparation; block only promotion | | `INPUT_MISSING` | Consequential project decision is unresolved | Use provisional value or ask if execution materially depends on it | | `WORK_UNAVAILABLE` | Nothing actionable is Ready | Park the loop | | `EXTERNAL_EVENT_PENDING` | Only another actor can change state | Enter `WAITING_EXTERNAL`; do not retry | ## Authority boundaries and implicit defaults ### Initialization vs. Promotion Authority Creating local, reversible project-operating files (e.g. `AGENTS.md`, `PROJECT_PROFILE.json`, `.iepe/protocol-reference.json`) requires only local reversible authorization. Unassigned promotion authority yields: ```json { "promotionAuthority": "unassigned", "profileStatus": "provisional", "promotionBlocked": true } ``` It must not prevent creation of local operating documentation or initial work contracts. ### Implicit Action Authorization When a user requests project initialization or local adoption, the implicit authorization defaults are: - `read_project`: allowed - `write_local_iepe_files`: allowed - `run_local_validation`: allowed - `create_external_work_items`: not_allowed - `push_or_merge`: not_allowed - `deploy_or_publish`: not_allowed - `spend_or_change_credentials`: not_allowed ### Hard-blocker fingerprinting Every blocker receives a stable fingerprint: ```json { "code": "ENV_WORKSPACE_READ_ONLY", "scope": "target-project", "requiredChange": "workspace-write capability", "retryableByAgent": false, "fingerprint": "ENV_WORKSPACE_READ_ONLY:target-project" } ``` If the current blocker fingerprint matches the previous non-retryable blocker, the coordinator MUST NOT retry, reread the objective, or consume additional attempts. It immediately enters `WAITING_EXTERNAL` and returns control to the user. ## Canonical objects Projects may extend these objects but should preserve their meanings: - `ProjectIntent` - `ExperienceContract` - `DesignDecision` - `PortfolioObjective` - `Milestone` - `Epic` - `IssueContract` - `Experiment` - `Candidate` - `Baseline` - `Evaluation` - `EvidenceBundle` - `Qualification` - `Promotion` - `NegativeResult` ## Work modes ### Delivery Use when the desired change is understood. ```text Ready -> Claimed -> Implemented -> Reviewed -> Done -> Verified ``` ### Improvement Use when the outcome is understood but the best intervention is uncertain. ```text Baseline -> Hypotheses -> Candidate beam -> Evaluation -> Promotion decision ``` ### Conversation Use when the project is operated through a conversational coordinator. ```text Explore -> Define -> Plan -> Execute -> Evaluate ``` Conversation modes may recur. The coordinator maintains intent and work state beneath a natural interface. ## Issue readiness An issue is ready only when it defines: - governing intent - objective or hypothesis - ownership and parent relationship - dependencies - acceptance criteria - evidence requirements - affected experience or design contracts - constraints and exclusions - permissions and side effects - budget - stop and escalation conditions ## Worker contract A worker receives a bounded packet containing the issue, authority references, scope, constraints, acceptance, evidence, permissions, budget, stop conditions, and return requirements. A worker returns artifacts, evidence, limitations, blockers, cost where material, and a recommended next action. It does not accept or promote its own work unless the project explicitly permits that low-risk operation. ## Evaluation Evaluation uses a visible vector rather than hiding material tradeoffs in one score. Applicable dimensions may include: - correctness - intent alignment - human effectiveness - accessibility - quality - performance - cost - risk - maintainability - portability - trust - uncertainty Human evidence is required before claims about comprehension, lived usefulness, emotional quality, cultural interpretation, trust, or delight become empirically validated. ## Promotion Promotion is separate from evaluation. It requires valid authority, complete lineage, required checks, independent assessment where specified, visible tradeoffs, recovery planning where applicable, and a retained decision record. ## Epistemic stress testing Qualified candidates may require designed perturbations before promotion. A candidate is frozen before sealed World Cards are revealed. Resulting robustness dispositions and unknown-variable discoveries inform, constrain, revise, block, or escalate promotion without silently changing governing intent. See [`EPISTEMIC_STRESS_TESTING.md`](EPISTEMIC_STRESS_TESTING.md). ## Memory Operational memory retains issues, runs, candidates, evidence, and incidents. Institutional memory retains approved doctrine, specifications, decisions, design systems, standards, and rejected directions. Generated context is a downstream projection of canonical sources. ## Protocol expression > Define intent. Authorize through tickets. Explore within bounds. Evaluate independently. Promote through evidence. Preserve what the project learns. --- FILE: docs/REFERENCE.md (166 lines, 5.0 KiB) --- # IEPE Single Agent Reference & Operational Sheet > Protocol: `IEPE-001` > Version: `v0.2.0` > Purpose: Universal single-file reference for human developers and autonomous AI agents. --- ## ⚡ The Single Agentic Adoption Command Copy and paste this single command block into any AI agent chat interface (Cursor, Antigravity, Claude, ChatGPT, Windsurf, Devin) to adopt IEPE on any project: ```text Adopt IEPE for this repository. Target: ./ Pinned IEPE source: https://github.com/zachshallbetter/IEPE (v0.2.0) Project Intent: "" Project Mode: existing | new Mutation Authority: local-files Execution sequence: 1. Preflight: Run workspace write capability probe once. 2. Reconcile: Perform read-only discovery of intent, files, and authority order. 3. Apply: Generate AGENTS.md, PROJECT_PROFILE.json, and .iepe/protocol-reference.json. 4. Validate: Run iepe-validate or python3 tools/validate.py. ``` --- ## 🏛️ Authority Hierarchy Resolve authority conflicts in strict canonical order: ```text 1. docs/PROTOCOL.md (Governing Protocol) 2. Approved Decision Records (docs/DECISIONS.md) 3. JSON Schemas (schemas/*.schema.json) 4. Coordinator & Adoption Specifications (docs/COORDINATOR.md, docs/ADOPTION.md) 5. Issue Contracts & Acceptance Criteria (work/*.md) 6. Implemented Substrate Code & Templates (iepe_core/, tools/) 7. Generated Artifacts & Agent Outputs ``` --- ## 🔗 The Governing Chain Every material project change must preserve complete provenance: ```text intent -> epic -> issue -> artifact -> evidence -> qualification -> promotion ``` --- ## 📊 Status Honesty & Maturity Taxonomy Never conflate maturity levels. Always state the weaker claim when in doubt: ```text Backlog -> Ready -> In progress -> In review -> Done -> Verified Documented != Implemented != Tested != Empirically Validated Intent -> Explored -> Specified -> Prototyped -> Implemented -> Observed -> Validated ``` --- ## 🚥 Condition Classification Taxonomy The coordinator classifies all unresolved execution conditions into six explicit types: | Condition | Meaning | Coordinator Response | | :--- | :--- | :--- | | `AUTHORIZATION_MISSING` | User has not permitted the action | Ask one precise question | | `CAPABILITY_MISSING` | Environment cannot perform the action | Stop once; identify required capability | | `EVIDENCE_MISSING` | Promotion cannot yet be justified | Continue allowed preparation; block promotion | | `INPUT_MISSING` | Consequential project decision is unresolved | Use provisional value or ask if execution materially depends on it | | `WORK_UNAVAILABLE` | Nothing actionable is Ready | Park the loop | | `EXTERNAL_EVENT_PENDING` | Only another actor can change state | Enter `WAITING_EXTERNAL`; do not retry | --- ## 🔄 Coordinator State Machine & Preflight Sequence ### Execution Sequence ```text resolve project -> inspect instructions -> test required capabilities -> perform discovery -> prepare changes -> mutate ``` ### State Machine ```text PREFLIGHT (Capabilities & Environment Probe) -> RECONCILE -> SELECT -> VALIDATE -> CLAIM -> ASSEMBLE_CONTEXT -> DISPATCH -> OBSERVE -> EVALUATE -> DISPOSITION -> RECORD -> CLOSE_LOOP -> WAITING_EXTERNAL (Parked on Non-Retryable Blocker) ``` --- ## 🛡️ Hard-Blocker Fingerprinting & Livelock Prevention Every blocker receives a stable `code:scope` fingerprint: ```json { "code": "ENV_WORKSPACE_READ_ONLY", "scope": "target-project", "requiredChange": "workspace-write capability", "retryableByAgent": false, "fingerprint": "ENV_WORKSPACE_READ_ONLY:target-project" } ``` **Rule:** If the current blocker fingerprint matches the previous non-retryable blocker, the agent MUST NOT retry, reread the objective, or consume additional attempts. It immediately enters `WAITING_EXTERNAL` and returns control to the user. --- ## 📜 Provisional Profile Protocol Creating local reversible operating files (`AGENTS.md`, `PROJECT_PROFILE.json`, `.iepe/protocol-reference.json`) requires only local reversible authorization. Unassigned promotion authority yields: ```json { "promotionAuthority": "unassigned", "profileStatus": "provisional", "promotionBlocked": true } ``` Initialization proceeds without blocking, while milestone promotion remains blocked until a named authority is assigned. --- ## 🛠️ Essential CLI Reference ```bash # Install IEPE Core package locally pip install -e .[dev] # Inspect existing project without mutation (Stage 1: Reconcile) iepe-init existing --project-root /path/to/project --report /path/to/report.json # Initialize project operating layer (Stage 2: Apply) iepe-init new \ --project-root /path/to/project \ --project-id project.name \ --project-name "Project Name" \ --intent "Core project intent statement." \ --protocol-source "https://github.com/zachshallbetter/IEPE" \ --protocol-revision "v0.2.0" # Validate full schema, template, evidence, and domain-neutrality suite iepe-validate # Execute pytest unit test suite pytest -v ``` --- FILE: docs/UPSTREAM_REFERENCE.md (50 lines, 2.5 KiB) --- # Upstream IEPE Reference ## Purpose An adopting project should reference a versioned IEPE Core source instead of copying the protocol into local documentation. This preserves a visible boundary between stable process semantics and project-specific authority. ```text IEPE Core at immutable revision -> protocol invariants and schemas -> local protocol reference -> local project profile and authority -> compiled Agent Project Package -> coordinator and worker cycles ``` ## Required pin The project records `.iepe/protocol-reference.json` with: - `protocolId`: the governing protocol identity, currently `IEPE-001` - `protocolVersion`: the declared semantic version - `source`: the canonical repository or content-addressed source - `revision`: an immutable commit, release tag, or digest - `relationship`: `reference` or `vendored` - `conformanceCommand`: the validation entry point for the pinned source A branch name such as `main` is not an adequate release pin. It may be used during provisional development only when the package reports provisional or unknown source state. ## Authority boundary Upstream IEPE owns invariant semantics for claims, bounded context, worker dispatch, evidence maturity, perturbation, promotion, receipts, project memory, and stop conditions. The adopting project owns intent, beneficiaries, experience, architecture, workspaces, providers, evaluators, local procedures, protected actions, and named authorities. Local files may specialize IEPE. They may not redefine artifact existence as evaluation, bypass claims, remove provenance, weaken a protected action, or promote beyond available evidence. ## Update procedure Treat an IEPE revision change as a governed dependency update: 1. Read the release or revision difference. 2. Run upstream conformance at the proposed revision. 3. Validate the local project profile and compiled package. 4. Reconcile schema, status, adapter, and authority changes. 5. Exercise one representative coordinator cycle in a reversible environment. 6. Record evidence and update the pin only after qualification. Do not let an agent update the protocol pin as incidental cleanup during ordinary project work. ## New-agent preflight The first agent verifies that the recorded source and revision can resolve the declared protocol and schemas. If the source is unavailable, the revision is mutable, or the local profile conflicts with the pinned protocol, the agent returns a stopped reconciliation result. Repository access alone does not authorize repair. --- FILE: pyproject.toml (39 lines, 1.0 KiB) --- [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "iepe-core" version = "0.2.0" description = "Intent and Evidence Project Engine Core Reference Implementation" readme = "README.md" requires-python = ">=3.11" license = { text = "Apache-2.0" } classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Topic :: Software Development :: Build Tools", "Topic :: Software Development :: Quality Assurance", ] dependencies = [ "jsonschema>=4.20.0", "PyYAML>=6.0", ] [project.optional-dependencies] dev = [ "pytest>=8.0.0", ] [project.scripts] iepe-init = "tools.init_project:main" iepe-compile = "tools.compile_package:main" iepe-validate = "tools.validate:main" [tool.setuptools.packages.find] where = ["."] include = ["iepe_core*", "tools*"] ======================================================================== ## SUBSYSTEM: CANONICAL CONTRACT SCHEMAS & PROTOCOL DEFINITIONS (16 files) ======================================================================== --- FILE: schemas/agent-package-manifest.schema.json (62 lines, 2.6 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/agent-package-manifest.schema.json", "title": "IEPE Agent Project Package Manifest", "type": "object", "additionalProperties": false, "required": ["formatVersion", "packageId", "packageVersion", "protocol", "releaseClass", "sourceState", "operatingContract", "sources", "skills", "adapters", "outputs", "exclusions", "payloadSha256"], "properties": { "$schema": {"type": "string"}, "formatVersion": {"const": "1"}, "packageId": {"type": "string", "minLength": 1}, "packageVersion": {"type": "string", "minLength": 1}, "protocol": { "type": "object", "additionalProperties": false, "required": ["protocolId", "protocolVersion", "source", "revision"], "properties": { "protocolId": {"const": "IEPE-001"}, "protocolVersion": {"type": "string", "minLength": 1}, "source": {"type": "string", "minLength": 1}, "revision": {"type": "string", "minLength": 7} } }, "releaseClass": {"enum": ["provisional", "release"]}, "sourceState": {"enum": ["clean", "dirty", "unknown", "provisional"]}, "operatingContract": {"type": "string", "minLength": 1}, "sources": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["path", "role", "authorityRank", "bytes", "sha256"], "properties": { "path": {"type": "string", "minLength": 1}, "role": {"enum": ["intent", "doctrine", "ontology", "schema", "implementation", "operations", "evidence", "historical"]}, "authorityRank": {"type": "integer", "minimum": 1}, "bytes": {"type": "integer", "minimum": 0}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"} } } }, "skills": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}, "adapters": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}, "outputs": { "type": "array", "minItems": 3, "items": { "type": "object", "additionalProperties": false, "required": ["path", "bytes", "sha256"], "properties": { "path": {"type": "string", "minLength": 1}, "bytes": {"type": "integer", "minimum": 0}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"} } } }, "exclusions": {"type": "array", "items": {"type": "string"}}, "payloadSha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"} } } --- FILE: schemas/agent-package-source.schema.json (46 lines, 2.0 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/agent-package-source.schema.json", "title": "IEPE Agent Project Package Source", "type": "object", "additionalProperties": false, "required": ["packageId", "packageVersion", "projectRoot", "protocol", "releaseClass", "sourceState", "operatingContract", "sources", "skills", "adapters", "exclusions"], "properties": { "$schema": {"type": "string"}, "manifestSchema": {"type": "string"}, "packageId": {"type": "string", "minLength": 1}, "packageVersion": {"type": "string", "minLength": 1}, "projectRoot": {"type": "string", "minLength": 1}, "protocol": { "type": "object", "additionalProperties": false, "required": ["protocolId", "protocolVersion", "source", "revision"], "properties": { "protocolId": {"const": "IEPE-001"}, "protocolVersion": {"type": "string", "minLength": 1}, "source": {"type": "string", "minLength": 1}, "revision": {"type": "string", "minLength": 7} } }, "releaseClass": {"enum": ["provisional", "release"]}, "sourceState": {"enum": ["clean", "dirty", "unknown", "provisional"]}, "operatingContract": {"type": "string", "minLength": 1}, "sources": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["path", "role", "authorityRank"], "properties": { "path": {"type": "string", "minLength": 1}, "role": {"enum": ["intent", "doctrine", "ontology", "schema", "implementation", "operations", "evidence", "historical"]}, "authorityRank": {"type": "integer", "minimum": 1} } } }, "skills": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}, "adapters": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}, "exclusions": {"type": "array", "items": {"type": "string"}} } } --- FILE: schemas/context-packet.schema.json (36 lines, 1.6 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/context-packet.schema.json", "title": "IEPE Bounded Context Packet", "type": "object", "additionalProperties": false, "required": ["id", "issueId", "claimId", "objective", "sources", "dependencies", "constraints", "evidenceRequired", "permissions", "stopConditions", "contextSha256"], "properties": { "$schema": {"type": "string"}, "id": {"type": "string", "minLength": 1}, "issueId": {"type": "string", "minLength": 1}, "claimId": {"type": "string", "minLength": 1}, "objective": {"type": "string", "minLength": 1}, "sources": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["ref", "kind", "authorityRank", "sha256"], "properties": { "ref": {"type": "string", "minLength": 1}, "kind": {"enum": ["intent", "authority", "experience", "dependency", "evidence", "operations"]}, "authorityRank": {"type": "integer", "minimum": 1}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"} } } }, "dependencies": {"type": "object", "additionalProperties": {"type": "string"}}, "constraints": {"type": "array", "items": {"type": "string"}}, "evidenceRequired": {"type": "array", "minItems": 1, "items": {"type": "string"}}, "permissions": {"type": "object", "additionalProperties": {"type": "boolean"}}, "stopConditions": {"type": "array", "minItems": 1, "items": {"type": "string"}}, "contextSha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"} } } --- FILE: schemas/evaluation-record.schema.json (35 lines, 1.4 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/evaluation-record.schema.json", "title": "IEPE Evaluation Record", "type": "object", "additionalProperties": false, "required": ["id", "subjectRef", "evaluator", "independence", "dimensions", "limitations", "disposition"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "subjectRef": { "type": "string", "minLength": 1 }, "baselineRef": { "type": ["string", "null"] }, "evaluator": { "type": "string", "minLength": 1 }, "independence": { "enum": ["independent", "partially-independent", "self-evaluation"] }, "environmentRef": { "type": ["string", "null"] }, "dimensions": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["name", "result", "evidenceRefs"], "properties": { "name": { "type": "string", "minLength": 1 }, "result": {}, "threshold": {}, "evidenceRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } } } } }, "tradeoffs": { "type": "array", "items": { "type": "string" }, "default": [] }, "limitations": { "type": "array", "items": { "type": "string" } }, "disposition": { "enum": ["reject", "retain", "retry", "revise", "escalate", "qualify"] } } } --- FILE: schemas/evidence-bundle.schema.json (56 lines, 2.0 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/evidence-bundle.schema.json", "title": "IEPE Evidence Bundle", "type": "object", "additionalProperties": false, "required": [ "id", "projectId", "issueId", "artifactRefs", "intentRefs", "environment", "evaluations", "limitations", "qualification" ], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "issueId": { "type": "string", "minLength": 1 }, "candidateId": { "type": ["string", "null"] }, "artifactRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "intentRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "authorityRefs": { "type": "array", "items": { "type": "string" }, "default": [] }, "environment": { "type": "object" }, "inputs": { "type": "array", "items": { "type": "string" }, "default": [] }, "provenance": { "type": "array", "items": { "type": "string" }, "default": [] }, "evaluations": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["dimension", "result", "evaluator"], "properties": { "dimension": { "type": "string" }, "result": {}, "evaluator": { "type": "string" }, "evidenceRefs": { "type": "array", "items": { "type": "string" } } } } }, "baselineComparison": { "type": ["object", "null"] }, "cost": { "type": ["object", "null"] }, "tradeoffs": { "type": "array", "items": { "type": "string" }, "default": [] }, "limitations": { "type": "array", "items": { "type": "string" } }, "qualification": { "enum": ["documented", "implemented", "tested", "empirically-validated"] }, "promotionRecommendation": { "enum": ["reject", "retain", "retry", "revise", "escalate", "promote", null] }, "reproduction": { "type": ["string", "null"] } } } --- FILE: schemas/experience-contract.schema.json (31 lines, 1.6 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/experience-contract.schema.json", "title": "IEPE Experience Contract", "type": "object", "additionalProperties": false, "required": ["id", "intent", "audience", "desiredOutcomes", "experientialQualities", "states", "constraints", "accessibilityRequirements", "evidenceRequirements"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "intent": { "type": "string", "minLength": 1 }, "audience": { "type": "object", "additionalProperties": false, "required": ["primary", "contexts"], "properties": { "primary": { "type": "string", "minLength": 1 }, "contexts": { "type": "array", "items": { "type": "string" } } } }, "desiredOutcomes": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "experientialQualities": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "behaviorsToEncourage": { "type": "array", "items": { "type": "string" }, "default": [] }, "behaviorsToAvoid": { "type": "array", "items": { "type": "string" }, "default": [] }, "states": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "accessibilityRequirements": { "type": "array", "items": { "type": "string" } }, "evidenceRequirements": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "authorityRefs": { "type": "array", "items": { "type": "string" }, "default": [] } } } --- FILE: schemas/issue-contract.schema.json (72 lines, 2.4 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/issue-contract.schema.json", "title": "IEPE Issue Contract", "type": "object", "additionalProperties": false, "required": [ "id", "type", "title", "intentRefs", "objective", "owner", "acceptanceCriteria", "evidenceRequired", "constraints", "permissions", "stopConditions" ], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "type": { "enum": [ "delivery", "experiment", "candidate", "evaluation", "design", "decision", "documentation", "incident", "promotion", "observation" ] }, "title": { "type": "string", "minLength": 1 }, "intentRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "experienceRefs": { "type": "array", "items": { "type": "string" }, "default": [] }, "objective": { "type": "string", "minLength": 1 }, "hypothesis": { "type": ["string", "null"] }, "owner": { "type": "string", "minLength": 1 }, "workspace": { "type": ["string", "null"] }, "parent": { "type": ["string", "null"] }, "dependencies": { "type": "array", "items": { "type": "string" }, "default": [] }, "acceptanceCriteria": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "evidenceRequired": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" }, "default": [] }, "permissions": { "type": "object", "additionalProperties": false, "required": ["externalWrites", "deployments", "communications", "spending"], "properties": { "externalWrites": { "type": "boolean" }, "deployments": { "type": "boolean" }, "communications": { "type": "boolean" }, "spending": { "type": "boolean" } } }, "budget": { "type": "object", "additionalProperties": false, "properties": { "time": { "type": ["string", "null"] }, "cost": { "type": ["number", "null"], "minimum": 0 }, "iterations": { "type": ["integer", "null"], "minimum": 1 } } }, "stopConditions": { "type": "array", "minItems": 1, "items": { "type": "string" } } } } --- FILE: schemas/migration-record.schema.json (33 lines, 1.5 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/migration-record.schema.json", "title": "IEPE Migration Record", "type": "object", "additionalProperties": false, "required": ["id", "source", "classification", "disposition", "provenance", "evidenceGaps", "decision"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "source": { "type": "object", "additionalProperties": false, "required": ["provider", "itemId", "status"], "properties": { "provider": { "type": "string", "minLength": 1 }, "itemId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "url": { "type": ["string", "null"] } } }, "classification": { "enum": ["historical", "active", "new"] }, "disposition": { "enum": ["preserve", "reconcile", "require-full-contract", "blocked"] }, "targetStatus": { "type": ["string", "null"] }, "statusRationale": { "type": ["string", "null"] }, "intentRefs": { "type": "array", "items": { "type": "string" }, "default": [] }, "relationshipRefs": { "type": "array", "items": { "type": "string" }, "default": [] }, "provenance": { "enum": ["complete", "partial", "missing"] }, "evidenceGaps": { "type": "array", "items": { "type": "string" } }, "decision": { "enum": ["accepted", "needs-review", "rejected"] }, "notes": { "type": ["string", "null"] } } } --- FILE: schemas/perturbation.schema.json (21 lines, 1.1 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/perturbation.schema.json", "title": "IEPE Designed Perturbation", "type": "object", "additionalProperties": false, "required": ["id", "family", "visibility", "protectedInvariants", "changedConditions", "revealGate", "evaluationDimensions", "severity", "recoveryRequired"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "family": { "enum": ["context", "constraint", "evidence", "actor", "time", "dependency", "scale", "intent-collision"] }, "visibility": { "enum": ["sealed", "revealed"] }, "protectedInvariants": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "changedConditions": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "revealGate": { "const": "candidate-frozen" }, "evaluationDimensions": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "severity": { "enum": ["low", "moderate", "high"] }, "recoveryRequired": { "type": "boolean" }, "steward": { "type": ["string", "null"] } } } --- FILE: schemas/project-profile.schema.json (60 lines, 2.5 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/project-profile.schema.json", "title": "IEPE Project Profile", "type": "object", "additionalProperties": false, "required": ["id", "protocol", "intentRefs", "authorityOrder", "workGraph", "coordinator", "evaluators", "protectedActions", "promotionAuthorities", "memory"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "profileStatus": { "enum": ["established", "provisional"] }, "protocol": { "type": "object", "additionalProperties": false, "required": ["protocolId", "protocolVersion", "source", "revision"], "properties": { "protocolId": {"const": "IEPE-001"}, "protocolVersion": {"type": "string", "minLength": 1}, "source": {"type": "string", "minLength": 1}, "revision": {"type": "string", "minLength": 7} } }, "intentRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "authorityOrder": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "workGraph": { "type": "object", "additionalProperties": false, "required": ["provider", "projectRefs"], "properties": { "provider": { "type": "string", "minLength": 1 }, "projectRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "workspaces": { "type": "array", "items": { "type": "string" }, "default": [] }, "coordinator": { "type": "object", "additionalProperties": false, "required": ["identity", "capacity"], "properties": { "identity": { "type": "string", "minLength": 1 }, "capacity": { "type": "integer", "minimum": 1 }, "stopPolicyRef": { "type": ["string", "null"] } } }, "evaluators": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "protectedActions": { "type": "array", "items": { "type": "string" } }, "promotionAuthorities": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "memory": { "type": "object", "additionalProperties": false, "required": ["operational", "institutional", "negativeResults"], "properties": { "operational": { "type": "string", "minLength": 1 }, "institutional": { "type": "string", "minLength": 1 }, "negativeResults": { "type": "string", "minLength": 1 } } } } } --- FILE: schemas/promotion-record.schema.json (22 lines, 1.1 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/promotion-record.schema.json", "title": "IEPE Promotion Record", "type": "object", "additionalProperties": false, "required": ["id", "subjectRef", "issueRef", "evidenceBundleRef", "authority", "decision", "target", "tradeoffs", "recoveryPlan"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "subjectRef": { "type": "string", "minLength": 1 }, "issueRef": { "type": "string", "minLength": 1 }, "evidenceBundleRef": { "type": "string", "minLength": 1 }, "authority": { "type": "string", "minLength": 1 }, "decision": { "enum": ["approved", "rejected", "deferred", "revoked"] }, "target": { "type": "string", "minLength": 1 }, "tradeoffs": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "array", "items": { "type": "string" }, "default": [] }, "recoveryPlan": { "type": "string", "minLength": 1 }, "effectiveAt": { "type": ["string", "null"], "format": "date-time" } } } --- FILE: schemas/protocol-reference.schema.json (17 lines, 0.7 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/protocol-reference.schema.json", "title": "IEPE Protocol Reference", "type": "object", "additionalProperties": false, "required": ["protocolId", "protocolVersion", "source", "revision", "relationship", "conformanceCommand"], "properties": { "$schema": {"type": "string"}, "protocolId": {"const": "IEPE-001"}, "protocolVersion": {"type": "string", "minLength": 1}, "source": {"type": "string", "minLength": 1}, "revision": {"type": "string", "minLength": 7}, "relationship": {"enum": ["reference", "vendored"]}, "conformanceCommand": {"type": "string", "minLength": 1} } } --- FILE: schemas/robustness-profile.schema.json (41 lines, 1.7 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/robustness-profile.schema.json", "title": "IEPE Robustness Profile", "type": "object", "additionalProperties": false, "required": ["id", "candidateRef", "knownQualificationRef", "surpriseBudget", "trials", "validityBoundary", "promotionEffect"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "candidateRef": { "type": "string", "minLength": 1 }, "knownQualificationRef": { "type": "string", "minLength": 1 }, "surpriseBudget": { "type": "object", "additionalProperties": false, "required": ["evaluationShare", "minimumWorldCards", "candidateVisibility"], "properties": { "evaluationShare": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "minimumWorldCards": { "type": "integer", "minimum": 1 }, "candidateVisibility": { "const": "sealed-until-frozen" } } }, "trials": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["worldCardRef", "disposition", "evidenceRefs", "limitations"], "properties": { "worldCardRef": { "type": "string" }, "disposition": { "enum": ["robust", "adaptable", "bounded", "fragile", "unsafe", "unknown"] }, "evidenceRefs": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "limitations": { "type": "array", "items": { "type": "string" } } } } }, "validityBoundary": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "promotionEffect": { "enum": ["none", "constrain", "revise", "block", "escalate"] } } } --- FILE: schemas/unknown-variable-ledger.schema.json (29 lines, 1.1 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/unknown-variable-ledger.schema.json", "title": "IEPE Unknown Variable Ledger", "type": "object", "additionalProperties": false, "required": ["id", "projectRef", "entries"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "projectRef": { "type": "string", "minLength": 1 }, "entries": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["id", "variable", "classification", "evidenceRefs", "nextProbe"], "properties": { "id": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "classification": { "enum": ["known-controlled", "known-unresolved", "assumed-untested", "observed-once", "discovered-through-perturbation", "currently-unknowable"] }, "evidenceRefs": { "type": "array", "items": { "type": "string" } }, "nextProbe": { "type": ["string", "null"] } } } } } } --- FILE: schemas/worker-dispatch.schema.json (32 lines, 1.4 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/worker-dispatch.schema.json", "title": "IEPE Worker Dispatch Record", "type": "object", "additionalProperties": false, "required": ["id", "issueId", "claimId", "contextSha256", "workerId", "role", "attempt", "permissions", "status"], "properties": { "$schema": {"type": "string"}, "id": {"type": "string", "minLength": 1}, "issueId": {"type": "string", "minLength": 1}, "claimId": {"type": "string", "minLength": 1}, "contextSha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "workerId": {"type": "string", "minLength": 1}, "role": {"type": "string", "minLength": 1}, "attempt": {"type": "integer", "minimum": 1}, "permissions": {"type": "object", "additionalProperties": {"type": "boolean"}}, "status": {"enum": ["active", "completed", "failed", "blocked", "stopped"]}, "result": { "type": ["object", "null"], "additionalProperties": false, "required": ["artifacts", "observations", "commands", "cost", "limitations"], "properties": { "artifacts": {"type": "array", "items": {"type": "string"}}, "observations": {"type": "array", "items": {"type": "string"}}, "commands": {"type": "array", "items": {"type": "string"}}, "cost": {"type": ["number", "null"], "minimum": 0}, "limitations": {"type": "array", "items": {"type": "string"}} } } } } --- FILE: schemas/world-card.schema.json (20 lines, 1.0 KiB) --- { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://iepe.dev/schema/world-card.schema.json", "title": "IEPE World Card", "type": "object", "additionalProperties": false, "required": ["id", "perturbationRef", "premise", "retained", "changed", "questions", "evidenceRequired", "revealState", "candidateFreezeRef"], "properties": { "$schema": { "type": "string" }, "id": { "type": "string", "minLength": 1 }, "perturbationRef": { "type": "string", "minLength": 1 }, "premise": { "type": "string", "minLength": 1 }, "retained": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "changed": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "questions": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "evidenceRequired": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "revealState": { "enum": ["sealed", "revealed"] }, "candidateFreezeRef": { "type": "string", "minLength": 1 } } } ======================================================================== ## SUBSYSTEM: CORE REFERENCE IMPLEMENTATION (IEPE_CORE) (7 files) ======================================================================== --- FILE: iepe_core/__init__.py (32 lines, 1.0 KiB) --- """Provider-neutral reference components for IEPE Core.""" from .coordinator import AssertionType, Coordinator, CoordinatorState, ExecutionReceipt, GateAssertion, StopRecord from .claims import Claim, ClaimEvent, ClaimMode, ClaimRegistry, scopes_overlap from .context import ContextPacket, ContextRequest, ContextSource, assemble_context_packet from .dispatch import DispatchEnvelope, DispatchRegistry, WorkerOutcome, WorkerResult from .receipts import load_and_validate_receipt, seal_receipt, serialize_receipt __all__ = [ "AssertionType", "Claim", "ClaimEvent", "ClaimMode", "ClaimRegistry", "ContextPacket", "ContextRequest", "ContextSource", "DispatchEnvelope", "DispatchRegistry", "Coordinator", "CoordinatorState", "ExecutionReceipt", "GateAssertion", "StopRecord", "WorkerOutcome", "WorkerResult", "load_and_validate_receipt", "seal_receipt", "serialize_receipt", "scopes_overlap", "assemble_context_packet", ] --- FILE: iepe_core/bootstrap.py (336 lines, 14.3 KiB) --- """Deterministic, reference-pinned IEPE project initialization.""" from __future__ import annotations from dataclasses import dataclass import hashlib import json from pathlib import Path import re from typing import Iterable FORBIDDEN_PARTS = {".git", "__MACOSX", "__pycache__", ".pytest_cache"} PROJECT_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$") CORE_ROOT = Path(__file__).resolve().parents[1] def canonical_json(value: object) -> str: return json.dumps(value, sort_keys=True, indent=2, ensure_ascii=False) + "\n" @dataclass(frozen=True) class BootstrapConfig: project_id: str project_name: str intent: str protocol_source: str protocol_revision: str protocol_version: str = "0.2.0" work_graph_provider: str = "local" project_ref: str = "work" coordinator_identity: str = "coordinator.local" coordinator_capacity: int = 1 evaluators: tuple[str, ...] = ("manual.acceptance",) promotion_authorities: tuple[str, ...] = ("project.owner",) protected_actions: tuple[str, ...] = ( "external-publication", "production-deployment", "spending", "destructive-migration", "credential-or-iam-change", "authoritative-intent-change", "external-communication", ) def validate(self) -> None: values = { "project ID": self.project_id, "project name": self.project_name, "intent": self.intent, "protocol source": self.protocol_source, "protocol revision": self.protocol_revision, "protocol version": self.protocol_version, "work graph provider": self.work_graph_provider, "project reference": self.project_ref, "coordinator identity": self.coordinator_identity, } for label, value in values.items(): if not value.strip(): raise ValueError(f"Missing {label}") if not PROJECT_ID.fullmatch(self.project_id): raise ValueError("Project ID must use letters, numbers, dots, underscores, or hyphens") if len(self.protocol_revision) < 7: raise ValueError("Protocol revision must be an immutable tag or digest with at least seven characters") if self.coordinator_capacity < 1: raise ValueError("Coordinator capacity must be positive") if not self.evaluators or not self.promotion_authorities: raise ValueError("At least one evaluator and promotion authority are required") def protocol_reference(config: BootstrapConfig) -> dict: return { "$schema": "https://iepe.dev/schema/protocol-reference.schema.json", "protocolId": "IEPE-001", "protocolVersion": config.protocol_version, "source": config.protocol_source, "revision": config.protocol_revision, "relationship": "reference", "conformanceCommand": "python3 tools/validate.py", } def project_profile(config: BootstrapConfig) -> dict: protocol = protocol_reference(config) is_provisional = "unassigned" in config.promotion_authorities return { "$schema": "https://iepe.dev/schema/project-profile.schema.json", "id": config.project_id, "name": config.project_name, "profileStatus": "provisional" if is_provisional else "established", "protocol": {key: protocol[key] for key in ("protocolId", "protocolVersion", "source", "revision")}, "intentRefs": ["INTENT.md"], "authorityOrder": ["INTENT.md", "docs/EXPERIENCE.md", "docs/ARCHITECTURE.md", "PROJECT_PROFILE.json", "AGENTS.md"], "workGraph": {"provider": config.work_graph_provider, "projectRefs": [config.project_ref]}, "workspaces": ["."], "coordinator": { "identity": config.coordinator_identity, "capacity": config.coordinator_capacity, "stopPolicyRef": "AGENTS.md#stop-conditions", }, "evaluators": list(config.evaluators), "protectedActions": list(config.protected_actions), "promotionAuthorities": list(config.promotion_authorities), "memory": { "operational": config.project_ref, "institutional": "docs", "negativeResults": "docs/NEGATIVE_RESULTS.md", }, } def _agents(config: BootstrapConfig) -> str: return f"""# {config.project_name} Agent Operating Contract ## IEPE authority This project operates under `IEPE-001`, version `{config.protocol_version}`, from `{config.protocol_source}` at immutable revision `{config.protocol_revision}`. The pin is recorded in `.iepe/protocol-reference.json`. IEPE Core governs claim, context, dispatch, evidence, perturbation, promotion, memory, and stop semantics. Local canonical sources govern this project's intent, experience, architecture, work graph, evaluators, adapters, and protected actions. Local instructions may specialize IEPE but may not weaken its invariants. Preserve this trace: ```text intent -> epic -> issue -> claim -> context -> artifact -> evaluation -> evidence -> qualification -> promotion ``` ## Authority order 1. `INTENT.md` 2. `docs/EXPERIENCE.md` 3. `docs/ARCHITECTURE.md` 4. `PROJECT_PROFILE.json` 5. Authorized issues and decisions 6. Implementation and operational observations 7. Generated agent context Conversation and generated files are evidence inputs, not automatic authority. ## Operational loop ```text reconcile -> select -> validate -> claim -> assemble bounded context -> dispatch -> observe -> evaluate -> stress test when required -> record evidence -> disposition -> release claim -> repeat ``` ## Startup 1. Verify `.iepe/protocol-reference.json` and `PROJECT_PROFILE.json` against the pinned IEPE revision. 2. Inspect repository, documentation, work graph, claims, dependencies, tests, and evidence without mutation. 3. Reconcile contradictions and missing authority. 4. Select only a complete Ready issue. 5. Claim bounded scope, assemble minimal context, dispatch, evaluate, record, and release. The first agent cycle is read-only reconciliation. Do not infer mutation authority from repository access. ## Status honesty `Documented != Implemented != Tested != Empirically Validated` Artifact existence, a passing API call, or completion language does not establish qualification. ## Process routing Use the narrowest procedure under `.agents/skills/`: initialize, reconcile, operate, qualify, stress test, or maintain the package. These procedures are projections from the pinned IEPE revision and cannot expand local authority. ## Protected actions Read `PROJECT_PROFILE.json`. Protected actions require its named promotion authority and issue-level authorization. ## Stop conditions Stop and record a typed result when authority, ownership, context, dependencies, permissions, evidence, evaluator availability, provider health, or recovery becomes ambiguous. Stop when capacity or retry limits are exhausted. Silence is not approval. """ def _intent(config: BootstrapConfig) -> str: return f"""# {config.project_name} Intent ## Purpose {config.intent.strip()} ## Beneficiaries Unconfirmed. Establish before the first promotional decision. ## Protected qualities Unconfirmed. Record qualities that implementation must preserve. ## Exclusions Unconfirmed. Record outcomes this project must not pursue. ## Success evidence Unconfirmed. Define observable evidence before the first issue becomes Ready. """ def generated_files(config: BootstrapConfig) -> dict[str, str]: config.validate() protocol = protocol_reference(config) profile = project_profile(config) package_source = { "$schema": "https://iepe.dev/schema/agent-package-source.schema.json", "manifestSchema": "https://iepe.dev/schema/agent-package-manifest.schema.json", "packageId": f"{config.project_id}.agent-package", "packageVersion": "0.1.0", "projectRoot": "..", "protocol": {key: protocol[key] for key in ("protocolId", "protocolVersion", "source", "revision")}, "releaseClass": "provisional", "sourceState": "provisional", "operatingContract": "AGENTS.md", "sources": [ {"path": ".iepe/protocol-reference.json", "role": "doctrine", "authorityRank": 1}, {"path": "INTENT.md", "role": "intent", "authorityRank": 2}, {"path": "docs/EXPERIENCE.md", "role": "doctrine", "authorityRank": 3}, {"path": "docs/ARCHITECTURE.md", "role": "doctrine", "authorityRank": 4}, {"path": "PROJECT_PROFILE.json", "role": "operations", "authorityRank": 5}, {"path": "AGENTS.md", "role": "operations", "authorityRank": 6}, {"path": "ROADMAP.md", "role": "operations", "authorityRank": 7}, ], "skills": [ f"iepe-core:initialize-iepe-project@{config.protocol_revision}", f"iepe-core:maintain-iepe-package@{config.protocol_revision}", f"iepe-core:operate-iepe-project@{config.protocol_revision}", f"iepe-core:qualify-iepe-outcome@{config.protocol_revision}", f"iepe-core:reconcile-iepe-project@{config.protocol_revision}", f"iepe-core:stress-test-iepe-candidate@{config.protocol_revision}", ], "adapters": [], "exclusions": [".git", "__MACOSX", "__pycache__", "*.pyc", "undeclared files"], } files = { ".agents/NEW_AGENT_PROMPT.md": f"""# First Agent Cycle Operate {config.project_name} under the pinned IEPE reference in `.iepe/protocol-reference.json` and the local contract in `AGENTS.md`. Begin with read-only reconciliation. Verify the protocol pin, local profile, authority chain, repository state, work graph, dependencies, evaluators, protected actions, and evidence gaps. Do not implement, claim, create or change work items, push, merge, deploy, publish, spend, or communicate externally during this first cycle unless the user explicitly expands authority. Return a typed reconciliation result, the material unknowns, and the first candidate Ready issue. If initialization gates are incomplete, stop with the exact authority or evidence needed to continue. """, ".agents/package-source.json": canonical_json(package_source), ".agents/runtime/COORDINATOR.md": """# Coordinator Runtime Use the state sequence defined by pinned IEPE Core: preflight, reconcile, select, validate, claim, assemble context, dispatch, observe, evaluate, disposition, record, and close loop. Concurrency, work-graph identity, evaluators, protected actions, promotion authorities, and memory locations come from `PROJECT_PROFILE.json`. Persist typed receipts. Never let a provider adapter expand local permissions or IEPE invariants. """, ".iepe/protocol-reference.json": canonical_json(protocol), "AGENTS.md": _agents(config), "INTENT.md": _intent(config), "PROJECT_PROFILE.json": canonical_json(profile), "ROADMAP.md": f"""# {config.project_name} Roadmap ## M0: Governed baseline Exit evidence: - intent, beneficiaries, protected qualities, exclusions, and success evidence are confirmed - project profile and protocol pin conform - zero-state or operational baseline is recorded - one material unknown is registered - one bounded, reversible issue is Ready ## M1: First qualified outcome Define after M0. Express the milestone as observable capability and exit evidence rather than a feature inventory. """, "docs/ARCHITECTURE.md": "# Architecture\n\nNo architecture has been authorized. Record established decisions separately from proposals and observations.\n", "docs/EXPERIENCE.md": "# Experience Contract\n\nBeneficiaries, critical journeys, states, accessibility requirements, protected qualities, and observation methods remain unconfirmed.\n", "docs/NEGATIVE_RESULTS.md": "# Negative and Inconclusive Results\n\nRetain rejected candidates, failed evaluations, contradictions, limitations, and the evidence that produced each disposition.\n", } for source in sorted((CORE_ROOT / ".agents/skills").glob("*/SKILL.md")): files[f".agents/skills/{source.parent.name}/SKILL.md"] = source.read_text(encoding="utf-8") return files def probe_workspace_write_capability(root: Path) -> bool: root = root.resolve() if not root.exists(): try: root.mkdir(parents=True, exist_ok=True) except OSError: return False probe_file = root / ".iepe-write-probe" try: probe_file.write_text("probe", encoding="utf-8") probe_file.unlink(missing_ok=True) return True except OSError: return False def initialize_new(root: Path, config: BootstrapConfig, *, overwrite: bool = False) -> tuple[Path, ...]: root = root.resolve() if not probe_workspace_write_capability(root): raise PermissionError("ENV_WORKSPACE_READ_ONLY: Cannot write to workspace root. Preflight write probe failed.") files = generated_files(config) conflicts = sorted(relative for relative in files if (root / relative).exists()) if conflicts and not overwrite: raise FileExistsError("Refusing to overwrite existing files: " + ", ".join(conflicts)) written = [] for relative, content in sorted(files.items()): path = root / relative path.parent.mkdir(parents=True, exist_ok=True) path.write_text(content, encoding="utf-8") written.append(path) return tuple(written) def discover_existing(root: Path) -> dict: root = root.resolve() if not root.is_dir(): raise ValueError(f"Project root is not a directory: {root}") records = [] for path in sorted(item for item in root.rglob("*") if item.is_file()): relative = path.relative_to(root) if any(part in FORBIDDEN_PARTS for part in relative.parts): continue data = path.read_bytes() records.append({"path": relative.as_posix(), "bytes": len(data), "sha256": hashlib.sha256(data).hexdigest()}) names = {record["path"] for record in records} return { "mode": "existing-read-only", "projectRoot": str(root), "files": records, "signals": { "hasAgentContract": "AGENTS.md" in names, "hasIntent": "INTENT.md" in names, "hasProjectProfile": "PROJECT_PROFILE.json" in names, "hasProtocolReference": ".iepe/protocol-reference.json" in names, "hasGitMetadata": (root / ".git").exists(), }, "nextAction": "Review provenance and contradictions before authorizing an IEPE overlay.", } --- FILE: iepe_core/claims.py (133 lines, 4.5 KiB) --- """Provider-neutral in-memory claim capacity and conflict management.""" from __future__ import annotations from dataclasses import dataclass from datetime import datetime, timezone from enum import Enum from .coordinator import AssertionType, GateAssertion class ClaimMode(str, Enum): READ = "read" WRITE = "write" @dataclass(frozen=True) class Claim: id: str issue_id: str agent_id: str workspace: str scopes: tuple[str, ...] mode: ClaimMode acquired_at: datetime expires_at: datetime @dataclass(frozen=True) class ClaimEvent: sequence: int claim_id: str action: str at: datetime reason: str | None = None def _utc(value: datetime) -> datetime: if value.tzinfo is None: raise ValueError("Claim timestamps must be timezone-aware") return value.astimezone(timezone.utc) def _scope_parts(scope: str) -> tuple[str, ...]: normalized = scope.strip().strip("/") if not normalized: raise ValueError("Claim scope cannot be empty") return tuple(part for part in normalized.split("/") if part) def scopes_overlap(left: str, right: str) -> bool: """Return true when either provider-neutral hierarchical scope contains the other.""" left_parts = _scope_parts(left) right_parts = _scope_parts(right) common = min(len(left_parts), len(right_parts)) return left_parts[:common] == right_parts[:common] class ClaimRegistry: def __init__(self, capacity: int) -> None: if capacity < 1: raise ValueError("Claim capacity must be at least one") self.capacity = capacity self._claims: dict[str, Claim] = {} self._released: set[str] = set() self._events: list[ClaimEvent] = [] @property def history(self) -> tuple[ClaimEvent, ...]: return tuple(self._events) def active(self, *, now: datetime) -> tuple[Claim, ...]: point = _utc(now) return tuple( claim for claim in self._claims.values() if claim.id not in self._released and _utc(claim.expires_at) > point ) def acquire(self, claim: Claim, *, now: datetime) -> Claim: point = _utc(now) acquired = _utc(claim.acquired_at) expires = _utc(claim.expires_at) if claim.id in self._claims: raise ValueError(f"Claim id already exists: {claim.id}") if not claim.scopes: raise ValueError("Claim requires at least one scope") if acquired > point: raise ValueError("Claim acquisition cannot be in the future") if expires <= point or expires <= acquired: raise ValueError("Claim must expire after acquisition and after the current time") active = self.active(now=point) if len(active) >= self.capacity: raise ValueError("Coordinator claim capacity exceeded") for existing in active: if existing.workspace != claim.workspace: continue if claim.mode is ClaimMode.READ and existing.mode is ClaimMode.READ: continue if any(scopes_overlap(left, right) for left in claim.scopes for right in existing.scopes): raise ValueError(f"Claim scope conflicts with active claim: {existing.id}") self._claims[claim.id] = claim self._record(claim.id, "acquired", point) return claim def release(self, claim_id: str, *, now: datetime, reason: str | None = None) -> bool: point = _utc(now) if claim_id not in self._claims: raise KeyError(f"Unknown claim: {claim_id}") if claim_id in self._released: self._record(claim_id, "release-repeated", point, reason) return False self._released.add(claim_id) self._record(claim_id, "released", point, reason) return True def claim_assertion(self, claim_id: str, *, issue_id: str, now: datetime) -> GateAssertion: point = _utc(now) claim = self._claims.get(claim_id) valid = claim is not None and claim.issue_id == issue_id and claim in self.active(now=point) return GateAssertion( id=f"assertion.{issue_id}.claim.valid.{claim_id}", kind=AssertionType.CLAIM_VALID, subject=issue_id, issuer="coordinator.claim-registry", evidence_refs=(f"claim.{claim_id}",), valid=valid, ) def _record(self, claim_id: str, action: str, at: datetime, reason: str | None = None) -> None: self._events.append(ClaimEvent(len(self._events) + 1, claim_id, action, at, reason)) --- FILE: iepe_core/context.py (112 lines, 4.0 KiB) --- """Deterministic, claim-bound context packet assembly.""" from __future__ import annotations from dataclasses import dataclass from datetime import datetime import hashlib import json from typing import Mapping from .claims import ClaimRegistry @dataclass(frozen=True) class ContextSource: ref: str kind: str authority_rank: int content: str assertion_subject: str | None = None @property def sha256(self) -> str: return hashlib.sha256(self.content.encode()).hexdigest() @dataclass(frozen=True) class ContextRequest: issue_id: str claim_id: str objective: str intent_refs: tuple[str, ...] authority_refs: tuple[str, ...] experience_refs: tuple[str, ...] = () dependencies: tuple[str, ...] = () constraints: tuple[str, ...] = () evidence_required: tuple[str, ...] = () permissions: tuple[tuple[str, bool], ...] = () stop_conditions: tuple[str, ...] = () @dataclass(frozen=True) class ContextPacket: record: dict @property def digest(self) -> str: return self.record["contextSha256"] def _canonical(value: object) -> bytes: return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode() def assemble_context_packet( request: ContextRequest, *, registry: ClaimRegistry, now: datetime, sources: Mapping[str, ContextSource], dependency_records: Mapping[str, str], max_sources: int = 24, ) -> ContextPacket: if not request.issue_id or not request.objective: raise ValueError("Context request requires issue and objective") if not request.intent_refs or not request.authority_refs: raise ValueError("Context request requires intent and authority references") if not request.evidence_required or not request.stop_conditions: raise ValueError("Context request requires evidence and stop conditions") assertion = registry.claim_assertion(request.claim_id, issue_id=request.issue_id, now=now) if not assertion.valid: raise ValueError("Context packet requires a matching active claim") ordered_refs = tuple(dict.fromkeys(request.intent_refs + request.authority_refs + request.experience_refs)) missing = sorted(ref for ref in ordered_refs if ref not in sources) if missing: raise ValueError(f"Missing mandatory context: {', '.join(missing)}") missing_dependencies = sorted(ref for ref in request.dependencies if ref not in dependency_records) if missing_dependencies: raise ValueError(f"Missing dependency state: {', '.join(missing_dependencies)}") if len(ordered_refs) > max_sources: raise ValueError("Bounded context source limit exceeded") selected = [sources[ref] for ref in ordered_refs] assertions: dict[str, str] = {} for source in selected: if source.assertion_subject is None: continue previous = assertions.get(source.assertion_subject) if previous is not None and previous != source.sha256: raise ValueError(f"Authority conflict for subject: {source.assertion_subject}") assertions[source.assertion_subject] = source.sha256 selected.sort(key=lambda source: (source.authority_rank, source.ref)) record = { "$schema": "../schemas/context-packet.schema.json", "id": f"context.{request.issue_id}.{request.claim_id}", "issueId": request.issue_id, "claimId": request.claim_id, "objective": request.objective, "sources": [ {"ref": source.ref, "kind": source.kind, "authorityRank": source.authority_rank, "sha256": source.sha256} for source in selected ], "dependencies": {ref: dependency_records[ref] for ref in sorted(request.dependencies)}, "constraints": list(request.constraints), "evidenceRequired": list(request.evidence_required), "permissions": {key: value for key, value in sorted(request.permissions)}, "stopConditions": list(request.stop_conditions), } record["contextSha256"] = hashlib.sha256(_canonical(record)).hexdigest() return ContextPacket(record) --- FILE: iepe_core/coordinator.py (263 lines, 9.9 KiB) --- """Deterministic reference state machine for the IEPE operational coordinator.""" from __future__ import annotations from dataclasses import dataclass, field from enum import Enum from typing import Any class CoordinatorState(str, Enum): PREFLIGHT = "preflight" RECONCILE = "reconcile" SELECT = "select" VALIDATE = "validate" CLAIM = "claim" ASSEMBLE_CONTEXT = "assemble_context" DISPATCH = "dispatch" OBSERVE = "observe" EVALUATE = "evaluate" DISPOSITION = "disposition" RECORD = "record" CLOSE_LOOP = "close_loop" COMPLETE = "complete" STOPPED = "stopped" WAITING_EXTERNAL = "waiting_external" class ConditionType(str, Enum): AUTHORIZATION_MISSING = "authorization_missing" CAPABILITY_MISSING = "capability_missing" EVIDENCE_MISSING = "evidence_missing" INPUT_MISSING = "input_missing" WORK_UNAVAILABLE = "work_unavailable" EXTERNAL_EVENT_PENDING = "external_event_pending" @dataclass(frozen=True) class BlockerFingerprint: code: str scope: str required_change: str retryable_by_agent: bool condition_type: ConditionType @property def fingerprint(self) -> str: return f"{self.code}:{self.scope}" class AssertionType(str, Enum): PREFLIGHT_VALID = "preflight.valid" STATE_RECONCILED = "state.reconciled" ISSUE_SELECTED = "issue.selected" ISSUE_READY = "issue.ready" CLAIM_VALID = "claim.valid" CONTEXT_BOUNDED = "context.bounded" WORKER_DISPATCHED = "worker.dispatched" WORKER_RESULT = "worker.result" EVALUATION_COMPLETE = "evaluation.complete" DISPOSITION_SELECTED = "disposition.selected" RECORD_PERSISTED = "record.persisted" CLAIM_RELEASED = "claim.released" ORDERED_PATH = ( CoordinatorState.PREFLIGHT, CoordinatorState.RECONCILE, CoordinatorState.SELECT, CoordinatorState.VALIDATE, CoordinatorState.CLAIM, CoordinatorState.ASSEMBLE_CONTEXT, CoordinatorState.DISPATCH, CoordinatorState.OBSERVE, CoordinatorState.EVALUATE, CoordinatorState.DISPOSITION, CoordinatorState.RECORD, CoordinatorState.CLOSE_LOOP, CoordinatorState.COMPLETE, ) ALLOWED_TRANSITIONS = { current: {ORDERED_PATH[index + 1], CoordinatorState.STOPPED, CoordinatorState.WAITING_EXTERNAL} for index, current in enumerate(ORDERED_PATH[:-1]) } ALLOWED_TRANSITIONS[CoordinatorState.COMPLETE] = set() ALLOWED_TRANSITIONS[CoordinatorState.STOPPED] = set() ALLOWED_TRANSITIONS[CoordinatorState.WAITING_EXTERNAL] = set() @dataclass(frozen=True) class TransitionRecord: sequence: int source: CoordinatorState target: CoordinatorState assertion_ids: tuple[str, ...] @dataclass(frozen=True) class GateAssertion: id: str kind: AssertionType subject: str issuer: str evidence_refs: tuple[str, ...] = () valid: bool = True @dataclass(frozen=True) class StopRecord: state: CoordinatorState reason: str resume_authority: str evidence: tuple[str, ...] = () @dataclass(frozen=True) class ExecutionReceipt: issue_id: str work_type: str final_state: CoordinatorState transitions: tuple[TransitionRecord, ...] stop: StopRecord | None artifacts: tuple[str, ...] assertions: tuple[GateAssertion, ...] @property def assertion_ids(self) -> tuple[str, ...]: return tuple(assertion.id for assertion in self.assertions) @dataclass class Coordinator: issue_id: str work_type: str state: CoordinatorState = CoordinatorState.PREFLIGHT history: list[TransitionRecord] = field(default_factory=list) stop_record: StopRecord | None = None artifacts: list[str] = field(default_factory=list) retained_assertions: list[GateAssertion] = field(default_factory=list) last_blocker_fingerprint: str | None = None def transition(self, target: CoordinatorState, *, assertions: list[GateAssertion] | None = None) -> None: assertions = assertions or [] if target not in ALLOWED_TRANSITIONS[self.state]: raise ValueError(f"Invalid coordinator transition: {self.state.value} -> {target.value}") self._enforce_gate(target, assertions) source = self.state self.state = target self.history.append( TransitionRecord( sequence=len(self.history) + 1, source=source, target=target, assertion_ids=tuple(assertion.id for assertion in assertions), ) ) self.retained_assertions.extend(assertions) def stop(self, reason: str, resume_authority: str, *, evidence: list[str] | None = None) -> None: if self.state in {CoordinatorState.COMPLETE, CoordinatorState.STOPPED, CoordinatorState.WAITING_EXTERNAL}: raise ValueError(f"Cannot stop coordinator from {self.state.value}") evidence = evidence or [] stopped_from = self.state self.transition(CoordinatorState.STOPPED) self.stop_record = StopRecord( state=stopped_from, reason=reason, resume_authority=resume_authority, evidence=tuple(evidence), ) def park_waiting_external(self, blocker: BlockerFingerprint, resume_authority: str) -> None: if self.last_blocker_fingerprint == blocker.fingerprint and not blocker.retryable_by_agent: raise ValueError(f"Duplicate non-retryable blocker fingerprint '{blocker.fingerprint}': do not retry") if self.state in {CoordinatorState.COMPLETE, CoordinatorState.STOPPED, CoordinatorState.WAITING_EXTERNAL}: raise ValueError(f"Cannot park coordinator from {self.state.value}") self.last_blocker_fingerprint = blocker.fingerprint stopped_from = self.state self.transition(CoordinatorState.WAITING_EXTERNAL) self.stop_record = StopRecord( state=stopped_from, reason=f"[{blocker.condition_type.value}] {blocker.code}: {blocker.required_change}", resume_authority=resume_authority, evidence=(f"fingerprint:{blocker.fingerprint}",), ) def add_artifact(self, artifact_ref: str) -> None: if self.state in {CoordinatorState.PREFLIGHT, CoordinatorState.RECONCILE, CoordinatorState.SELECT}: raise ValueError("Artifacts cannot be accepted before issue validation") self.artifacts.append(artifact_ref) def receipt(self) -> ExecutionReceipt: if self.state not in {CoordinatorState.COMPLETE, CoordinatorState.STOPPED, CoordinatorState.WAITING_EXTERNAL}: raise ValueError("A receipt requires a terminal coordinator state") return ExecutionReceipt( issue_id=self.issue_id, work_type=self.work_type, final_state=self.state, transitions=tuple(self.history), stop=self.stop_record, artifacts=tuple(self.artifacts), assertions=tuple(self.retained_assertions), ) def _enforce_gate(self, target: CoordinatorState, assertions: list[GateAssertion]) -> None: required = { CoordinatorState.RECONCILE: AssertionType.PREFLIGHT_VALID, CoordinatorState.SELECT: AssertionType.STATE_RECONCILED, CoordinatorState.VALIDATE: AssertionType.ISSUE_SELECTED, CoordinatorState.CLAIM: AssertionType.ISSUE_READY, CoordinatorState.ASSEMBLE_CONTEXT: AssertionType.CLAIM_VALID, CoordinatorState.DISPATCH: AssertionType.CONTEXT_BOUNDED, CoordinatorState.OBSERVE: AssertionType.WORKER_DISPATCHED, CoordinatorState.EVALUATE: AssertionType.WORKER_RESULT, CoordinatorState.DISPOSITION: AssertionType.EVALUATION_COMPLETE, CoordinatorState.RECORD: AssertionType.DISPOSITION_SELECTED, CoordinatorState.CLOSE_LOOP: AssertionType.RECORD_PERSISTED, CoordinatorState.COMPLETE: AssertionType.CLAIM_RELEASED, }.get(target) if not required: return matching = [assertion for assertion in assertions if assertion.kind is required] if not matching: raise ValueError(f"Transition to {target.value} requires assertion: {required.value}") assertion = matching[0] if assertion.subject != self.issue_id: raise ValueError(f"Assertion {assertion.id} has the wrong subject") if not assertion.valid: raise ValueError(f"Assertion {assertion.id} is invalid") def make_assertion(kind: AssertionType, issue_id: str, *, valid: bool = True) -> GateAssertion: return GateAssertion( id=f"assertion.{issue_id}.{kind.value}", kind=kind, subject=issue_id, issuer="coordinator.reference-evaluator", evidence_refs=(f"evidence.{issue_id}.{kind.value}",), valid=valid, ) def simulate_valid_cycle(issue_id: str, work_type: str) -> ExecutionReceipt: coordinator = Coordinator(issue_id=issue_id, work_type=work_type) path = ( (CoordinatorState.RECONCILE, AssertionType.PREFLIGHT_VALID), (CoordinatorState.SELECT, AssertionType.STATE_RECONCILED), (CoordinatorState.VALIDATE, AssertionType.ISSUE_SELECTED), (CoordinatorState.CLAIM, AssertionType.ISSUE_READY), (CoordinatorState.ASSEMBLE_CONTEXT, AssertionType.CLAIM_VALID), (CoordinatorState.DISPATCH, AssertionType.CONTEXT_BOUNDED), (CoordinatorState.OBSERVE, AssertionType.WORKER_DISPATCHED), (CoordinatorState.EVALUATE, AssertionType.WORKER_RESULT), (CoordinatorState.DISPOSITION, AssertionType.EVALUATION_COMPLETE), (CoordinatorState.RECORD, AssertionType.DISPOSITION_SELECTED), (CoordinatorState.CLOSE_LOOP, AssertionType.RECORD_PERSISTED), (CoordinatorState.COMPLETE, AssertionType.CLAIM_RELEASED), ) for state, assertion_type in path: coordinator.transition(state, assertions=[make_assertion(assertion_type, issue_id)]) if state is CoordinatorState.EVALUATE: coordinator.add_artifact(f"artifact.{issue_id}") return coordinator.receipt() --- FILE: iepe_core/dispatch.py (127 lines, 4.7 KiB) --- """Provider-neutral worker dispatch and result provenance.""" from __future__ import annotations from dataclasses import dataclass from datetime import datetime from enum import Enum from .claims import ClaimRegistry from .context import ContextPacket class WorkerOutcome(str, Enum): COMPLETED = "completed" FAILED = "failed" BLOCKED = "blocked" STOPPED = "stopped" @dataclass(frozen=True) class DispatchEnvelope: id: str issue_id: str claim_id: str context_sha256: str worker_id: str role: str attempt: int permissions: tuple[tuple[str, bool], ...] @dataclass(frozen=True) class WorkerResult: dispatch_id: str issue_id: str claim_id: str context_sha256: str worker_id: str attempt: int outcome: WorkerOutcome artifacts: tuple[str, ...] = () observations: tuple[str, ...] = () commands: tuple[str, ...] = () cost: float | None = None limitations: tuple[str, ...] = () class DispatchRegistry: def __init__(self) -> None: self._dispatches: dict[str, DispatchEnvelope] = {} self._results: dict[str, WorkerResult] = {} def dispatch( self, envelope: DispatchEnvelope, *, packet: ContextPacket, claims: ClaimRegistry, now: datetime, ) -> None: if envelope.id in self._dispatches: raise ValueError(f"Duplicate dispatch: {envelope.id}") if envelope.attempt < 1: raise ValueError("Dispatch attempt must be positive") record = packet.record if envelope.issue_id != record["issueId"] or envelope.claim_id != record["claimId"]: raise ValueError("Dispatch subject does not match context packet") if envelope.context_sha256 != packet.digest: raise ValueError("Dispatch context is stale or mismatched") if not claims.claim_assertion(envelope.claim_id, issue_id=envelope.issue_id, now=now).valid: raise ValueError("Dispatch requires a matching active claim") packet_permissions = record["permissions"] for name, value in envelope.permissions: if value and not packet_permissions.get(name, False): raise ValueError(f"Dispatch permission expansion: {name}") related = [item for item in self._dispatches.values() if item.issue_id == envelope.issue_id] if related: highest = max(item.attempt for item in related) previous = [item for item in related if item.attempt == highest][0] if previous.id not in self._results: raise ValueError("Previous dispatch is still active") if envelope.attempt != highest + 1: raise ValueError("Retry attempt must follow prior attempt") elif envelope.attempt != 1: raise ValueError("First dispatch must be attempt one") self._dispatches[envelope.id] = envelope def accept_result(self, result: WorkerResult) -> dict: envelope = self._dispatches.get(result.dispatch_id) if envelope is None: raise ValueError("Result references an unknown dispatch") if result.dispatch_id in self._results: raise ValueError("Duplicate worker result") expected = (envelope.issue_id, envelope.claim_id, envelope.context_sha256, envelope.worker_id, envelope.attempt) actual = (result.issue_id, result.claim_id, result.context_sha256, result.worker_id, result.attempt) if actual != expected: raise ValueError("Worker result provenance does not match dispatch") if result.cost is not None and result.cost < 0: raise ValueError("Worker result cost cannot be negative") self._results[result.dispatch_id] = result return self.record(result.dispatch_id) def record(self, dispatch_id: str) -> dict: envelope = self._dispatches[dispatch_id] result = self._results.get(dispatch_id) return { "$schema": "../schemas/worker-dispatch.schema.json", "id": envelope.id, "issueId": envelope.issue_id, "claimId": envelope.claim_id, "contextSha256": envelope.context_sha256, "workerId": envelope.worker_id, "role": envelope.role, "attempt": envelope.attempt, "permissions": {key: value for key, value in sorted(envelope.permissions)}, "status": result.outcome.value if result else "active", "result": None if result is None else { "artifacts": list(result.artifacts), "observations": list(result.observations), "commands": list(result.commands), "cost": result.cost, "limitations": list(result.limitations), }, } --- FILE: iepe_core/receipts.py (164 lines, 6.8 KiB) --- """Deterministic persistence and replay validation for coordinator receipts.""" from __future__ import annotations import hashlib import json from typing import Any from .coordinator import ALLOWED_TRANSITIONS, AssertionType, CoordinatorState, ExecutionReceipt RECEIPT_FORMAT = "iepe.coordinator-receipt" RECEIPT_VERSION = 1 REQUIRED_ASSERTIONS = { CoordinatorState.RECONCILE: AssertionType.PREFLIGHT_VALID, CoordinatorState.SELECT: AssertionType.STATE_RECONCILED, CoordinatorState.VALIDATE: AssertionType.ISSUE_SELECTED, CoordinatorState.CLAIM: AssertionType.ISSUE_READY, CoordinatorState.ASSEMBLE_CONTEXT: AssertionType.CLAIM_VALID, CoordinatorState.DISPATCH: AssertionType.CONTEXT_BOUNDED, CoordinatorState.OBSERVE: AssertionType.WORKER_DISPATCHED, CoordinatorState.EVALUATE: AssertionType.WORKER_RESULT, CoordinatorState.DISPOSITION: AssertionType.EVALUATION_COMPLETE, CoordinatorState.RECORD: AssertionType.DISPOSITION_SELECTED, CoordinatorState.CLOSE_LOOP: AssertionType.RECORD_PERSISTED, CoordinatorState.COMPLETE: AssertionType.CLAIM_RELEASED, } def canonical_bytes(value: Any) -> bytes: return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8") def digest_payload(payload: dict[str, Any]) -> str: return hashlib.sha256(canonical_bytes(payload)).hexdigest() def receipt_payload(receipt: ExecutionReceipt) -> dict[str, Any]: return { "issueId": receipt.issue_id, "workType": receipt.work_type, "finalState": receipt.final_state.value, "transitions": [ { "sequence": transition.sequence, "source": transition.source.value, "target": transition.target.value, "assertionIds": list(transition.assertion_ids), } for transition in receipt.transitions ], "assertions": [ { "id": assertion.id, "kind": assertion.kind.value, "subject": assertion.subject, "issuer": assertion.issuer, "evidenceRefs": list(assertion.evidence_refs), "valid": assertion.valid, } for assertion in receipt.assertions ], "stop": None if receipt.stop is None else { "state": receipt.stop.state.value, "reason": receipt.stop.reason, "resumeAuthority": receipt.stop.resume_authority, "evidence": list(receipt.stop.evidence), }, "artifacts": list(receipt.artifacts), } def seal_payload(payload: dict[str, Any]) -> dict[str, Any]: return { "format": RECEIPT_FORMAT, "version": RECEIPT_VERSION, "payload": payload, "sha256": digest_payload(payload), } def seal_receipt(receipt: ExecutionReceipt) -> dict[str, Any]: return seal_payload(receipt_payload(receipt)) def serialize_receipt(receipt: ExecutionReceipt) -> bytes: return canonical_bytes(seal_receipt(receipt)) def load_and_validate_receipt(data: bytes | str) -> dict[str, Any]: envelope = json.loads(data) if envelope.get("format") != RECEIPT_FORMAT: raise ValueError("Unsupported receipt format") if envelope.get("version") != RECEIPT_VERSION: raise ValueError("Unsupported receipt version") payload = envelope.get("payload") if not isinstance(payload, dict): raise ValueError("Receipt payload is missing") if envelope.get("sha256") != digest_payload(payload): raise ValueError("Receipt integrity check failed") validate_replay(payload) return envelope def validate_replay(payload: dict[str, Any]) -> None: issue_id = payload.get("issueId") transitions = payload.get("transitions") assertion_rows = payload.get("assertions") if not isinstance(issue_id, str) or not issue_id: raise ValueError("Receipt issue identity is missing") if not isinstance(transitions, list) or not transitions: raise ValueError("Receipt transition history is missing") if not isinstance(assertion_rows, list): raise ValueError("Receipt assertions are missing") assertions: dict[str, dict[str, Any]] = {} for assertion in assertion_rows: assertion_id = assertion.get("id") if not isinstance(assertion_id, str) or assertion_id in assertions: raise ValueError("Receipt assertion identity is missing or duplicated") assertions[assertion_id] = assertion expected_source = CoordinatorState.PREFLIGHT for index, transition in enumerate(transitions, start=1): if transition.get("sequence") != index: raise ValueError("Receipt transition sequence is invalid") source = CoordinatorState(transition.get("source")) target = CoordinatorState(transition.get("target")) if source is not expected_source: raise ValueError("Receipt transition history is discontinuous") if target not in ALLOWED_TRANSITIONS[source]: raise ValueError("Receipt contains an impossible transition") required = REQUIRED_ASSERTIONS.get(target) transition_assertions = [assertions.get(value) for value in transition.get("assertionIds", [])] if any(assertion is None for assertion in transition_assertions): raise ValueError("Receipt transition references an unknown assertion") if required: matching = [assertion for assertion in transition_assertions if assertion["kind"] == required.value] if not matching: raise ValueError(f"Receipt transition lacks required assertion: {required.value}") assertion = matching[0] if assertion.get("subject") != issue_id: raise ValueError("Receipt assertion has the wrong subject") if assertion.get("valid") is not True: raise ValueError("Receipt assertion is invalid") if not assertion.get("issuer") or not assertion.get("evidenceRefs"): raise ValueError("Receipt assertion provenance is incomplete") expected_source = target final_state = CoordinatorState(payload.get("finalState")) if expected_source is not final_state: raise ValueError("Receipt final state does not match transition history") if final_state not in {CoordinatorState.COMPLETE, CoordinatorState.STOPPED, CoordinatorState.WAITING_EXTERNAL}: raise ValueError("Receipt final state is not terminal") stop = payload.get("stop") if final_state in {CoordinatorState.STOPPED, CoordinatorState.WAITING_EXTERNAL}: if not isinstance(stop, dict) or not stop.get("reason") or not stop.get("resumeAuthority"): raise ValueError("Stopped receipt is missing its stop record") elif stop is not None: raise ValueError("Completed receipt cannot contain a stop record") ======================================================================== ## SUBSYSTEM: CORE TOOLS & UTILITIES (3 files) ======================================================================== --- FILE: tools/compile_package.py (123 lines, 4.8 KiB) --- #!/usr/bin/env python3 """Compile canonical project sources into a deterministic Agent Project Package.""" from __future__ import annotations import argparse import hashlib import json from pathlib import Path OUTPUTS = ("AGENTS.md", "context-index.md", "context-full.md") FORBIDDEN_PARTS = {"__MACOSX", "__pycache__", ".git"} FORBIDDEN_SUFFIXES = {".pyc", ".pyo"} def canonical_json(value: object) -> bytes: return (json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False) + "\n").encode() def digest(data: bytes) -> str: return hashlib.sha256(data).hexdigest() def safe_source(root: Path, relative: str) -> Path: candidate = Path(relative) if candidate.is_absolute() or ".." in candidate.parts: raise ValueError(f"Unsafe source path: {relative}") if any(part in FORBIDDEN_PARTS for part in candidate.parts) or candidate.suffix in FORBIDDEN_SUFFIXES: raise ValueError(f"Excluded source path: {relative}") resolved = (root / candidate).resolve() if root.resolve() not in resolved.parents and resolved != root.resolve(): raise ValueError(f"Source escapes project root: {relative}") if not resolved.is_file(): raise ValueError(f"Missing source: {relative}") return resolved def compile_package(config_path: Path, output_dir: Path) -> dict: config = json.loads(config_path.read_text(encoding="utf-8")) root = (config_path.parent / config.get("projectRoot", ".")).resolve() if config["releaseClass"] == "release" and config["sourceState"] != "clean": raise ValueError("Release packages require clean source state") declared = config["sources"] paths = [item["path"] for item in declared] if len(paths) != len(set(paths)): raise ValueError("Duplicate source path") if config["operatingContract"] not in paths: raise ValueError("Operating contract must be a declared source") source_records = [] bodies = [] for item in sorted(declared, key=lambda value: (value["authorityRank"], value["path"])): path = safe_source(root, item["path"]) data = path.read_bytes() source_records.append({ "path": item["path"], "role": item["role"], "authorityRank": item["authorityRank"], "bytes": len(data), "sha256": digest(data), }) text = data.decode("utf-8") bodies.append(f"--- SOURCE: {item['path']} | ROLE: {item['role']} | AUTHORITY: {item['authorityRank']} ---\n{text.rstrip()}\n") operating_data = safe_source(root, config["operatingContract"]).read_bytes() index_lines = [ f"# {config['packageId']} Context Index", "", f"> Package version: {config['packageVersion']}", f"> Source state: {config['sourceState']}", "", ] for record in source_records: index_lines.append( f"- `{record['path']}` | {record['role']} | authority {record['authorityRank']} | " f"{record['bytes']} bytes | `{record['sha256']}`" ) index_data = ("\n".join(index_lines) + "\n").encode() full_data = (f"# {config['packageId']} Compiled Context\n\n" + "\n".join(bodies)).encode() output_dir.mkdir(parents=True, exist_ok=True) generated = {"AGENTS.md": operating_data, "context-index.md": index_data, "context-full.md": full_data} for name, data in generated.items(): (output_dir / name).write_bytes(data) output_records = [ {"path": name, "bytes": len(generated[name]), "sha256": digest(generated[name])} for name in OUTPUTS ] payload = b"".join(name.encode() + b"\0" + generated[name] for name in OUTPUTS) manifest = { "$schema": config.get("manifestSchema", "https://iepe.dev/schema/agent-package-manifest.schema.json"), "formatVersion": "1", "packageId": config["packageId"], "packageVersion": config["packageVersion"], "protocol": config["protocol"], "releaseClass": config["releaseClass"], "sourceState": config["sourceState"], "operatingContract": config["operatingContract"], "sources": source_records, "skills": sorted(config.get("skills", [])), "adapters": sorted(config.get("adapters", [])), "outputs": output_records, "exclusions": sorted(config.get("exclusions", [])), "payloadSha256": digest(payload), } (output_dir / "agent-package-manifest.json").write_bytes(canonical_json(manifest)) return manifest def main() -> int: parser = argparse.ArgumentParser() parser.add_argument("--config", type=Path, required=True) parser.add_argument("--output", type=Path, required=True) args = parser.parse_args() compile_package(args.config.resolve(), args.output.resolve()) return 0 if __name__ == "__main__": raise SystemExit(main()) --- FILE: tools/init_project.py (73 lines, 3.0 KiB) --- #!/usr/bin/env python3 """Initialize a new IEPE project or inspect an existing project without mutation.""" from __future__ import annotations import argparse import json from pathlib import Path import sys sys.path.insert(0, str(Path(__file__).resolve().parents[1])) from iepe_core.bootstrap import BootstrapConfig, discover_existing, initialize_new def parser() -> argparse.ArgumentParser: root = argparse.ArgumentParser() commands = root.add_subparsers(dest="mode", required=True) new = commands.add_parser("new") new.add_argument("--project-root", type=Path, required=True) new.add_argument("--project-id", required=True) new.add_argument("--project-name", required=True) new.add_argument("--intent", required=True) new.add_argument("--protocol-source", required=True) new.add_argument("--protocol-revision", required=True) new.add_argument("--protocol-version", default="0.2.0") new.add_argument("--work-graph-provider", default="local") new.add_argument("--project-ref", default="work") new.add_argument("--coordinator-identity", default="coordinator.local") new.add_argument("--coordinator-capacity", type=int, default=1) new.add_argument("--evaluator", action="append", default=[]) new.add_argument("--promotion-authority", action="append", default=[]) new.add_argument("--overwrite", action="store_true") existing = commands.add_parser("existing") existing.add_argument("--project-root", type=Path, required=True) existing.add_argument("--report", type=Path) return root def main() -> int: args = parser().parse_args() if args.mode == "existing": report = json.dumps(discover_existing(args.project_root), sort_keys=True, indent=2) + "\n" if args.report: if args.report.exists(): raise FileExistsError(f"Refusing to overwrite report: {args.report}") args.report.parent.mkdir(parents=True, exist_ok=True) args.report.write_text(report, encoding="utf-8") else: print(report, end="") return 0 config = BootstrapConfig( project_id=args.project_id, project_name=args.project_name, intent=args.intent, protocol_source=args.protocol_source, protocol_revision=args.protocol_revision, protocol_version=args.protocol_version, work_graph_provider=args.work_graph_provider, project_ref=args.project_ref, coordinator_identity=args.coordinator_identity, coordinator_capacity=args.coordinator_capacity, evaluators=tuple(args.evaluator or ["manual.acceptance"]), promotion_authorities=tuple(args.promotion_authority or ["project.owner"]), ) written = initialize_new(args.project_root, config, overwrite=args.overwrite) print(json.dumps({"mode": "new", "projectRoot": str(args.project_root.resolve()), "files": [str(path) for path in written]}, indent=2)) return 0 if __name__ == "__main__": raise SystemExit(main()) --- FILE: tools/validate.py (168 lines, 6.2 KiB) --- #!/usr/bin/env python3 from __future__ import annotations import json import os import re import subprocess import sys from pathlib import Path import yaml from jsonschema import Draft202012Validator ROOT = Path(__file__).resolve().parents[1] SCHEMA_DIR = ROOT / "schemas" TEMPLATE_DIR = ROOT / ".github" / "ISSUE_TEMPLATE" SKILL_DIR = ROOT / ".agents" / "skills" EVIDENCE_DIR = ROOT / "evidence" FIXTURE_PATH = ROOT / "fixtures" / "conformance.json" TEXT_SUFFIXES = {".md", ".json", ".yml", ".yaml", ".py", ".txt"} PLACEHOLDER_PATTERNS = (rf"\b{'TO' + 'DO'}\b", rf"\b{'T' + 'BD'}\b") def fail(message: str) -> None: raise AssertionError(message) def load_json(path: Path) -> object: return json.loads(path.read_text(encoding="utf-8")) def validate_schemas() -> dict[str, dict]: schemas: dict[str, dict] = {} for path in sorted(SCHEMA_DIR.glob("*.json")): schema = load_json(path) Draft202012Validator.check_schema(schema) schemas[path.name] = schema ids = [schema["$id"] for schema in schemas.values()] if len(ids) != len(set(ids)): fail("Schema $id values must be unique") fixtures = load_json(FIXTURE_PATH) if set(fixtures) != set(schemas): fail("Every schema must have exactly one named conformance fixture") for name, schema in schemas.items(): validator = Draft202012Validator(schema) validator.validate(fixtures[name]) if not list(validator.iter_errors({})): fail(f"{name} accepted the empty negative fixture") return schemas def validate_evidence(schemas: dict[str, dict]) -> int: validator = Draft202012Validator(schemas["evidence-bundle.schema.json"]) paths = sorted(EVIDENCE_DIR.glob("*.json")) for path in paths: validator.validate(load_json(path)) return len(paths) def validate_examples() -> int: record_count = 0 for manifest_path in sorted((ROOT / "examples").glob("*/conformance-manifest.json")): manifest = load_json(manifest_path) for schema_ref, record_refs in manifest.items(): schema_path = (manifest_path.parent / schema_ref).resolve() schema = load_json(schema_path) if isinstance(record_refs, str): record_refs = [record_refs] for record_ref in record_refs: record_path = (manifest_path.parent / record_ref).resolve() if ROOT.resolve() not in schema_path.parents or ROOT.resolve() not in record_path.parents: fail(f"{manifest_path} contains a path outside the project root") record = load_json(record_path) Draft202012Validator(schema).validate(record) record_count += 1 return record_count def validate_templates() -> int: paths = sorted(TEMPLATE_DIR.glob("*.yml")) for path in paths: document = yaml.safe_load(path.read_text(encoding="utf-8")) if not document.get("name") or not document.get("description") or not document.get("body"): fail(f"{path.name} is missing required template structure") ids = [item.get("id") for item in document["body"] if item.get("id")] if len(ids) != len(set(ids)): fail(f"{path.name} contains duplicate body IDs") return len(paths) def validate_skills() -> int: paths = sorted(SKILL_DIR.glob("*/SKILL.md")) if not paths: fail("No IEPE process skills found") for path in paths: text = path.read_text(encoding="utf-8") match = re.match(r"\A---\n(.*?)\n---\n", text, re.S) if not match: fail(f"{path} has invalid skill frontmatter") metadata = yaml.safe_load(match.group(1)) if set(metadata) != {"name", "description"}: fail(f"{path} skill metadata must contain only name and description") if metadata["name"] != path.parent.name or not re.fullmatch(r"[a-z0-9-]+", metadata["name"]): fail(f"{path} has invalid or mismatched skill name") if not metadata["description"].strip(): fail(f"{path} has an empty skill description") return len(paths) def validate_domain_neutrality() -> None: project_terms = [term.strip() for term in os.getenv("IEPE_FORBIDDEN_TERMS", "").split(",") if term.strip()] forbidden_patterns = PLACEHOLDER_PATTERNS + tuple(re.escape(term) for term in project_terms) violations: list[str] = [] for path in ROOT.rglob("*"): if not path.is_file() or path.suffix not in TEXT_SUFFIXES: continue text = path.read_text(encoding="utf-8") for pattern in forbidden_patterns: if re.search(pattern, text): violations.append(f"{path.relative_to(ROOT)}: {pattern}") if violations: fail("Domain-neutrality audit failed:\n" + "\n".join(violations)) def validate_reference_tests() -> str: completed = subprocess.run( [sys.executable, "-m", "unittest", "discover", "-s", "tests", "-v"], cwd=ROOT, text=True, capture_output=True, check=False, ) if completed.returncode != 0: fail("Reference tests failed:\n" + completed.stdout + completed.stderr) return completed.stdout + completed.stderr def main() -> int: try: schemas = validate_schemas() evidence_count = validate_evidence(schemas) example_record_count = validate_examples() template_count = validate_templates() skill_count = validate_skills() validate_domain_neutrality() reference_test_output = validate_reference_tests() except Exception as error: print(f"IEPE conformance failed: {error}", file=sys.stderr) return 1 print(f"IEPE conformance passed: {len(schemas)} schemas") print(f"IEPE conformance passed: {template_count} issue templates") print(f"IEPE conformance passed: {skill_count} process skills") print(f"IEPE conformance passed: {evidence_count} evidence bundles") print(f"IEPE conformance passed: {example_record_count} example records") print("IEPE conformance passed: domain-neutrality audit") print(f"IEPE conformance passed: reference tests ({reference_test_output.count(' ... ok')} cases)") return 0 if __name__ == "__main__": raise SystemExit(main()) ======================================================================== ## SUBSYSTEM: EXAMPLES & PROTOCOL FIXTURES (38 files) ======================================================================== --- FILE: examples/agent-package/conformance-manifest.json (3 lines, 0.1 KiB) --- { "../../schemas/agent-package-manifest.schema.json": "output/agent-package-manifest.json" } --- FILE: examples/agent-package/output/AGENTS.md (3 lines, 0.3 KiB) --- # Example Operating Contract Intent governs implementation. Issues authorize work. Generated package artifacts are non-authoritative projections of declared canonical sources. Stop when authority, ownership, permissions, or required evidence becomes ambiguous. --- FILE: examples/agent-package/output/agent-package-manifest.json (1 lines, 1.4 KiB) --- {"$schema":"../../../schemas/agent-package-manifest.schema.json","adapters":["work-graph.example"],"exclusions":["*.pyc",".git","__MACOSX","__pycache__","undeclared files"],"formatVersion":"1","operatingContract":"OPERATING.md","outputs":[{"bytes":262,"path":"AGENTS.md","sha256":"92a5be1dae475b0cdaf6d09a004064e775e22f104663925b8fc18611ad51fe79"},{"bytes":462,"path":"context-index.md","sha256":"c3b9ad7b81cdb676ed1a4bf2a223a1285af3e7ff6d833237d12ebc21e5aad95a"},{"bytes":749,"path":"context-full.md","sha256":"927002bac7036e0a1d279d32342e2258db018f363cb19db9d0a1419f84258147"}],"packageId":"project.example.agent-package","packageVersion":"0.1.0","payloadSha256":"a81897983cbf0ce0e8e4ce6178939b56a5b7e6ec5ead1ac8959a0cc281c2bb3b","protocol":{"protocolId":"IEPE-001","protocolVersion":"0.1.0","revision":"v0.1.0-example","source":"../../../"},"releaseClass":"release","skills":["documentation-alignment","evidence-closure","issue-grooming"],"sourceState":"clean","sources":[{"authorityRank":1,"bytes":112,"path":"INTENT.md","role":"intent","sha256":"fb601d888fa02eb650c946c3fa0c2064c15045583b513e60c5397edf167b3d2b"},{"authorityRank":2,"bytes":262,"path":"OPERATING.md","role":"doctrine","sha256":"92a5be1dae475b0cdaf6d09a004064e775e22f104663925b8fc18611ad51fe79"},{"authorityRank":3,"bytes":142,"path":"OPERATIONS.md","role":"operations","sha256":"afddc6905006765eba56258d36c89b9f746fb87f7b743ea1a1cdee64aa2ba28c"}]} --- FILE: examples/agent-package/output/context-full.md (16 lines, 0.7 KiB) --- # project.example.agent-package Compiled Context --- SOURCE: INTENT.md | ROLE: intent | AUTHORITY: 1 --- # Example Intent Demonstrate deterministic project packaging without importing a product or provider ontology. --- SOURCE: OPERATING.md | ROLE: doctrine | AUTHORITY: 2 --- # Example Operating Contract Intent governs implementation. Issues authorize work. Generated package artifacts are non-authoritative projections of declared canonical sources. Stop when authority, ownership, permissions, or required evidence becomes ambiguous. --- SOURCE: OPERATIONS.md | ROLE: operations | AUTHORITY: 3 --- # Example Operations Workers receive bounded context selected from the compiled package. Promotion requires declared evidence and authority. --- FILE: examples/agent-package/output/context-index.md (8 lines, 0.5 KiB) --- # project.example.agent-package Context Index > Package version: 0.1.0 > Source state: clean - `INTENT.md` | intent | authority 1 | 112 bytes | `fb601d888fa02eb650c946c3fa0c2064c15045583b513e60c5397edf167b3d2b` - `OPERATING.md` | doctrine | authority 2 | 262 bytes | `92a5be1dae475b0cdaf6d09a004064e775e22f104663925b8fc18611ad51fe79` - `OPERATIONS.md` | operations | authority 3 | 142 bytes | `afddc6905006765eba56258d36c89b9f746fb87f7b743ea1a1cdee64aa2ba28c` --- FILE: examples/agent-package/package-source.json (19 lines, 0.9 KiB) --- { "$schema": "../../../schemas/agent-package-source.schema.json", "manifestSchema": "../../../schemas/agent-package-manifest.schema.json", "packageId": "project.example.agent-package", "packageVersion": "0.1.0", "protocol": {"protocolId": "IEPE-001", "protocolVersion": "0.1.0", "source": "../../../", "revision": "v0.1.0-example"}, "projectRoot": "project", "releaseClass": "release", "sourceState": "clean", "operatingContract": "OPERATING.md", "sources": [ {"path": "INTENT.md", "role": "intent", "authorityRank": 1}, {"path": "OPERATING.md", "role": "doctrine", "authorityRank": 2}, {"path": "OPERATIONS.md", "role": "operations", "authorityRank": 3} ], "skills": ["documentation-alignment", "evidence-closure", "issue-grooming"], "adapters": ["work-graph.example"], "exclusions": ["__MACOSX", "__pycache__", "*.pyc", ".git", "undeclared files"] } --- FILE: examples/agent-package/project/INTENT.md (3 lines, 0.1 KiB) --- # Example Intent Demonstrate deterministic project packaging without importing a product or provider ontology. --- FILE: examples/agent-package/project/OPERATING.md (3 lines, 0.3 KiB) --- # Example Operating Contract Intent governs implementation. Issues authorize work. Generated package artifacts are non-authoritative projections of declared canonical sources. Stop when authority, ownership, permissions, or required evidence becomes ambiguous. --- FILE: examples/agent-package/project/OPERATIONS.md (3 lines, 0.1 KiB) --- # Example Operations Workers receive bounded context selected from the compiled package. Promotion requires declared evidence and authority. --- FILE: examples/exhibition-guide/INTENT.md (25 lines, 0.7 KiB) --- # Project Intent ## Purpose Help a first-time visitor enter a small exhibition with enough orientation to make an independent choice about where to begin. ## Human outcome The visitor understands that there is no required route, recognizes three possible ways to enter the exhibition, and feels permitted to follow personal curiosity. ## Values - Visitor agency - Plain language - Interpretive openness - Physical and cognitive accessibility - Respect for uncertainty ## Prohibited outcomes - Presenting one route as authoritative - Explaining what an artwork is supposed to mean - Requiring prior knowledge - Using urgency or completion pressure - Claiming that the guide has been validated with visitors --- FILE: examples/exhibition-guide/README.md (24 lines, 1.1 KiB) --- # Exhibition Guide Pilot This synthetic pilot tests IEPE against a non-software editorial and experience-design project. The fictional project creates a one-page orientation guide for first-time visitors entering a small exhibition titled **Ways of Seeing Water**. The guide should help visitors choose where to begin without prescribing a correct route or explaining the artworks for them. No real visitors participated. The pilot can test structural intent alignment, editorial constraints, candidate comparison, evidence lineage, and promotion separation. It cannot validate comprehension, emotional quality, accessibility in lived use, or visitor behavior. ## Pilot path ```text Project profile -> Intent and experience contract -> Authorized issue -> Two editorial candidates -> Rule-based evaluation -> Rejected-direction record -> Evidence bundle -> Internal example-baseline promotion ``` ## Qualification The example is **tested** as a protocol and schema exercise. Its visitor experience remains **specified**, not observed or empirically validated. --- FILE: examples/exhibition-guide/baseline.md (5 lines, 0.3 KiB) --- # Baseline The fictional exhibition currently provides only its title at the entrance. No orientation copy, route options, or visitor-facing explanation of navigational freedom exists. This baseline is intentionally minimal. The pilot compares candidate guide structures against the declared intent, not against measured visitor behavior. --- FILE: examples/exhibition-guide/candidates/candidate-a-route-led.md (11 lines, 0.6 KiB) --- # Candidate A: Route-Led ## Begin Here Start with the suspended glass work in the first room. Then continue to the projection beyond the central partition. Finish beside the three drawings near the quiet seating area. The exhibition follows water as material, memory, and movement. Each section develops the idea introduced by the one before it. Allow about twenty minutes for the complete route. If you have less time, visit the glass work and the final drawings. Labels beside each work provide additional context. You may return to the entrance at any point. --- FILE: examples/exhibition-guide/candidates/candidate-b-choice-led.md (19 lines, 0.6 KiB) --- # Candidate B: Choice-Led ## Choose Where to Begin There is no required route through **Ways of Seeing Water**. Begin with the question that feels closest to you. ### What does water hold? Find the three drawings near the quiet seating area. ### How does water change what we see? Look for the suspended glass work in the first room. ### What happens when water becomes time? Enter the projection space beyond the central partition. Move between these works in any order. You can follow one question, change direction, pause, or leave a section unfinished. Labels offer context, but you do not need them to begin. --- FILE: examples/exhibition-guide/conformance-manifest.json (18 lines, 0.9 KiB) --- { "../../schemas/project-profile.schema.json": "records/project-profile.json", "../../schemas/experience-contract.schema.json": "records/experience-contract.json", "../../schemas/issue-contract.schema.json": "records/issue-contract.json", "../../schemas/evaluation-record.schema.json": "records/evaluation-record.json", "../../schemas/evidence-bundle.schema.json": "records/evidence-bundle.json", "../../schemas/promotion-record.schema.json": "records/promotion-record.json", "../../schemas/perturbation.schema.json": [ "stress/perturbation-format-loss.json", "stress/perturbation-artwork-unavailable.json" ], "../../schemas/world-card.schema.json": [ "stress/world-card-format-loss.json", "stress/world-card-artwork-unavailable.json" ], "../../schemas/robustness-profile.schema.json": "stress/robustness-profile.json", "../../schemas/unknown-variable-ledger.schema.json": "stress/unknown-variable-ledger.json" } --- FILE: examples/exhibition-guide/coordinator-trace.md (24 lines, 1.4 KiB) --- # Coordinator Trace | State | Result | | --- | --- | | Preflight | Local workspace, authority, permissions, and evaluator limits resolved | | Reconcile | M1 required a non-software adoption example; no existing example was present | | Select | `IEPE-CORE-004` was Ready and unblocked | | Validate | Intent, hypothesis, acceptance, evidence, constraints, and stop conditions were complete | | Claim | One local claim established for the pilot | | Assemble context | Core protocol, adoption guide, schemas, roadmap, and issue contract selected | | Dispatch | Editorial candidate generation bounded to two iterations and no external side effects | | Observe | Both candidates remained within editorial scope; no stop condition occurred | | Evaluate | Rule-based structural evaluation qualified Candidate B; human evaluation remained unexecuted | | Disposition | Candidate B promoted only to the internal example baseline; Candidate A retained as a negative result | | Record | Evaluation, evidence, promotion, limitations, and negative result persisted | | Close loop | Pilot prepared for conformance; external validation remains explicitly unresolved | ## Context identity The trace applies to IEPE Core v0.1.0 working state during `IEPE-CORE-004`. ## Authority boundary No external publication, communication, deployment, spending, or claim about real visitor behavior occurred. --- FILE: examples/exhibition-guide/negative-results.md (9 lines, 0.6 KiB) --- # Negative Results ## Candidate A: Route-Led Candidate A was rejected for the pilot baseline because it instructs visitors to start, continue, and finish in a curatorial sequence. This contradicts the declared intent to support independent entry and makes the later statement about returning to the entrance insufficient. The direction is not universally invalid. It could be appropriate for an exhibition whose meaning depends on sequence. It is invalid under this project’s current intent and experience contract. The result is retained so future revisions do not repeatedly rediscover that a friendly tone alone does not establish visitor agency. --- FILE: examples/exhibition-guide/records/evaluation-record.json (45 lines, 1.8 KiB) --- { "$schema": "../../../schemas/evaluation-record.schema.json", "id": "evaluation.exhibition-guide.1", "subjectRef": "candidate-set.exhibition-guide.1", "baselineRef": "../baseline.md", "evaluator": "evaluator.editorial-structure", "independence": "partially-independent", "environmentRef": "synthetic editorial evaluation", "dimensions": [ { "name": "route neutrality", "result": { "candidateA": "fail", "candidateB": "pass" }, "threshold": "must not prescribe a required sequence", "evidenceRefs": ["../candidates/candidate-a-route-led.md", "../candidates/candidate-b-choice-led.md"] }, { "name": "visitor agency", "result": { "candidateA": "weak", "candidateB": "strong" }, "threshold": "must provide a meaningful choice at entry", "evidenceRefs": ["../INTENT.md", "experience-contract.json"] }, { "name": "editorial constraints", "result": { "candidateA": "pass", "candidateB": "pass" }, "threshold": "one page, no more than 180 words, plain language", "evidenceRefs": ["../candidates/candidate-a-route-led.md", "../candidates/candidate-b-choice-led.md"] }, { "name": "human comprehension", "result": { "candidateA": "not observed", "candidateB": "not observed" }, "threshold": "requires real visitor observation", "evidenceRefs": ["experience-contract.json"] } ], "tradeoffs": [ "Candidate B gives less curatorial sequence context than Candidate A", "Question-led entry depends on the three questions being legible in the final graphic composition" ], "limitations": [ "No visitor participated", "No printed layout was evaluated", "Accessibility requirements were specified but not observed in use" ], "disposition": "qualify" } --- FILE: examples/exhibition-guide/records/evidence-bundle.json (37 lines, 1.6 KiB) --- { "$schema": "../../../schemas/evidence-bundle.schema.json", "id": "evidence.exhibition-guide.1", "projectId": "project.exhibition-guide", "issueId": "IEPE-CORE-004-PILOT", "candidateId": "candidate-b-choice-led", "artifactRefs": ["../candidates/candidate-b-choice-led.md"], "intentRefs": ["../INTENT.md"], "authorityRefs": ["experience-contract.json", "issue-contract.json"], "environment": { "type": "synthetic editorial pilot", "externalSideEffects": false }, "inputs": ["candidate-a-route-led.md", "candidate-b-choice-led.md"], "provenance": ["IEPE-CORE-004 coordinator cycle"], "evaluations": [ { "dimension": "structural intent alignment", "result": "Candidate B passes route-neutrality and visitor-agency thresholds", "evaluator": "evaluator.editorial-structure", "evidenceRefs": ["evaluation-record.json"] }, { "dimension": "human comprehension", "result": "not observed", "evaluator": "not executed", "evidenceRefs": ["experience-contract.json"] } ], "baselineComparison": { "before": "title only, with no orientation or route options", "after": "three explicit entry choices with freedom to change direction" }, "cost": { "external": 0, "iterations": 2 }, "tradeoffs": ["less curatorial sequence context"], "limitations": ["synthetic example", "no human observation", "no graphic-layout evaluation"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Review both candidate files against INTENT.md and experience-contract.json, then validate all records with the IEPE conformance runner." } --- FILE: examples/exhibition-guide/records/experience-contract.json (36 lines, 1.4 KiB) --- { "$schema": "../../../schemas/experience-contract.schema.json", "id": "experience.exhibition-entry", "intent": "Give a first-time visitor enough orientation to choose an entry path without prescribing interpretation.", "audience": { "primary": "first-time exhibition visitors", "contexts": ["arriving alone", "arriving with companions", "limited attention", "unfamiliar with exhibition conventions"] }, "desiredOutcomes": [ "recognize that no route is required", "identify three possible entry approaches", "make an independent starting choice" ], "experientialQualities": ["calm", "inviting", "open", "legible"], "behaviorsToEncourage": ["choose by curiosity", "change direction freely", "pause without penalty"], "behaviorsToAvoid": ["follow a route from perceived obligation", "treat interpretation as a test"], "states": ["arrival", "orientation", "choice", "entry"], "constraints": [ "one printed page", "maximum 180 words", "plain language", "no mandatory sequence", "no claims about artwork meaning" ], "accessibilityRequirements": [ "headings communicate structure without color", "directions do not rely on left and right alone", "body copy supports large-print reproduction" ], "evidenceRequirements": [ "editorial constraint audit", "route-neutrality audit", "human observation before any comprehension claim" ], "authorityRefs": ["../INTENT.md"] } --- FILE: examples/exhibition-guide/records/issue-contract.json (27 lines, 1.5 KiB) --- { "$schema": "../../../schemas/issue-contract.schema.json", "id": "IEPE-CORE-004-PILOT", "type": "experiment", "title": "Develop the exhibition entry guide", "intentRefs": ["../INTENT.md"], "experienceRefs": ["experience.exhibition-entry"], "objective": "Select a structurally qualified one-page guide from distinct editorial candidates.", "hypothesis": "A choice-led guide will preserve visitor agency more reliably than a route-led guide.", "owner": "coordinator.iepe-core", "workspace": "examples/exhibition-guide", "parent": "IEPE-CORE-004", "dependencies": [], "acceptanceCriteria": [ "at least two structurally different candidates exist", "candidates remain within 180 words", "evaluation retains separate intent-alignment dimensions", "rejected direction and rationale are preserved", "promotion does not claim human validation" ], "evidenceRequired": ["candidate artifacts", "evaluation record", "negative-result record", "evidence bundle", "promotion record"], "constraints": ["synthetic example only", "no external side effects", "no invented visitor observations"], "exclusions": ["graphic production", "printing", "real visitor study", "external publication"], "permissions": { "externalWrites": false, "deployments": false, "communications": false, "spending": false }, "budget": { "time": "one execution cycle", "cost": 0, "iterations": 2 }, "stopConditions": ["candidate requires an unsupported human-outcome claim", "core protocol must be weakened to fit the example"] } --- FILE: examples/exhibition-guide/records/project-profile.json (19 lines, 1.0 KiB) --- { "$schema": "../../../schemas/project-profile.schema.json", "id": "project.exhibition-guide", "name": "Ways of Seeing Water Visitor Guide", "protocol": {"protocolId": "IEPE-001", "protocolVersion": "0.1.0", "source": "../../../", "revision": "v0.1.0-example"}, "intentRefs": ["../INTENT.md"], "authorityOrder": ["../INTENT.md", "experience-contract.json", "issue-contract.json"], "workGraph": { "provider": "local-reference", "projectRefs": ["IEPE-CORE-004"] }, "workspaces": ["examples/exhibition-guide"], "coordinator": { "identity": "coordinator.iepe-core", "capacity": 1, "stopPolicyRef": "../../../AGENTS.md#stop-rule" }, "evaluators": ["evaluator.editorial-structure"], "protectedActions": ["external publication", "claims about visitor behavior"], "promotionAuthorities": ["authority.example-owner"], "memory": { "operational": "coordinator-trace.md", "institutional": "../INTENT.md", "negativeResults": "../negative-results.md" } } --- FILE: examples/exhibition-guide/records/promotion-record.json (14 lines, 0.6 KiB) --- { "$schema": "../../../schemas/promotion-record.schema.json", "id": "promotion.exhibition-guide.1", "subjectRef": "../candidates/candidate-b-choice-led.md", "issueRef": "IEPE-CORE-004-PILOT", "evidenceBundleRef": "evidence-bundle.json", "authority": "authority.example-owner", "decision": "approved", "target": "internal example baseline", "tradeoffs": ["human and layout validation remain unresolved"], "conditions": ["must not be represented as visitor-validated", "requires human observation before external experience claims"], "recoveryPlan": "Restore the title-only baseline or reopen candidate exploration.", "effectiveAt": null } --- FILE: examples/exhibition-guide/stress/perturbation-artwork-unavailable.json (13 lines, 0.6 KiB) --- { "$schema": "../../../schemas/perturbation.schema.json", "id": "perturbation.exhibition.artwork-unavailable", "family": "dependency", "visibility": "revealed", "protectedInvariants": ["visitor agency", "no invented interpretation", "promotion authority"], "changedConditions": ["one referenced artwork is temporarily unavailable"], "revealGate": "candidate-frozen", "evaluationDimensions": ["continued utility", "stale-reference risk", "repair scope"], "severity": "moderate", "recoveryRequired": true, "steward": "perturbation-steward.synthetic" } --- FILE: examples/exhibition-guide/stress/perturbation-format-loss.json (13 lines, 0.6 KiB) --- { "$schema": "../../../schemas/perturbation.schema.json", "id": "perturbation.exhibition.format-loss", "family": "constraint", "visibility": "revealed", "protectedInvariants": ["visitor agency", "no invented interpretation", "promotion authority"], "changedConditions": ["headings and typographic hierarchy are removed during reproduction"], "revealGate": "candidate-frozen", "evaluationDimensions": ["instruction survival", "visitor agency", "factual integrity"], "severity": "moderate", "recoveryRequired": false, "steward": "perturbation-steward.synthetic" } --- FILE: examples/exhibition-guide/stress/robustness-profile.json (27 lines, 1.1 KiB) --- { "$schema": "../../../schemas/robustness-profile.schema.json", "id": "robustness.exhibition.candidate-b.1", "candidateRef": "candidates/candidate-b-choice-led.md#frozen-at-evaluation-1", "knownQualificationRef": "records/evaluation-record.json", "surpriseBudget": { "evaluationShare": 0.15, "minimumWorldCards": 2, "candidateVisibility": "sealed-until-frozen" }, "trials": [ { "worldCardRef": "world.exhibition.format-loss", "disposition": "bounded", "evidenceRefs": ["stress/trial-report.md#trial-1-format-loss"], "limitations": ["synthetic inspection does not establish visitor comprehension"] }, { "worldCardRef": "world.exhibition.artwork-unavailable", "disposition": "adaptable", "evidenceRefs": ["stress/trial-report.md#trial-2-artwork-unavailable"], "limitations": ["repair was analyzed but not field tested"] } ], "validityBoundary": ["all named artworks remain available or the guide is corrected", "basic textual grouping is preserved", "human outcomes remain unvalidated"], "promotionEffect": "constrain" } --- FILE: examples/exhibition-guide/stress/trial-report.md (17 lines, 1.2 KiB) --- # Blind Counterfactual Trial Report ## Freeze record Candidate B was frozen after the known evaluation recorded in `records/evaluation-record.json`. The two World Cards were withheld from candidate production and revealed only after this freeze. This is a synthetic procedural trial, not proof of human outcomes. ## Trial 1: Format loss The wording still explicitly says there is no required route and retains all three invitations. Without grouping, rapid distinction among the invitations is not established. Disposition: **bounded**. The content survives, but its validity narrows to contexts where readers can inspect the full text. ## Trial 2: Artwork unavailable Two entry points remain and the no-required-route instruction survives. The unavailable option becomes stale, so the frozen artifact should not be used unchanged. Removing or replacing one invitation is a bounded, authorized repair that does not alter intent. Disposition: **adaptable**. ## Promotion effect Constrain promotion. The candidate remains synthetically qualified only when named works are available and basic text grouping is preserved. Human comprehension and behavior remain unvalidated. --- FILE: examples/exhibition-guide/stress/unknown-variable-ledger.json (28 lines, 1.1 KiB) --- { "$schema": "../../../schemas/unknown-variable-ledger.schema.json", "id": "unknowns.exhibition-guide.1", "projectRef": "project.exhibition-guide", "entries": [ { "id": "unknown.exhibition.comprehension", "variable": "whether visitors understand and act on the invitation", "classification": "currently-unknowable", "evidenceRefs": [], "nextProbe": "Observe consenting visitors in the intended environment" }, { "id": "unknown.exhibition.format-dependence", "variable": "dependence on typographic hierarchy for rapid scanning", "classification": "discovered-through-perturbation", "evidenceRefs": ["stress/trial-report.md#trial-1-format-loss"], "nextProbe": "Compare plain-text and designed renderings with users" }, { "id": "unknown.exhibition.availability-drift", "variable": "frequency and operational handling of unavailable referenced works", "classification": "known-unresolved", "evidenceRefs": ["stress/trial-report.md#trial-2-artwork-unavailable"], "nextProbe": "Define an availability check before each print run" } ] } --- FILE: examples/exhibition-guide/stress/world-card-artwork-unavailable.json (12 lines, 0.7 KiB) --- { "$schema": "../../../schemas/world-card.schema.json", "id": "world.exhibition.artwork-unavailable", "perturbationRef": "perturbation.exhibition.artwork-unavailable", "premise": "One of the three artworks named by the frozen guide is temporarily removed after printing.", "retained": ["two artworks remain available", "visitor agency", "factual standards"], "changed": ["availability of one named entry point"], "questions": ["Can a visitor still begin without a required route?", "Does the stale option require an authorized correction?"], "evidenceRequired": ["literal candidate inspection", "bounded repair analysis"], "revealState": "revealed", "candidateFreezeRef": "freeze.exhibition.candidate-b.1" } --- FILE: examples/exhibition-guide/stress/world-card-format-loss.json (12 lines, 0.7 KiB) --- { "$schema": "../../../schemas/world-card.schema.json", "id": "world.exhibition.format-loss", "perturbationRef": "perturbation.exhibition.format-loss", "premise": "The guide is reproduced as plain text with no headings, bullets, emphasis, or spatial grouping.", "retained": ["all candidate wording", "visitor agency", "factual standards"], "changed": ["visual hierarchy", "scannability cues"], "questions": ["Does the text still state that there is no required route?", "Do the three invitations remain distinguishable?"], "evidenceRequired": ["literal plain-text inspection against the frozen candidate"], "revealState": "revealed", "candidateFreezeRef": "freeze.exhibition.candidate-b.1" } --- FILE: examples/legacy-migration/README.md (11 lines, 0.5 KiB) --- # Legacy Migration Fixture This synthetic fixture tests incremental IEPE adoption against a small pre-existing backlog. The fixture includes: - one closed historical item with no reason to enrich it - one active item with partial provenance that requires reconciliation - one new item created after the adoption boundary that must satisfy the full contract The fixture does not simulate a live provider. It validates classification, status honesty, evidence gaps, and preservation of source identity. --- FILE: examples/legacy-migration/after.md (9 lines, 0.5 KiB) --- # Migration Result | Item | Classification | Disposition | IEPE status | Claim maturity | | --- | --- | --- | --- | --- | | `LEGACY-11` | Historical | Preserve | Unmapped | Unresolved | | `LEGACY-18` | Active | Reconcile | In progress | Documented | | `NEW-24` | New | Require full contract | Backlog | Documented | No source item was deleted, closed, or advanced. `LEGACY-18` remains active but blocked from review until its acceptance, evidence, and claim identity gaps are resolved. `NEW-24` remains in Backlog until it receives a complete issue contract. --- FILE: examples/legacy-migration/before.json (5 lines, 0.3 KiB) --- [ { "id": "LEGACY-11", "status": "Closed", "title": "Earlier exploration", "relationships": [] }, { "id": "LEGACY-18", "status": "Doing", "title": "Revise the participant guide", "relationships": ["EPIC-3"] }, { "id": "NEW-24", "status": "Open", "title": "Evaluate the revised guide", "relationships": ["LEGACY-18"] } ] --- FILE: examples/legacy-migration/conformance-manifest.json (7 lines, 0.1 KiB) --- { "../../schemas/migration-record.schema.json": [ "records/historical.json", "records/active.json", "records/new.json" ] } --- FILE: examples/legacy-migration/records/active.json (15 lines, 0.7 KiB) --- { "$schema": "../../../schemas/migration-record.schema.json", "id": "migration.legacy-18", "source": { "provider": "example-tracker", "itemId": "LEGACY-18", "status": "Doing", "url": null }, "classification": "active", "disposition": "reconcile", "targetStatus": "In progress", "statusRationale": "An active claim is present, but acceptance and evidence must be reconciled before review.", "intentRefs": ["intent.participant-guide"], "relationshipRefs": ["EPIC-3"], "provenance": "partial", "evidenceGaps": ["acceptance criteria missing", "evaluation requirement missing", "claim identity not verified"], "decision": "needs-review", "notes": "Do not advance until the reconciliation packet is complete." } --- FILE: examples/legacy-migration/records/historical.json (15 lines, 0.6 KiB) --- { "$schema": "../../../schemas/migration-record.schema.json", "id": "migration.legacy-11", "source": { "provider": "example-tracker", "itemId": "LEGACY-11", "status": "Closed", "url": null }, "classification": "historical", "disposition": "preserve", "targetStatus": null, "statusRationale": "The item is not required for active authority, dependency, or evidence.", "intentRefs": [], "relationshipRefs": [], "provenance": "missing", "evidenceGaps": ["completion evidence not retained"], "decision": "accepted", "notes": "Preserve source identity and status without manufacturing maturity." } --- FILE: examples/legacy-migration/records/new.json (15 lines, 0.7 KiB) --- { "$schema": "../../../schemas/migration-record.schema.json", "id": "migration.new-24", "source": { "provider": "example-tracker", "itemId": "NEW-24", "status": "Open", "url": null }, "classification": "new", "disposition": "require-full-contract", "targetStatus": "Backlog", "statusRationale": "The item was created after the adoption boundary and cannot become Ready without a complete IEPE issue contract.", "intentRefs": ["intent.participant-guide"], "relationshipRefs": ["LEGACY-18"], "provenance": "complete", "evidenceGaps": ["IEPE issue contract not yet attached"], "decision": "accepted", "notes": "Native dependency on LEGACY-18 must remain intact." } --- FILE: fixtures/conformance.json (219 lines, 9.1 KiB) --- { "agent-package-source.schema.json": { "packageId": "package.example", "packageVersion": "0.1.0", "projectRoot": ".", "protocol": {"protocolId": "IEPE-001", "protocolVersion": "0.1.0", "source": "https://example.test/iepe-core", "revision": "v0.1.0-test"}, "releaseClass": "provisional", "sourceState": "provisional", "operatingContract": "AGENTS.md", "sources": [{"path": "AGENTS.md", "role": "operations", "authorityRank": 1}], "skills": ["operate-iepe-project"], "adapters": [], "exclusions": [".git"] }, "agent-package-manifest.schema.json": { "formatVersion": "1", "packageId": "package.example", "packageVersion": "0.1.0", "protocol": {"protocolId": "IEPE-001", "protocolVersion": "0.1.0", "source": "https://example.test/iepe-core", "revision": "v0.1.0-test"}, "releaseClass": "provisional", "sourceState": "provisional", "operatingContract": "AGENTS.source.md", "sources": [{"path": "INTENT.md", "role": "intent", "authorityRank": 1, "bytes": 10, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}], "skills": ["evidence-closure"], "adapters": ["work-graph.example"], "outputs": [ {"path": "AGENTS.md", "bytes": 10, "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}, {"path": "context-index.md", "bytes": 10, "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"}, {"path": "context-full.md", "bytes": 10, "sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"} ], "exclusions": ["__pycache__"], "payloadSha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, "project-profile.schema.json": { "id": "project.example", "name": "Example Project", "protocol": {"protocolId": "IEPE-001", "protocolVersion": "0.1.0", "source": "https://example.test/iepe-core", "revision": "v0.1.0-test"}, "intentRefs": ["docs/INTENT.md"], "authorityOrder": ["docs/INTENT.md", "AGENTS.md"], "workGraph": { "provider": "github", "projectRefs": ["project.example"] }, "workspaces": ["workspace.example"], "coordinator": { "identity": "coordinator.example", "capacity": 1, "stopPolicyRef": "AGENTS.md#stop-rule" }, "evaluators": ["validator.schema"], "protectedActions": ["publication"], "promotionAuthorities": ["owner.example"], "memory": { "operational": "issues", "institutional": "docs", "negativeResults": "docs/rejected" } }, "protocol-reference.schema.json": { "protocolId": "IEPE-001", "protocolVersion": "0.1.0", "source": "https://example.test/iepe-core", "revision": "v0.1.0-test", "relationship": "reference", "conformanceCommand": "python3 tools/validate.py" }, "experience-contract.schema.json": { "id": "experience.example", "intent": "Help a participant complete the central task with confidence.", "audience": { "primary": "participants", "contexts": ["first use"] }, "desiredOutcomes": ["complete the task"], "experientialQualities": ["clear", "calm"], "behaviorsToEncourage": ["informed choice"], "behaviorsToAvoid": ["accidental commitment"], "states": ["initial", "active", "error", "recovery"], "constraints": ["preserve reversibility"], "accessibilityRequirements": ["keyboard-complete operation"], "evidenceRequirements": ["observed task completion"], "authorityRefs": ["docs/INTENT.md"] }, "issue-contract.schema.json": { "id": "ISSUE-001", "type": "delivery", "title": "Deliver an example outcome", "intentRefs": ["docs/INTENT.md"], "experienceRefs": ["experience.example"], "objective": "Produce the defined outcome.", "hypothesis": null, "owner": "owner.example", "workspace": "workspace.example", "parent": "EPIC-001", "dependencies": [], "acceptanceCriteria": ["outcome exists"], "evidenceRequired": ["independent review"], "constraints": ["remain reversible"], "exclusions": [], "permissions": { "externalWrites": false, "deployments": false, "communications": false, "spending": false }, "budget": { "time": "one cycle", "cost": 0, "iterations": 3 }, "stopConditions": ["authority becomes ambiguous"] }, "context-packet.schema.json": { "id": "context.ISSUE-1.claim-1", "issueId": "ISSUE-1", "claimId": "claim-1", "objective": "Produce the bounded outcome.", "sources": [{"ref": "INTENT.md", "kind": "intent", "authorityRank": 1, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}], "dependencies": {"DEP-1": "complete"}, "constraints": ["remain reversible"], "evidenceRequired": ["independent review"], "permissions": {"externalWrites": false}, "stopConditions": ["authority becomes ambiguous"], "contextSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, "evaluation-record.schema.json": { "id": "evaluation.example.1", "subjectRef": "artifact.example.1", "baselineRef": null, "evaluator": "reviewer.example", "independence": "independent", "environmentRef": "environment.example", "dimensions": [ { "name": "intent alignment", "result": "pass", "threshold": "pass", "evidenceRefs": ["observation.example"] } ], "tradeoffs": [], "limitations": ["single environment"], "disposition": "qualify" }, "evidence-bundle.schema.json": { "id": "evidence.example.1", "projectId": "project.example", "issueId": "ISSUE-001", "candidateId": null, "artifactRefs": ["artifact.example.1"], "intentRefs": ["docs/INTENT.md"], "authorityRefs": ["AGENTS.md"], "environment": { "name": "example" }, "inputs": [], "provenance": ["run.example.1"], "evaluations": [ { "dimension": "intent alignment", "result": "pass", "evaluator": "reviewer.example", "evidenceRefs": ["observation.example"] } ], "baselineComparison": null, "cost": null, "tradeoffs": [], "limitations": ["single environment"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run the declared evaluator." }, "promotion-record.schema.json": { "id": "promotion.example.1", "subjectRef": "artifact.example.1", "issueRef": "ISSUE-001", "evidenceBundleRef": "evidence.example.1", "authority": "owner.example", "decision": "approved", "target": "baseline.example", "tradeoffs": [], "conditions": [], "recoveryPlan": "Restore the previous baseline.", "effectiveAt": null }, "migration-record.schema.json": { "id": "migration.example", "source": { "provider": "tracker", "itemId": "ITEM-1", "status": "Open", "url": null }, "classification": "active", "disposition": "reconcile", "targetStatus": "In progress", "statusRationale": "An active claim exists.", "intentRefs": ["intent.example"], "relationshipRefs": [], "provenance": "partial", "evidenceGaps": ["acceptance criteria missing"], "decision": "needs-review", "notes": null }, "perturbation.schema.json": { "id": "perturbation.example", "family": "constraint", "visibility": "sealed", "protectedInvariants": ["project intent"], "changedConditions": ["available time is reduced"], "revealGate": "candidate-frozen", "evaluationDimensions": ["task completion"], "severity": "moderate", "recoveryRequired": true, "steward": "steward.example" }, "worker-dispatch.schema.json": { "id": "dispatch.example.1", "issueId": "ISSUE-1", "claimId": "claim-1", "contextSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "workerId": "worker.example", "role": "resolver", "attempt": 1, "permissions": {"localWrites": true, "externalWrites": false}, "status": "completed", "result": {"artifacts": ["artifact.example"], "observations": [], "commands": ["test"], "cost": null, "limitations": ["local only"]} }, "world-card.schema.json": { "id": "world.example", "perturbationRef": "perturbation.example", "premise": "The participant has half the expected time.", "retained": ["project intent"], "changed": ["available time"], "questions": ["Does the result remain usable?"], "evidenceRequired": ["bounded trial"], "revealState": "revealed", "candidateFreezeRef": "candidate.example.frozen" }, "robustness-profile.schema.json": { "id": "robustness.example", "candidateRef": "candidate.example", "knownQualificationRef": "evaluation.example", "surpriseBudget": { "evaluationShare": 0.15, "minimumWorldCards": 2, "candidateVisibility": "sealed-until-frozen" }, "trials": [ { "worldCardRef": "world.example", "disposition": "bounded", "evidenceRefs": ["trial.example"], "limitations": [] } ], "validityBoundary": ["expected operating conditions"], "promotionEffect": "constrain" }, "unknown-variable-ledger.schema.json": { "id": "unknowns.example", "projectRef": "project.example", "entries": [ { "id": "unknown.example.1", "variable": "future operating context", "classification": "assumed-untested", "evidenceRefs": [], "nextProbe": "Create a context World Card" } ] } } ======================================================================== ## SUBSYSTEM: TESTSUITE & VERIFICATION GATES (7 files) ======================================================================== --- FILE: tests/test_bootstrap.py (82 lines, 3.8 KiB) --- import json from pathlib import Path import tempfile import unittest from iepe_core.bootstrap import BootstrapConfig, discover_existing, generated_files, initialize_new from tools.compile_package import compile_package class BootstrapTests(unittest.TestCase): def config(self) -> BootstrapConfig: return BootstrapConfig( project_id="project.alpha", project_name="Project Alpha", intent="Help readers understand a difficult system through a verified interactive explanation.", protocol_source="https://example.test/iepe-core", protocol_revision="v0.1.0-test", evaluators=("content.correctness", "experience.observation"), promotion_authorities=("owner.alpha",), ) def test_new_project_is_deterministic_and_reference_pinned(self): one = generated_files(self.config()) two = generated_files(self.config()) self.assertEqual(one, two) reference = json.loads(one[".iepe/protocol-reference.json"]) profile = json.loads(one["PROJECT_PROFILE.json"]) self.assertEqual(reference["revision"], "v0.1.0-test") self.assertEqual(profile["protocol"]["source"], reference["source"]) self.assertIn("first agent cycle is read-only reconciliation", one["AGENTS.md"]) def test_initializer_refuses_existing_files(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) (root / "AGENTS.md").write_text("user content", encoding="utf-8") with self.assertRaisesRegex(FileExistsError, "AGENTS.md"): initialize_new(root, self.config()) self.assertEqual((root / "AGENTS.md").read_text(encoding="utf-8"), "user content") def test_existing_discovery_is_read_only(self): with tempfile.TemporaryDirectory() as directory: root = Path(directory) source = root / "notes.md" source.write_text("observed behavior", encoding="utf-8") before = source.read_bytes() report = discover_existing(root) self.assertEqual(source.read_bytes(), before) self.assertEqual([item["path"] for item in report["files"]], ["notes.md"]) self.assertFalse(report["signals"]["hasProtocolReference"]) def test_generated_project_compiles_with_protocol_provenance(self): with tempfile.TemporaryDirectory() as directory, tempfile.TemporaryDirectory() as output: root = Path(directory) initialize_new(root, self.config()) manifest = compile_package(root / ".agents/package-source.json", Path(output)) self.assertEqual(manifest["protocol"]["protocolId"], "IEPE-001") self.assertEqual(manifest["protocol"]["revision"], "v0.1.0-test") def test_provisional_profile_when_promotion_unassigned(self): cfg = BootstrapConfig( project_id="project.provisional", project_name="Project Provisional", intent="Intent text for provisional project.", protocol_source="https://example.test/iepe-core", protocol_revision="v0.1.0-test", evaluators=("content.correctness",), promotion_authorities=("unassigned",), ) files = generated_files(cfg) profile = json.loads(files["PROJECT_PROFILE.json"]) self.assertEqual(profile["profileStatus"], "provisional") self.assertEqual(profile["promotionAuthorities"], ["unassigned"]) def test_write_capability_probe(self): from iepe_core.bootstrap import probe_workspace_write_capability with tempfile.TemporaryDirectory() as directory: root = Path(directory) self.assertTrue(probe_workspace_write_capability(root)) if __name__ == "__main__": unittest.main() --- FILE: tests/test_claims.py (68 lines, 3.2 KiB) --- from datetime import datetime, timedelta, timezone import unittest from iepe_core.claims import Claim, ClaimMode, ClaimRegistry, scopes_overlap NOW = datetime(2026, 1, 1, tzinfo=timezone.utc) def claim(identifier, issue, workspace, scope, mode=ClaimMode.WRITE, minutes=30): return Claim(identifier, issue, "agent.test", workspace, (scope,), mode, NOW, NOW + timedelta(minutes=minutes)) class ClaimRegistryTests(unittest.TestCase): def test_hierarchical_scope_overlap_is_provider_neutral(self): self.assertTrue(scopes_overlap("project/component", "project/component/file")) self.assertFalse(scopes_overlap("project/component-a", "project/component-b")) def test_capacity_is_enforced(self): registry = ClaimRegistry(capacity=1) registry.acquire(claim("c1", "i1", "w", "a"), now=NOW) with self.assertRaisesRegex(ValueError, "capacity"): registry.acquire(claim("c2", "i2", "w", "b"), now=NOW) def test_overlapping_write_is_rejected(self): registry = ClaimRegistry(capacity=2) registry.acquire(claim("c1", "i1", "w", "area"), now=NOW) with self.assertRaisesRegex(ValueError, "conflicts"): registry.acquire(claim("c2", "i2", "w", "area/file"), now=NOW) def test_read_only_overlap_can_coexist(self): registry = ClaimRegistry(capacity=2) registry.acquire(claim("c1", "i1", "w", "area", ClaimMode.READ), now=NOW) registry.acquire(claim("c2", "i2", "w", "area/file", ClaimMode.READ), now=NOW) self.assertEqual(2, len(registry.active(now=NOW))) def test_workspaces_are_isolated(self): registry = ClaimRegistry(capacity=2) registry.acquire(claim("c1", "i1", "w1", "area"), now=NOW) registry.acquire(claim("c2", "i2", "w2", "area"), now=NOW) self.assertEqual(2, len(registry.active(now=NOW))) def test_expired_claim_does_not_authorize_or_consume_capacity(self): registry = ClaimRegistry(capacity=1) registry.acquire(claim("c1", "i1", "w", "area", minutes=1), now=NOW) later = NOW + timedelta(minutes=2) self.assertFalse(registry.claim_assertion("c1", issue_id="i1", now=later).valid) fresh = Claim("c2", "i2", "agent.test", "w", ("area",), ClaimMode.WRITE, later, later + timedelta(minutes=10)) registry.acquire(fresh, now=later) def test_release_is_idempotent_and_both_attempts_are_recorded(self): registry = ClaimRegistry(capacity=1) registry.acquire(claim("c1", "i1", "w", "area"), now=NOW) self.assertTrue(registry.release("c1", now=NOW, reason="complete")) self.assertFalse(registry.release("c1", now=NOW, reason="retry")) self.assertEqual(["acquired", "released", "release-repeated"], [event.action for event in registry.history]) def test_assertion_is_derived_from_matching_active_claim(self): registry = ClaimRegistry(capacity=1) registry.acquire(claim("c1", "i1", "w", "area"), now=NOW) assertion = registry.claim_assertion("c1", issue_id="i1", now=NOW) self.assertTrue(assertion.valid) self.assertEqual(("claim.c1",), assertion.evidence_refs) self.assertFalse(registry.claim_assertion("c1", issue_id="other", now=NOW).valid) if __name__ == "__main__": unittest.main() --- FILE: tests/test_context.py (73 lines, 3.4 KiB) --- from datetime import datetime, timedelta, timezone import unittest from iepe_core.claims import Claim, ClaimMode, ClaimRegistry from iepe_core.context import ContextRequest, ContextSource, assemble_context_packet NOW = datetime(2026, 1, 1, tzinfo=timezone.utc) def registry(): value = ClaimRegistry(1) value.acquire(Claim("claim-1", "ISSUE-1", "agent", "workspace", ("project",), ClaimMode.WRITE, NOW, NOW + timedelta(hours=1)), now=NOW) return value def request(**changes): values = dict( issue_id="ISSUE-1", claim_id="claim-1", objective="Produce the bounded outcome.", intent_refs=("intent",), authority_refs=("authority",), dependencies=("DEP-1",), constraints=("remain reversible",), evidence_required=("independent review",), permissions=(("externalWrites", False),), stop_conditions=("authority becomes ambiguous",), ) values.update(changes) return ContextRequest(**values) def sources(): return { "intent": ContextSource("intent", "intent", 1, "Serve the declared participant.", "purpose"), "authority": ContextSource("authority", "authority", 2, "Owner approves promotion."), "unrelated": ContextSource("unrelated", "operations", 9, "Do not include me."), } class ContextPacketTests(unittest.TestCase): def test_complete_packet_is_deterministic_and_claim_bound(self): first = assemble_context_packet(request(), registry=registry(), now=NOW, sources=sources(), dependency_records={"DEP-1": "complete"}) second = assemble_context_packet(request(), registry=registry(), now=NOW, sources=sources(), dependency_records={"DEP-1": "complete"}) self.assertEqual(first.record, second.record) self.assertEqual("claim-1", first.record["claimId"]) def test_missing_mandatory_context_blocks_packet(self): with self.assertRaisesRegex(ValueError, "Missing mandatory context"): assemble_context_packet(request(), registry=registry(), now=NOW, sources={"intent": sources()["intent"]}, dependency_records={"DEP-1": "complete"}) def test_authority_conflict_is_surfaced(self): conflicting = sources() conflicting["other-intent"] = ContextSource("other-intent", "intent", 1, "A different purpose.", "purpose") with self.assertRaisesRegex(ValueError, "Authority conflict"): assemble_context_packet(request(intent_refs=("intent", "other-intent")), registry=registry(), now=NOW, sources=conflicting, dependency_records={"DEP-1": "complete"}) def test_unreferenced_excess_context_is_excluded(self): packet = assemble_context_packet(request(), registry=registry(), now=NOW, sources=sources(), dependency_records={"DEP-1": "complete"}) self.assertNotIn("unrelated", [source["ref"] for source in packet.record["sources"]]) def test_referenced_excess_context_is_rejected(self): with self.assertRaisesRegex(ValueError, "limit exceeded"): assemble_context_packet(request(), registry=registry(), now=NOW, sources=sources(), dependency_records={"DEP-1": "complete"}, max_sources=1) def test_expired_claim_blocks_packet(self): with self.assertRaisesRegex(ValueError, "active claim"): assemble_context_packet(request(), registry=registry(), now=NOW + timedelta(hours=2), sources=sources(), dependency_records={"DEP-1": "complete"}) if __name__ == "__main__": unittest.main() --- FILE: tests/test_coordinator.py (102 lines, 4.9 KiB) --- import unittest from iepe_core.coordinator import AssertionType, Coordinator, CoordinatorState, GateAssertion, make_assertion, simulate_valid_cycle class CoordinatorTests(unittest.TestCase): def test_delivery_cycle_completes(self) -> None: receipt = simulate_valid_cycle("DELIVERY-1", "delivery") self.assertEqual(receipt.final_state, CoordinatorState.COMPLETE) self.assertEqual(len(receipt.transitions), 12) self.assertIn("artifact.DELIVERY-1", receipt.artifacts) def test_experiment_cycle_completes(self) -> None: receipt = simulate_valid_cycle("EXPERIMENT-1", "experiment") self.assertEqual(receipt.work_type, "experiment") self.assertIn("assertion.EXPERIMENT-1.evaluation.complete", receipt.assertion_ids) def test_invalid_transition_fails(self) -> None: coordinator = Coordinator("INVALID-1", "delivery") with self.assertRaisesRegex(ValueError, "Invalid coordinator transition"): coordinator.transition(CoordinatorState.CLAIM, assertions=[make_assertion(AssertionType.ISSUE_READY, "INVALID-1")]) def test_missing_gate_evidence_fails(self) -> None: coordinator = Coordinator("INVALID-2", "delivery") with self.assertRaisesRegex(ValueError, "preflight.valid"): coordinator.transition(CoordinatorState.RECONCILE) def test_wrong_assertion_type_fails(self) -> None: coordinator = Coordinator("INVALID-TYPE", "delivery") with self.assertRaisesRegex(ValueError, "preflight.valid"): coordinator.transition( CoordinatorState.RECONCILE, assertions=[make_assertion(AssertionType.ISSUE_READY, "INVALID-TYPE")], ) def test_wrong_assertion_subject_fails(self) -> None: coordinator = Coordinator("SUBJECT-1", "delivery") assertion = make_assertion(AssertionType.PREFLIGHT_VALID, "OTHER-ISSUE") with self.assertRaisesRegex(ValueError, "wrong subject"): coordinator.transition(CoordinatorState.RECONCILE, assertions=[assertion]) def test_invalidated_assertion_fails(self) -> None: coordinator = Coordinator("INVALIDATED-1", "delivery") assertion = make_assertion(AssertionType.PREFLIGHT_VALID, "INVALIDATED-1", valid=False) with self.assertRaisesRegex(ValueError, "is invalid"): coordinator.transition(CoordinatorState.RECONCILE, assertions=[assertion]) def test_stop_record_preserves_reason_and_authority(self) -> None: coordinator = Coordinator("STOP-1", "delivery") coordinator.stop( "owning workspace is ambiguous", "project owner", evidence=["workspace.conflict"], ) receipt = coordinator.receipt() self.assertEqual(receipt.final_state, CoordinatorState.STOPPED) self.assertEqual(receipt.stop.state, CoordinatorState.PREFLIGHT) self.assertEqual(receipt.stop.resume_authority, "project owner") def test_artifact_before_validation_fails(self) -> None: coordinator = Coordinator("INVALID-3", "delivery") with self.assertRaisesRegex(ValueError, "before issue validation"): coordinator.add_artifact("artifact.invalid") def test_nonterminal_receipt_fails(self) -> None: coordinator = Coordinator("INVALID-4", "delivery") with self.assertRaisesRegex(ValueError, "terminal"): coordinator.receipt() def test_waiting_external_state(self) -> None: from iepe_core.coordinator import BlockerFingerprint, ConditionType coordinator = Coordinator("WAIT-1", "delivery") blocker = BlockerFingerprint( code="ENV_WORKSPACE_READ_ONLY", scope="SES", required_change="workspace-write capability", retryable_by_agent=False, condition_type=ConditionType.CAPABILITY_MISSING, ) coordinator.park_waiting_external(blocker, resume_authority="user") receipt = coordinator.receipt() self.assertEqual(receipt.final_state, CoordinatorState.WAITING_EXTERNAL) self.assertIn("ENV_WORKSPACE_READ_ONLY", receipt.stop.reason) self.assertEqual(receipt.stop.resume_authority, "user") def test_duplicate_non_retryable_blocker_fails(self) -> None: from iepe_core.coordinator import BlockerFingerprint, ConditionType coordinator = Coordinator("WAIT-2", "delivery") blocker = BlockerFingerprint( code="ENV_WORKSPACE_READ_ONLY", scope="SES", required_change="workspace-write capability", retryable_by_agent=False, condition_type=ConditionType.CAPABILITY_MISSING, ) coordinator.park_waiting_external(blocker, resume_authority="user") with self.assertRaisesRegex(ValueError, "Duplicate non-retryable blocker fingerprint"): coordinator.park_waiting_external(blocker, resume_authority="user") if __name__ == "__main__": unittest.main() --- FILE: tests/test_dispatch.py (75 lines, 4.3 KiB) --- from datetime import datetime, timedelta, timezone import unittest from iepe_core.claims import Claim, ClaimMode, ClaimRegistry from iepe_core.context import ContextRequest, ContextSource, assemble_context_packet from iepe_core.dispatch import DispatchEnvelope, DispatchRegistry, WorkerOutcome, WorkerResult NOW = datetime(2026, 1, 1, tzinfo=timezone.utc) def setup(): claims = ClaimRegistry(1) claims.acquire(Claim("claim-1", "ISSUE-1", "agent", "workspace", ("project",), ClaimMode.WRITE, NOW, NOW + timedelta(hours=1)), now=NOW) request = ContextRequest("ISSUE-1", "claim-1", "Do work", ("intent",), ("authority",), evidence_required=("tests",), permissions=(("externalWrites", False), ("localWrites", True)), stop_conditions=("authority conflict",)) sources = {"intent": ContextSource("intent", "intent", 1, "Intent"), "authority": ContextSource("authority", "authority", 2, "Authority")} packet = assemble_context_packet(request, registry=claims, now=NOW, sources=sources, dependency_records={}) return claims, packet def envelope(packet, identifier="dispatch-1", worker="worker-1", attempt=1, permissions=(("localWrites", True),)): return DispatchEnvelope(identifier, "ISSUE-1", "claim-1", packet.digest, worker, "resolver", attempt, permissions) def result(packet, dispatch="dispatch-1", worker="worker-1", attempt=1, outcome=WorkerOutcome.COMPLETED): return WorkerResult(dispatch, "ISSUE-1", "claim-1", packet.digest, worker, attempt, outcome, artifacts=("artifact.1",), commands=("test",), limitations=("local only",)) class DispatchTests(unittest.TestCase): def test_success_record_retains_provenance(self): claims, packet = setup(); registry = DispatchRegistry() registry.dispatch(envelope(packet), packet=packet, claims=claims, now=NOW) record = registry.accept_result(result(packet)) self.assertEqual("completed", record["status"]) self.assertEqual(["artifact.1"], record["result"]["artifacts"]) def test_failure_blocked_and_stopped_are_distinct(self): for outcome in (WorkerOutcome.FAILED, WorkerOutcome.BLOCKED, WorkerOutcome.STOPPED): with self.subTest(outcome=outcome): claims, packet = setup(); registry = DispatchRegistry() registry.dispatch(envelope(packet), packet=packet, claims=claims, now=NOW) self.assertEqual(outcome.value, registry.accept_result(result(packet, outcome=outcome))["status"]) def test_permission_expansion_is_rejected(self): claims, packet = setup(); registry = DispatchRegistry() with self.assertRaisesRegex(ValueError, "permission expansion"): registry.dispatch(envelope(packet, permissions=(("externalWrites", True),)), packet=packet, claims=claims, now=NOW) def test_stale_context_is_rejected(self): claims, packet = setup(); registry = DispatchRegistry() changed = DispatchEnvelope("dispatch-1", "ISSUE-1", "claim-1", "0" * 64, "worker-1", "resolver", 1, ()) with self.assertRaisesRegex(ValueError, "stale"): registry.dispatch(changed, packet=packet, claims=claims, now=NOW) def test_retry_preserves_attempt_lineage_and_may_change_worker(self): claims, packet = setup(); registry = DispatchRegistry() registry.dispatch(envelope(packet), packet=packet, claims=claims, now=NOW) registry.accept_result(result(packet, outcome=WorkerOutcome.FAILED)) retry = envelope(packet, identifier="dispatch-2", worker="worker-2", attempt=2) registry.dispatch(retry, packet=packet, claims=claims, now=NOW) self.assertEqual(2, registry.record("dispatch-2")["attempt"]) self.assertEqual("worker-2", registry.record("dispatch-2")["workerId"]) def test_duplicate_dispatch_and_result_are_rejected(self): claims, packet = setup(); registry = DispatchRegistry(); item = envelope(packet) registry.dispatch(item, packet=packet, claims=claims, now=NOW) with self.assertRaisesRegex(ValueError, "Duplicate dispatch"): registry.dispatch(item, packet=packet, claims=claims, now=NOW) registry.accept_result(result(packet)) with self.assertRaisesRegex(ValueError, "Duplicate worker result"): registry.accept_result(result(packet)) if __name__ == "__main__": unittest.main() --- FILE: tests/test_package_compiler.py (63 lines, 2.7 KiB) --- import json from pathlib import Path import tempfile import unittest from tools.compile_package import compile_package ROOT = Path(__file__).resolve().parents[1] EXAMPLE = ROOT / "examples" / "agent-package" / "package-source.json" class PackageCompilerTests(unittest.TestCase): def test_example_compiles_deterministically(self): with tempfile.TemporaryDirectory() as first, tempfile.TemporaryDirectory() as second: one = compile_package(EXAMPLE, Path(first)) two = compile_package(EXAMPLE, Path(second)) self.assertEqual(one, two) self.assertEqual( (Path(first) / "agent-package-manifest.json").read_bytes(), (Path(second) / "agent-package-manifest.json").read_bytes(), ) self.assertEqual( (Path(first) / "context-full.md").read_bytes(), (Path(second) / "context-full.md").read_bytes(), ) def test_missing_source_is_rejected(self): config = json.loads(EXAMPLE.read_text()) config["projectRoot"] = str((EXAMPLE.parent / "project").resolve()) config["sources"][0]["path"] = "MISSING.md" with tempfile.TemporaryDirectory() as directory: path = Path(directory) / "config.json" path.write_text(json.dumps(config)) with self.assertRaisesRegex(ValueError, "Missing source"): compile_package(path, Path(directory) / "out") def test_unsafe_and_machine_paths_are_rejected(self): config = json.loads(EXAMPLE.read_text()) config["projectRoot"] = str((EXAMPLE.parent / "project").resolve()) for bad in ("../secret.txt", "__pycache__/record.pyc"): with self.subTest(path=bad), tempfile.TemporaryDirectory() as directory: changed = dict(config) changed["sources"] = [dict(config["sources"][0], path=bad), *config["sources"][1:]] changed["operatingContract"] = bad path = Path(directory) / "config.json" path.write_text(json.dumps(changed)) with self.assertRaisesRegex(ValueError, "Unsafe|Excluded"): compile_package(path, Path(directory) / "out") def test_dirty_release_is_rejected(self): config = json.loads(EXAMPLE.read_text()) config["projectRoot"] = str((EXAMPLE.parent / "project").resolve()) config["sourceState"] = "dirty" with tempfile.TemporaryDirectory() as directory: path = Path(directory) / "config.json" path.write_text(json.dumps(config)) with self.assertRaisesRegex(ValueError, "clean source state"): compile_package(path, Path(directory) / "out") if __name__ == "__main__": unittest.main() --- FILE: tests/test_receipts.py (62 lines, 3.0 KiB) --- import copy import json import unittest from iepe_core.coordinator import Coordinator, CoordinatorState, simulate_valid_cycle from iepe_core.receipts import load_and_validate_receipt, seal_payload, seal_receipt, serialize_receipt class ReceiptTests(unittest.TestCase): def test_completed_receipt_round_trips(self) -> None: receipt = simulate_valid_cycle("ROUNDTRIP-1", "delivery") envelope = load_and_validate_receipt(serialize_receipt(receipt)) self.assertEqual(envelope["payload"]["finalState"], "complete") self.assertEqual(len(envelope["payload"]["assertions"]), 12) def test_stopped_receipt_round_trips(self) -> None: coordinator = Coordinator("STOPPED-ROUNDTRIP", "delivery") coordinator.stop("provider unavailable", "project owner", evidence=["provider.health.failed"]) envelope = load_and_validate_receipt(serialize_receipt(coordinator.receipt())) self.assertEqual(envelope["payload"]["stop"]["resumeAuthority"], "project owner") def test_serialization_is_deterministic(self) -> None: receipt = simulate_valid_cycle("DETERMINISTIC-1", "experiment") self.assertEqual(serialize_receipt(receipt), serialize_receipt(receipt)) def test_tampered_payload_fails_integrity(self) -> None: envelope = seal_receipt(simulate_valid_cycle("TAMPER-1", "delivery")) envelope["payload"]["workType"] = "altered" with self.assertRaisesRegex(ValueError, "integrity"): load_and_validate_receipt(json.dumps(envelope)) def test_unsupported_version_fails(self) -> None: envelope = seal_receipt(simulate_valid_cycle("VERSION-1", "delivery")) envelope["version"] = 999 with self.assertRaisesRegex(ValueError, "version"): load_and_validate_receipt(json.dumps(envelope)) def test_impossible_history_fails_even_with_valid_digest(self) -> None: envelope = seal_receipt(simulate_valid_cycle("HISTORY-1", "delivery")) payload = copy.deepcopy(envelope["payload"]) payload["transitions"][1]["target"] = "claim" resealed = seal_payload(payload) with self.assertRaisesRegex(ValueError, "impossible|discontinuous"): load_and_validate_receipt(json.dumps(resealed)) def test_wrong_assertion_subject_fails_replay(self) -> None: envelope = seal_receipt(simulate_valid_cycle("SUBJECT-REPLAY", "delivery")) payload = copy.deepcopy(envelope["payload"]) payload["assertions"][0]["subject"] = "OTHER" with self.assertRaisesRegex(ValueError, "wrong subject"): load_and_validate_receipt(json.dumps(seal_payload(payload))) def test_missing_assertion_provenance_fails_replay(self) -> None: envelope = seal_receipt(simulate_valid_cycle("PROVENANCE-1", "delivery")) payload = copy.deepcopy(envelope["payload"]) payload["assertions"][0]["evidenceRefs"] = [] with self.assertRaisesRegex(ValueError, "provenance"): load_and_validate_receipt(json.dumps(seal_payload(payload))) if __name__ == "__main__": unittest.main() ======================================================================== ## SUBSYSTEM: OPERATIONAL WORK GRAPH & ISSUES (15 files) ======================================================================== --- FILE: work/IEPE-CORE-002.md (71 lines, 2.4 KiB) --- # IEPE-CORE-002: Complete the M1 Contract and Template Suite ## Intent Make IEPE adoptable by unrelated projects without requiring them to invent core intent, experience, evaluation, decision, incident, or promotion records. ## Type Delivery ## Parent M1: Adoption Kit ## Objective Add the missing domain-neutral schemas and GitHub issue templates required to operate the principal IEPE work types. ## Acceptance criteria - Project profile schema defines authority, work graph, coordinator, evaluators, protected actions, promotion authorities, and memory. - Experience contract schema preserves audience, desired outcomes, qualities, states, constraints, accessibility, and evidence. - Evaluation record schema represents independent multi-dimensional assessment. - Promotion record schema separates qualification from adoption authority. - GitHub templates exist for design, evaluation, decision, incident, and promotion work. - Every JSON schema parses and validates representative valid and invalid fixtures. - Every YAML issue template parses. - Core artifacts contain no project-specific authority or runtime dependency. - README and roadmap accurately report maturity. ## Evidence required - Automated parsing results. - Positive and negative JSON Schema fixture results. - Cross-file identifier and reference audit. - Domain-neutrality search. - Updated evidence bundle. ## Constraints - Remain provider-neutral at the protocol layer. - GitHub files are reference adapters, not core authority. - Do not claim coordinator implementation. - Do not claim empirical validation. ## Permissions - Local file writes: allowed within `IEPE-Core`. - Library replacement: allowed for the existing project archive after qualification. - GitHub writes: not authorized or available. - Deployments: not authorized. - External communication: not authorized. - Spending: not authorized. ## Stop conditions - A required contract cannot be expressed without domain-specific assumptions. - Validation tooling is unavailable and cannot be replaced by a local equivalent. - Existing authority conflicts with the proposed schema semantics. ## Status Verified ## Claim maturity Tested ## Result Six domain-neutral schemas and seven GitHub issue templates passed structural evaluation. One residual originating-project name was found during domain-neutrality review and removed before qualification. See `evidence/IEPE-CORE-002-evidence.json`. --- FILE: work/IEPE-CORE-003.md (64 lines, 1.9 KiB) --- # IEPE-CORE-003: Implement the M1 Conformance Runner ## Intent Make IEPE contract validation reproducible by adopters rather than dependent on an undocumented evaluator environment. ## Type Delivery ## Parent M1: Adoption Kit ## Objective Provide one documented command that validates schemas, positive and negative fixtures, evidence records, GitHub issue templates, schema identifier uniqueness, and domain-neutrality constraints. ## Acceptance criteria - Development dependencies are declared. - A repository-owned validation command exists. - Every schema has a representative valid fixture. - Every schema rejects an empty invalid fixture. - Evidence records validate against the evidence schema. - GitHub templates parse and contain unique body field identifiers. - Forbidden domain references and unresolved placeholders fail validation. - The command returns nonzero on failure. - README documents the command. ## Evidence required - Clean command output. - Deliberate invalid-fixture rejection. - Evidence bundle validated by the runner. ## Constraints - Validation tooling must remain independent from a specific project domain. - Do not implement the operational coordinator in this issue. - Do not claim empirical validation. ## Permissions - Local project writes: allowed. - Temporary dependency installation: allowed. - External publishing and deployment: not authorized. ## Stop conditions - Required validation cannot run in a clean Python environment with declared dependencies. - The runner must weaken a schema to make fixtures pass. ## Status Verified ## Claim maturity Tested ## Result The repository now carries its declared validation dependencies, positive and negative fixtures, and a single conformance command. The runner passed the complete current suite and returned a nonzero status during a deliberate domain-term violation probe. See `evidence/IEPE-CORE-003-evidence.json`. --- FILE: work/IEPE-CORE-004.md (69 lines, 2.2 KiB) --- # IEPE-CORE-004: Build the First Cross-Domain Adoption Example ## Intent Prove that the adoption kit can describe a meaningful non-software project without modifying core doctrine. ## Type Experiment ## Parent M1: Adoption Kit ## Hypothesis An editorial or creative-production project can adopt IEPE using only a project profile, intent and experience contracts, work items, evidence, and domain-specific evaluators. ## Objective Create and execute one self-contained example from intent through evidence and promotion decision, then record every core ambiguity or missing extension point. ## Acceptance criteria - The example is outside software engineering. - All example records validate against the current schemas. - The example uses the coordinator state sequence. - At least one candidate is evaluated against visible dimensions. - A negative or rejected direction is preserved. - Qualification and promotion remain separate. - No example-specific concept is added to core unless proven generally necessary. - Adoption gaps are recorded as evidence for protocol refinement. ## Evidence required - Valid project profile. - Valid experience contract. - Valid issue, evaluation, evidence, and promotion records. - Coordinator execution trace. - Gap and negative-result record. - Conformance output. ## Constraints - The example must not pretend to be a real external field validation. - Human-value claims remain documented or tested unless actual observation exists. - The example stays reversible and has no external side effects. ## Permissions - Local example artifacts: allowed. - External publication, communication, spending, and deployment: not authorized. ## Stop conditions - The example requires weakening a core evidence or authority invariant. - The domain cannot supply an honest evaluator for its central claim. ## Status Verified ## Claim maturity Tested ## Result The exhibition-guide pilot completed the full internal path from intent through promotion decision. Six example records validate against the core schemas. Candidate B was promoted only to the internal example baseline. Candidate A was retained as a context-specific negative result. Human comprehension and lived accessibility remain unobserved. --- FILE: work/IEPE-CORE-005.md (66 lines, 1.9 KiB) --- # IEPE-CORE-005: Define Incremental Adoption and Migration ## Intent Allow established projects to adopt IEPE without rewriting history, disrupting current delivery, or assigning unsupported evidence maturity to legacy work. ## Type Delivery ## Parent M1: Adoption Kit ## Objective Define a provider-neutral migration protocol, legacy-item classification, minimum field mapping, reconciliation procedure, and pilot acceptance test. ## Acceptance criteria - Migration distinguishes historical, active, and new work. - Legacy status is not treated as evidence maturity. - New committed work uses complete IEPE issue contracts. - Active work receives a bounded reconciliation packet. - Historical work is migrated only when needed for authority, dependency, or evidence. - Native relationships remain authoritative where the provider supports them. - Migration has rollback and stop conditions. - One synthetic legacy backlog fixture passes the migration procedure. ## Evidence required - Migration specification. - Field and status mapping. - Synthetic before-and-after backlog fixture. - Reconciliation evidence. - Conformance results. ## Constraints - Do not require wholesale historical conversion. - Do not invent missing provenance. - Do not close or advance work merely because fields were mapped. - Remain project-management-provider neutral. ## Permissions - Local project artifacts: allowed. - External project mutation: not authorized. ## Stop conditions - Migration would destroy provider-native identity or relationships. - Required provenance cannot be established. - A field mapping changes the semantic meaning of an existing status. ## Status Verified ## Claim maturity Tested ## Result The migration protocol and synthetic backlog fixture passed conformance. Historical identity was preserved, active work retained explicit evidence gaps, and new work remained gated by the full issue contract. No status or maturity was inferred from a legacy label alone. --- FILE: work/IEPE-CORE-006.md (65 lines, 1.9 KiB) --- # IEPE-CORE-006: Implement the Coordinator State Machine ## Intent Move IEPE from a documented coordination sequence to an executable, provider-neutral reference state machine. ## Type Delivery ## Parent M2: Coordinator Reference ## Objective Implement coordinator state, transition rules, stop-state handling, execution receipts, and a deterministic local simulation for delivery and experiment work. ## Acceptance criteria - Coordinator states match `docs/COORDINATOR.md`. - Only declared transitions are permitted. - Invalid authority, context, ownership, dependencies, permission, budget, and evidence can stop execution. - A stop record identifies the reason and resumption authority. - Delivery and experiment simulations complete valid paths. - Invalid transitions and missing readiness evidence fail. - State history is retained as a receipt. - Implementation has no project-management-provider dependency. ## Evidence required - Automated state-transition tests. - Successful delivery trace. - Successful experiment trace. - Stop-state and invalid-transition traces. - Conformance results. ## Constraints - Local deterministic reference only. - No worker process spawning. - No external provider mutation. - No production-readiness claim. ## Permissions - Local code, tests, fixtures, and documentation: allowed. - External writes, deployment, communication, and spending: not authorized. ## Stop conditions - Implementation requires provider-specific concepts in the core state model. - A test must bypass an authority or evidence gate to complete. ## Status Verified ## Claim maturity Tested ## Result The provider-neutral coordinator state machine completed valid delivery and experiment paths and rejected invalid transitions, missing gate evidence, premature artifacts, and nonterminal receipts. Stop records retain the originating state, reason, evidence, and resumption authority. Seven automated tests pass. --- FILE: work/IEPE-CORE-007.md (62 lines, 1.7 KiB) --- # IEPE-CORE-007: Replace String Gates with Typed Coordinator Assertions ## Intent Prevent callers from satisfying coordinator gates with unstructured strings that are syntactically present but semantically unsupported. ## Type Delivery ## Parent M2: Coordinator Reference ## Objective Introduce typed assertions, assertion provenance, gate policies, and explicit readiness failures while preserving provider neutrality. ## Acceptance criteria - Gate assertions have type, subject, issuer, evidence references, and validity. - Required gates accept only matching valid assertion types. - Assertions for the wrong issue or subject fail. - Invalidated assertions fail. - Transition receipts retain assertion identity rather than only text. - Existing valid delivery and experiment paths continue to pass. - Tests cover wrong type, wrong subject, invalid assertion, and complete typed paths. ## Evidence required - Typed assertion model. - Gate-policy tests. - Updated execution traces. - Conformance results. ## Constraints - No identity-provider dependency. - No cryptographic implementation in this issue. - Preserve simple adapter construction for pilots. ## Permissions - Local code, tests, fixtures, and documentation: allowed. - External actions: not authorized. ## Stop conditions - Typed assertions require provider-specific identity semantics. - Compatibility requires weakening an existing stop-state test. ## Status Verified ## Claim maturity Tested ## Result Coordinator gates now require typed, issue-bound, valid assertions carrying issuer and evidence references. Valid delivery and experiment cycles continue to complete. Wrong types, wrong subjects, invalidated assertions, missing gates, and invalid transitions are rejected. Ten automated tests pass. --- FILE: work/IEPE-CORE-008.md (62 lines, 1.7 KiB) --- # IEPE-CORE-008: Persist and Replay Coordinator Receipts ## Intent Allow coordinator work to survive interruption and be audited or resumed without reconstructing state from conversation memory. ## Type Delivery ## Parent M2: Coordinator Reference ## Objective Define a versioned receipt format, deterministic serialization, integrity checking, and replay validation for completed and stopped coordinator executions. ## Acceptance criteria - Receipts serialize deterministically. - Receipt format is versioned. - State history, assertion identities, artifacts, and stop records persist. - Replay rejects impossible transition history. - Replay rejects altered receipt content through an integrity digest. - Completed and stopped receipts round-trip. - No external database is required. ## Evidence required - Receipt schema or typed model. - Round-trip tests. - Tamper and invalid-history tests. - Conformance results. ## Constraints - Local file or byte representation only. - No production durability claim. - No provider-specific storage. ## Permissions - Local code, tests, fixtures, and documentation: allowed. - External actions: not authorized. ## Stop conditions - Replay requires trusting unverified state transitions. - Serialization discards assertion or stop provenance. ## Status Verified ## Claim maturity Tested ## Result Coordinator receipts now serialize deterministically into a versioned envelope with a SHA-256 payload digest. Completed and stopped receipts round-trip. Replay rejects changed content, unsupported versions, impossible histories, wrong assertion subjects, incomplete assertion provenance, and nonterminal outcomes. Eighteen total reference tests pass. --- FILE: work/IEPE-CORE-009.md (59 lines, 1.6 KiB) --- # IEPE-CORE-009: Implement Claim Capacity and Conflict Management ## Intent Prevent the coordinator from dispatching overlapping or excessive work that violates project ownership, resource limits, or isolation boundaries. ## Type Delivery ## Parent M2: Coordinator Reference ## Objective Implement typed claims, capacity limits, workspace conflict detection, expiration, release, and receipt integration. ## Acceptance criteria - Claims identify issue, agent, workspace, scope, and expiration. - Coordinator capacity is enforced. - Overlapping mutable scope is rejected. - Read-only scope may coexist when policy permits. - Expired claims cannot authorize dispatch. - Release is idempotent and recorded. - Claim assertions are derived from valid claim state. - Tests cover capacity, overlap, expiration, coexistence, and release. ## Evidence required - Claim model and registry. - Positive and negative tests. - Updated coordinator integration. - Conformance results. ## Constraints - In-memory reference registry only. - No provider-specific lock service. - No distributed-consensus claim. ## Permissions - Local code, tests, fixtures, and documentation: allowed. - External actions: not authorized. ## Stop conditions - Scope overlap cannot be represented without provider-specific paths. - Claim release can silently erase execution history. ## Result The reference registry enforces global capacity, isolates workspaces, detects hierarchical mutable-scope conflicts, permits read-only coexistence, expires authority, records repeated release attempts, and derives subject-bound claim assertions from active state. ## Status Verified / Tested --- FILE: work/IEPE-CORE-010.md (64 lines, 2.3 KiB) --- # IEPE-CORE-010: Add Epistemic Stress Testing ## Intent Expose hidden assumptions and unknown variables before promotion by testing frozen candidates against controlled conditions they were not optimized to satisfy. ## Type Delivery ## Parent M2: Coordinator Reference ## Objective Add designed perturbations, sealed World Cards, surprise budgets, robustness profiles, and an unknown-variable ledger to the IEPE protocol and conformance suite. ## Acceptance criteria - Epistemic stress testing is distinct from ordinary evaluation and random disruption. - Perturbations declare protected invariants and changed conditions. - World Cards remain sealed until a candidate-freeze gate. - Robustness dispositions include robust, adaptable, bounded, fragile, unsafe, and unknown. - Unknown variables are classified rather than collapsed into one uncertainty field. - Projects can define a surprise budget. - One existing candidate completes at least two synthetic blind counterfactual trials. - Stress trials cannot silently change project intent or promotion authority. - Human-outcome claims remain unvalidated without observation. ## Evidence required - Protocol document. - Contract schemas and conformance fixtures. - GitHub issue template. - Synthetic World Cards and robustness profile. - Updated unknown-variable ledger. - Conformance results. ## Constraints - Initial trials are synthetic. - No random destructive mutations. - Protected human, safety, consent, identity, and authority invariants cannot be perturbed away. - Do not treat fragility as universal failure when the validity boundary can be stated honestly. ## Permissions - Local documents, schemas, templates, examples, and evaluation artifacts: allowed. - External experiments, communications, deployment, and spending: not authorized. ## Stop conditions - A perturbation changes the governing purpose rather than testing its realization. - The evaluator lacks authority or evidence for the resulting claim. - A trial could create an external consequence. ## Result Two sealed synthetic World Cards were revealed after Candidate B was frozen. The trials produced bounded and adaptable dispositions, constrained promotion, and added three classified unknowns without making a human-outcome claim. ## Status Verified / Tested --- FILE: work/IEPE-CORE-011.md (29 lines, 0.9 KiB) --- # IEPE-CORE-011: Assemble Bounded Context Packets ## Intent Give a worker the minimum sufficient, authority-ordered context required to execute one claimed issue without silently expanding scope. ## Type Delivery ## Parent M2: Coordinator Reference ## Acceptance criteria - Packets bind issue, claim, intent, authority, dependencies, constraints, evidence requirements, permissions, and stop conditions. - Missing mandatory context blocks dispatch. - Authority conflicts are surfaced rather than flattened. - Packet construction is deterministic and provider-neutral. - Tests cover complete, missing, conflicting, and excess-context cases. ## Result Context packets now bind issue and active claim, order selected sources by authority, include dependency state and execution boundaries, surface conflicts, omit unrelated corpus material, enforce a source limit, and retain a deterministic digest. ## Status Verified / Tested --- FILE: work/IEPE-CORE-012.md (30 lines, 1.1 KiB) --- # IEPE-CORE-012: Specify New and Existing Project Initialization ## Intent Make IEPE adoption portable to both greenfield and established projects without confusing conversation, current behavior, or historical tickets with governing authority. ## Type Documentation ## Parent M1: Adoption Kit ## Acceptance criteria - New-project initialization defines conversation capture, governing structure, zero-state baseline, first milestone, and first Ready issue. - Existing-project initialization begins with read-only discovery and provenance-aware reconciliation. - Conversational initialization separates user statements from agent inference. - Domain profiles extend evaluation without replacing core semantics. - Initialization gates and operational handoff are explicit. - Proposed commands are labeled unimplemented. ## Result `docs/INITIALIZATION.md` defines both entry modes, their convergence conditions, project-profile boundary, conversational entry, and handoff into the coordinator loop. `docs/ADOPTION.md` now routes adopters through these modes. ## Status Verified / Documented --- FILE: work/IEPE-CORE-013.md (30 lines, 0.9 KiB) --- # IEPE-CORE-013: Implement Agent Project Packages ## Intent Compile canonical project sources into a versioned agent-operable package without allowing generated context to become authority. ## Type Delivery ## Parent M1: Adoption Kit ## Acceptance criteria - Package planes separate governance, context, procedure, adapters, runtime, and integrity. - A manifest records source roles, authority ranks, state, hashes, outputs, skills, adapters, and exclusions. - The compiler rejects missing, unsafe, machine-generated, and duplicate sources. - Release packages require clean source state. - Identical inputs produce byte-identical outputs. - Generated artifacts remain non-authoritative. ## Result The reference compiler produces a deterministic operating contract, context index, compiled corpus, and integrity manifest. It records skills and adapters while rejecting unsafe inputs and dishonest release state. ## Status Verified / Tested --- FILE: work/IEPE-CORE-014.md (30 lines, 1.1 KiB) --- # IEPE-CORE-014: Define Worker Dispatch Interfaces ## Intent Dispatch a bounded context packet to a worker through a provider-neutral interface while preserving worker identity, permissions, result provenance, and stop-state behavior. ## Type Delivery ## Parent M2: Coordinator Reference ## Acceptance criteria - Dispatch binds issue, claim, context digest, worker identity, role, and attempt. - Provider adapters cannot expand packet permissions. - Worker results distinguish completed, failed, blocked, and stopped outcomes. - Results retain artifact, observation, command, cost, and limitation references. - Duplicate dispatch and stale result conditions are rejected. - Tests cover success, failure, permission expansion, stale context, and retry identity. ## Result Dispatch envelopes now bind worker identity, role, issue, claim, context digest, permissions, and attempt. Results preserve distinct terminal outcomes and evidence provenance. Stale context, permission expansion, duplicate work, and invalid retry lineage are rejected. ## Status Verified / Tested --- FILE: work/IEPE-CORE-015.md (84 lines, 2.3 KiB) --- # IEPE-CORE-015: Qualify Worker Evidence Intake ## Intent Convert worker artifacts and observations into evidence assertions without allowing completion language or adapter success to overstate maturity. ## Type Delivery ## Parent M2: Coordinator Reference ## Owner IEPE Core coordinator ## Dependencies - IEPE-CORE-006 - IEPE-CORE-007 - IEPE-CORE-008 - IEPE-CORE-014 ## Objective Implement evidence qualification rules that bind worker output to dispatch lineage, evaluate multi-dimensional evidence, retain negative results, and block overclaimed maturity promotion. ## Scope - Define intake binding across worker dispatches, candidates, evaluators, and environments. - Enforce structural separation between artifact creation, execution, testing, and empirical validation. - Implement qualification checks that reject missing provenance, unverified assertions, or invalid claims. - Retain negative and inconclusive evidence bundles for institutional memory. ## Acceptance criteria - Intake binds evidence to dispatch, issue, candidate, environment, and evaluator. - Artifact existence is distinct from evaluation. - Qualification cannot exceed its strongest valid evidence. - Missing provenance, reproduction, or required dimensions blocks promotion recommendation. - Negative and inconclusive results remain retained. - Tests cover documented, implemented, tested, invalid, and overclaimed evidence. ## Evidence required - Coordinator evidence qualification unit tests. - Validation results for valid, invalid, and overclaimed evidence bundles. - Negative-result retention receipts. ## Constraints - Domain-neutral evaluator interfaces only. - Do not grant authority based on worker self-reporting or completion text. - Maintain four-tier maturity taxonomy. ## Exclusions - Domain-specific test runner adapters. - Provider-specific webhooks. ## Permissions - Write within `IEPE-Core` and temporary test directories. - No network, external repository, deployment, or spending authority. ## Budget - One bounded implementation cycle with local deterministic tests. ## Stop conditions - An evidence claim cannot be evaluated without domain-specific runtime assumptions. - Invalid provenance or missing issue contracts cannot be trapped by coordinator intake. ## Status Ready ## Claim maturity Specified --- FILE: work/IEPE-CORE-016.md (83 lines, 3.0 KiB) --- # IEPE-CORE-016: Implement Reference-Pinned Project Bootstrap ## Intent Make IEPE directly usable when starting a new agent or project by generating a local operating layer that references a versioned IEPE Core source without copying project-specific assumptions into the protocol. ## Type Delivery ## Parent M1: Adoption Kit ## Owner IEPE Core coordinator ## Dependencies - IEPE-CORE-012 - IEPE-CORE-013 - IEPE-CORE-014 ## Scope - Define a machine-readable upstream protocol reference. - Implement deterministic greenfield scaffolding and read-only existing-project discovery. - Generate a compact `AGENTS.md`, project profile, coordinator configuration, package-source declaration, and first-cycle prompt. - Bind Agent Project Packages to the upstream protocol reference. - Document the adoption and update boundary. ## Exclusions - Creating or configuring a live GitHub repository or Project. - Installing credentials or provider applications. - Inferring production authority from repository access. - Automatically rewriting an established project's governing documentation. ## Acceptance criteria - A new project can be initialized from one command with an explicit IEPE source and immutable revision. - The generated project separates upstream invariants from local intent, profile, skills, adapters, and evidence. - A new agent receives an unambiguous read-only first-cycle prompt. - Existing-project discovery performs no writes unless an external report path is explicitly supplied. - Package manifests retain the pinned IEPE protocol identity and revision. - Repeated initialization with identical inputs produces identical files. - Existing files are never overwritten without explicit authorization. - Tests cover generation, determinism, overwrite refusal, read-only discovery, and protocol provenance. ## Required evidence - IEPE conformance suite - Bootstrap unit tests - A generated synthetic project that compiles into a valid Agent Project Package - A deliberate overwrite refusal ## Permissions - Write within `IEPE-Core` and temporary test directories. - No network, external repository, provider, deployment, publication, or credential mutation. ## Budget - One bounded implementation cycle with local deterministic tests. ## Stop conditions - The upstream reference cannot be represented without inventing a canonical repository URL. - Existing IEPE schemas require an incompatible authority change. - Validation would require live provider access. ## Definition of done The bootstrap and provenance contracts are implemented, documented, tested, recorded in evidence, and honestly classified by maturity. ## Result IEPE Core now generates a deterministic, reference-pinned operating layer for new projects and performs read-only discovery for established projects. The generated layer includes local intent and profile authority, a protocol pin, coordinator runtime, six narrow process skills, package-source declaration, and a first-agent reconciliation prompt. Compiled packages retain protocol provenance. ## Status Verified / Tested ======================================================================== ## SUBSYSTEM: VERIFICATION & EXECUTION EVIDENCE (17 files) ======================================================================== --- FILE: evidence/IEPE-CORE-002-evidence.json (66 lines, 2.6 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-002.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-002", "candidateId": null, "artifactRefs": [ "schemas/project-profile.schema.json", "schemas/experience-contract.schema.json", "schemas/evaluation-record.schema.json", "schemas/promotion-record.schema.json", "schemas/issue-contract.schema.json", "schemas/evidence-bundle.schema.json", ".github/ISSUE_TEMPLATE/design.yml", ".github/ISSUE_TEMPLATE/evaluation.yml", ".github/ISSUE_TEMPLATE/decision.yml", ".github/ISSUE_TEMPLATE/incident.yml", ".github/ISSUE_TEMPLATE/promotion.yml", ".github/ISSUE_TEMPLATE/delivery.yml", ".github/ISSUE_TEMPLATE/experiment.yml" ], "intentRefs": ["README.md#first-milestone", "ROADMAP.md#m1-adoption-kit"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": { "jsonSchemaDialect": "2020-12", "jsonSchemaValidator": "jsonschema 4.26.0", "yamlParser": "PyYAML", "executionClass": "local isolated validation" }, "inputs": ["representative positive fixture per schema", "empty-object negative fixture per schema"], "provenance": ["IEPE-CORE-002 execution cycle"], "evaluations": [ { "dimension": "schema correctness", "result": "6 of 6 schemas accepted valid fixtures and rejected invalid fixtures", "evaluator": "Draft202012Validator", "evidenceRefs": ["validation output"] }, { "dimension": "template structure", "result": "7 of 7 YAML templates parsed with unique field identifiers", "evaluator": "PyYAML structural evaluator", "evidenceRefs": ["validation output"] }, { "dimension": "domain neutrality", "result": "one residual originating-project reference found and corrected; no runtime dependency remains", "evaluator": "literal terminology audit", "evidenceRefs": ["README.md"] } ], "baselineComparison": { "before": "2 schemas and 2 issue templates", "after": "6 schemas and 7 issue templates" }, "cost": null, "tradeoffs": ["Templates prioritize completeness over compact issue entry"], "limitations": [ "No live GitHub rendering test was available", "Fixtures cover structural contracts rather than all semantic edge cases", "No external project has adopted the suite" ], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Validate every schema with Draft 2020-12 positive and negative fixtures; parse every issue template as YAML and assert unique body IDs." } --- FILE: evidence/IEPE-CORE-003-evidence.json (56 lines, 2.1 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-003.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-003", "candidateId": null, "artifactRefs": [ "tools/validate.py", "fixtures/conformance.json", "requirements-dev.txt", "README.md" ], "intentRefs": ["ROADMAP.md#m1-adoption-kit"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": { "python": "3.12", "jsonSchemaDialect": "2020-12", "dependencySource": "requirements-dev.txt" }, "inputs": ["six positive fixtures", "six empty-object negative fixtures", "deliberate forbidden-term probe"], "provenance": ["IEPE-CORE-003 execution cycle"], "evaluations": [ { "dimension": "reproducibility", "result": "one repository-owned command validates the current contract suite", "evaluator": "tools/validate.py", "evidenceRefs": ["clean conformance output"] }, { "dimension": "failure behavior", "result": "deliberate forbidden-term violation returned status 1", "evaluator": "negative conformance probe", "evidenceRefs": ["negative probe output"] }, { "dimension": "coverage", "result": "6 schemas, 7 issue templates, 1 prior evidence bundle, and domain neutrality passed", "evaluator": "tools/validate.py", "evidenceRefs": ["clean conformance output"] } ], "baselineComparison": { "before": "validation depended on an undeclared environment-specific command", "after": "dependencies, fixtures, and validation behavior are repository-owned" }, "cost": null, "tradeoffs": ["Development validation requires Python dependencies rather than a zero-dependency binary"], "limitations": [ "The runner has not been exercised in continuous integration", "The runner validates structural conformance, not project-specific semantic quality", "No external adopter has executed the command" ], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Install requirements-dev.txt and run python3 tools/validate.py. Set IEPE_FORBIDDEN_TERMS to audit adoption-specific leakage." } --- FILE: evidence/IEPE-CORE-004-evidence.json (66 lines, 2.9 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-004.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-004", "candidateId": "example.exhibition-guide", "artifactRefs": [ "examples/exhibition-guide/INTENT.md", "examples/exhibition-guide/records/project-profile.json", "examples/exhibition-guide/records/experience-contract.json", "examples/exhibition-guide/records/issue-contract.json", "examples/exhibition-guide/candidates/candidate-a-route-led.md", "examples/exhibition-guide/candidates/candidate-b-choice-led.md", "examples/exhibition-guide/records/evaluation-record.json", "examples/exhibition-guide/negative-results.md", "examples/exhibition-guide/records/evidence-bundle.json", "examples/exhibition-guide/records/promotion-record.json", "examples/exhibition-guide/coordinator-trace.md" ], "intentRefs": ["ROADMAP.md#m1-adoption-kit", "work/IEPE-CORE-004.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": { "type": "synthetic cross-domain pilot", "externalSideEffects": false }, "inputs": ["two editorial candidate structures", "one experience contract", "one synthetic baseline"], "provenance": ["IEPE-CORE-004 coordinator cycle"], "evaluations": [ { "dimension": "schema conformance", "result": "6 of 6 example records validate", "evaluator": "tools/validate.py", "evidenceRefs": ["examples/exhibition-guide/conformance-manifest.json"] }, { "dimension": "editorial constraints", "result": "both candidates remain below 180 words", "evaluator": "word-count audit", "evidenceRefs": ["examples/exhibition-guide/candidates"] }, { "dimension": "negative-result retention", "result": "route-led direction retained with contextual rejection rationale", "evaluator": "coordinator record audit", "evidenceRefs": ["examples/exhibition-guide/negative-results.md"] }, { "dimension": "human experience", "result": "not observed and not claimed", "evaluator": "evidence-boundary audit", "evidenceRefs": ["examples/exhibition-guide/README.md"] } ], "baselineComparison": { "before": "core schemas and templates had no complete cross-domain example", "after": "one non-software example completes the internal protocol path" }, "cost": { "external": 0, "candidateIterations": 2 }, "tradeoffs": ["The pilot demonstrates structural portability but supplies no field evidence"], "limitations": [ "Synthetic project", "Partially independent rule-based evaluation", "No real visitor observation", "No live project-management provider" ], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run tools/validate.py, audit candidate word counts, and compare the two candidates against the experience contract." } --- FILE: evidence/IEPE-CORE-005-evidence.json (51 lines, 2.3 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-005.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-005", "candidateId": "migration.incremental.1", "artifactRefs": [ "docs/MIGRATION.md", "schemas/migration-record.schema.json", "examples/legacy-migration/before.json", "examples/legacy-migration/records/historical.json", "examples/legacy-migration/records/active.json", "examples/legacy-migration/records/new.json", "examples/legacy-migration/after.md" ], "intentRefs": ["ROADMAP.md#m1-adoption-kit", "work/IEPE-CORE-005.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": { "type": "synthetic legacy backlog migration", "provider": "local reference" }, "inputs": ["one historical item", "one active item", "one new item"], "provenance": ["IEPE-CORE-005 coordinator cycle"], "evaluations": [ { "dimension": "record conformance", "result": "3 migration records validate against the migration schema", "evaluator": "tools/validate.py", "evidenceRefs": ["examples/legacy-migration/conformance-manifest.json"] }, { "dimension": "status honesty", "result": "no source status was converted into unsupported evidence maturity", "evaluator": "migration outcome audit", "evidenceRefs": ["examples/legacy-migration/after.md"] }, { "dimension": "identity preservation", "result": "all source item identifiers and relationships remain represented", "evaluator": "before-and-after audit", "evidenceRefs": ["examples/legacy-migration/before.json", "examples/legacy-migration/after.md"] } ], "baselineComparison": { "before": "adoption guide stated a migration rule without an executable record model", "after": "migration classes, sequence, schema, fixture, and stop conditions are tested" }, "cost": null, "tradeoffs": ["Incremental adoption leaves some historical records intentionally sparse"], "limitations": ["Synthetic provider", "No live project migration", "No rollback executed against an external system"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run tools/validate.py and compare the legacy-migration before and after artifacts." } --- FILE: evidence/IEPE-CORE-006-evidence.json (53 lines, 2.1 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-006.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-006", "candidateId": "coordinator.state-machine.1", "artifactRefs": [ "iepe_core/coordinator.py", "tests/test_coordinator.py", "evidence/traces/coordinator-traces.json", "docs/COORDINATOR.md" ], "intentRefs": ["ROADMAP.md#m2-coordinator-reference", "work/IEPE-CORE-006.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": { "type": "local deterministic reference", "language": "Python 3.12" }, "inputs": ["valid delivery", "valid experiment", "invalid transition", "missing gate evidence", "ambiguous workspace stop"], "provenance": ["IEPE-CORE-006 coordinator cycle"], "evaluations": [ { "dimension": "valid state progression", "result": "delivery and experiment reach complete through 12 guarded transitions", "evaluator": "unittest", "evidenceRefs": ["tests/test_coordinator.py", "evidence/traces/coordinator-traces.json"] }, { "dimension": "invalid transition safety", "result": "direct preflight-to-claim transition rejected", "evaluator": "unittest", "evidenceRefs": ["tests/test_coordinator.py"] }, { "dimension": "stop-state integrity", "result": "stop receipt preserves reason, originating state, evidence, and resumption authority", "evaluator": "unittest", "evidenceRefs": ["evidence/traces/coordinator-traces.json"] } ], "baselineComparison": { "before": "coordinator existed only as a documented sequence", "after": "provider-neutral executable state machine with seven tests and terminal receipts" }, "cost": null, "tradeoffs": ["Gate evidence is represented by string assertions in this first reference"], "limitations": [ "No live provider adapter", "No worker spawning", "No persistence across process restarts", "Evidence assertions are not yet typed or cryptographically bound" ], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Install development requirements and run python3 tools/validate.py." } --- FILE: evidence/IEPE-CORE-007-evidence.json (47 lines, 2.0 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-007.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-007", "candidateId": "coordinator.typed-assertions.1", "artifactRefs": [ "iepe_core/coordinator.py", "tests/test_coordinator.py", "evidence/traces/coordinator-typed-traces.json" ], "intentRefs": ["ROADMAP.md#m2-coordinator-reference", "work/IEPE-CORE-007.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": { "type": "local deterministic reference", "language": "Python 3.12" }, "inputs": ["valid typed path", "wrong assertion type", "wrong subject", "invalidated assertion"], "provenance": ["IEPE-CORE-007 coordinator cycle"], "evaluations": [ { "dimension": "typed gate integrity", "result": "required gate kind, issue subject, and validity are enforced", "evaluator": "unittest", "evidenceRefs": ["tests/test_coordinator.py"] }, { "dimension": "compatibility", "result": "valid delivery and experiment cycles continue to complete", "evaluator": "unittest", "evidenceRefs": ["evidence/traces/coordinator-typed-traces.json"] }, { "dimension": "negative-path coverage", "result": "wrong type, wrong subject, invalid assertion, missing assertion, and invalid transition reject", "evaluator": "unittest", "evidenceRefs": ["tests/test_coordinator.py"] } ], "baselineComparison": { "before": "gate satisfaction depended on caller-supplied strings", "after": "gates require typed, subject-bound, valid assertions with retained identities" }, "cost": null, "tradeoffs": ["Assertions remain locally issued and are not cryptographically attested"], "limitations": ["No trust registry", "No cryptographic signature", "No persisted revocation state"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 tools/validate.py and inspect the ten coordinator test cases." } --- FILE: evidence/IEPE-CORE-008-evidence.json (59 lines, 2.3 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-008.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-008", "candidateId": "coordinator.receipt-replay.1", "artifactRefs": [ "iepe_core/receipts.py", "iepe_core/coordinator.py", "tests/test_receipts.py", "tests/test_coordinator.py" ], "intentRefs": ["ROADMAP.md#m2-coordinator-reference", "work/IEPE-CORE-008.md"], "authorityRefs": ["docs/PROTOCOL.md", "docs/COORDINATOR.md", "AGENTS.md"], "environment": { "type": "local deterministic reference", "language": "Python 3.12", "digest": "SHA-256" }, "inputs": ["completed receipt", "stopped receipt", "tampered payload", "unsupported version", "impossible history", "wrong subject", "missing provenance"], "provenance": ["IEPE-CORE-008 coordinator cycle"], "evaluations": [ { "dimension": "round-trip persistence", "result": "completed and stopped receipts serialize and replay successfully", "evaluator": "unittest", "evidenceRefs": ["tests/test_receipts.py"] }, { "dimension": "integrity", "result": "altered payload fails SHA-256 integrity verification", "evaluator": "unittest", "evidenceRefs": ["tests/test_receipts.py"] }, { "dimension": "history validity", "result": "re-signed but impossible transition history is rejected", "evaluator": "unittest", "evidenceRefs": ["tests/test_receipts.py"] }, { "dimension": "assertion provenance", "result": "wrong subject and missing evidence references reject during replay", "evaluator": "unittest", "evidenceRefs": ["tests/test_receipts.py"] } ], "baselineComparison": { "before": "execution receipts existed only as in-memory dataclasses", "after": "versioned deterministic envelopes support integrity checking and replay validation" }, "cost": null, "tradeoffs": ["JSON favors inspectability over compact binary representation"], "limitations": [ "SHA-256 digest is not an identity signature", "No external durable store", "No cross-process resumption implementation", "No schema migration beyond rejecting unsupported versions" ], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 tools/validate.py and inspect tests/test_receipts.py." } --- FILE: evidence/IEPE-CORE-009-evidence.json (26 lines, 1.9 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-009.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-009", "candidateId": "coordinator.claim-registry.1", "artifactRefs": ["iepe_core/claims.py", "tests/test_claims.py", "iepe_core/__init__.py"], "intentRefs": ["ROADMAP.md#m2-coordinator-reference", "work/IEPE-CORE-009.md"], "authorityRefs": ["docs/PROTOCOL.md", "docs/COORDINATOR.md", "AGENTS.md"], "environment": {"type": "local deterministic reference", "language": "Python 3.12"}, "inputs": ["capacity limits", "hierarchical scopes", "read and write modes", "expiration", "repeated release"], "provenance": ["IEPE-CORE-009 coordinator cycle"], "evaluations": [ {"dimension": "capacity and conflict", "result": "excess capacity and overlapping mutable scope are rejected", "evaluator": "unittest", "evidenceRefs": ["tests/test_claims.py"]}, {"dimension": "coexistence", "result": "read-only overlap and separate workspaces coexist", "evaluator": "unittest", "evidenceRefs": ["tests/test_claims.py"]}, {"dimension": "lifecycle", "result": "expiration invalidates authority and repeated release preserves history", "evaluator": "unittest", "evidenceRefs": ["tests/test_claims.py"]}, {"dimension": "gate provenance", "result": "claim.valid assertions derive from matching active registry state", "evaluator": "unittest", "evidenceRefs": ["tests/test_claims.py"]} ], "baselineComparison": {"before": "claim gates accepted manually constructed assertions", "after": "a typed registry derives claim assertions from active state"}, "cost": null, "tradeoffs": ["hierarchical string scopes favor portability over provider-specific lock precision"], "limitations": ["in-memory only", "no distributed consensus", "expiration cleanup is evaluated lazily"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 tools/validate.py and inspect tests/test_claims.py." } --- FILE: evidence/IEPE-CORE-010-evidence.json (25 lines, 2.0 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-010.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-010", "candidateId": "epistemic-stress-testing.1", "artifactRefs": ["docs/EPISTEMIC_STRESS_TESTING.md", "schemas/perturbation.schema.json", "schemas/world-card.schema.json", "schemas/robustness-profile.schema.json", "schemas/unknown-variable-ledger.schema.json", "examples/exhibition-guide/stress/trial-report.md"], "intentRefs": ["ROADMAP.md", "work/IEPE-CORE-010.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": {"type": "local synthetic blind counterfactual trial", "worldCards": 2}, "inputs": ["frozen editorial candidate", "format-loss World Card", "dependency-loss World Card"], "provenance": ["IEPE-CORE-010 protocol cycle"], "evaluations": [ {"dimension": "contract conformance", "result": "four new record types validate", "evaluator": "tools/validate.py", "evidenceRefs": ["fixtures/conformance.json"]}, {"dimension": "blind perturbation procedure", "result": "candidate freeze precedes two World Card reveals", "evaluator": "synthetic independent review", "evidenceRefs": ["examples/exhibition-guide/stress/trial-report.md"]}, {"dimension": "epistemic honesty", "result": "human comprehension remains explicitly unvalidated", "evaluator": "protocol review", "evidenceRefs": ["examples/exhibition-guide/stress/unknown-variable-ledger.json"]} ], "baselineComparison": {"before": "known contracts tested only under declared conditions", "after": "frozen candidates can be tested against sealed changed conditions with bounded claims"}, "cost": null, "tradeoffs": ["synthetic cards improve assumption discovery but do not replace field observation"], "limitations": ["initial trials are synthetic", "steward independence is procedural rather than organizational"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 tools/validate.py and inspect examples/exhibition-guide/stress/trial-report.md." } --- FILE: evidence/IEPE-CORE-011-evidence.json (26 lines, 2.1 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-011.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-011", "candidateId": "bounded-context-packet.1", "artifactRefs": ["schemas/context-packet.schema.json", "iepe_core/context.py", "tests/test_context.py"], "intentRefs": ["ROADMAP.md#m2-coordinator-reference", "work/IEPE-CORE-011.md"], "authorityRefs": ["docs/PROTOCOL.md", "docs/COORDINATOR.md", "AGENTS.md"], "environment": {"type": "local deterministic reference", "language": "Python 3.12", "digest": "SHA-256"}, "inputs": ["active claim", "intent references", "authority references", "dependency states", "permissions", "evidence requirements", "stop conditions"], "provenance": ["IEPE-CORE-011 coordinator cycle"], "evaluations": [ {"dimension": "claim binding", "result": "expired or mismatched claims block packet assembly", "evaluator": "unittest", "evidenceRefs": ["tests/test_context.py"]}, {"dimension": "context sufficiency", "result": "missing mandatory sources or dependency state blocks assembly", "evaluator": "unittest", "evidenceRefs": ["tests/test_context.py"]}, {"dimension": "authority integrity", "result": "conflicting assertions for one subject are surfaced", "evaluator": "unittest", "evidenceRefs": ["tests/test_context.py"]}, {"dimension": "boundedness and determinism", "result": "unreferenced sources are omitted, limits are enforced, and repeated assembly is identical", "evaluator": "unittest", "evidenceRefs": ["tests/test_context.py"]} ], "baselineComparison": {"before": "the coordinator required a context gate without a packet implementation", "after": "typed claim-bound packets deterministically select mandatory project context"}, "cost": null, "tradeoffs": ["conflicting assertions block assembly instead of automatically resolving through precedence"], "limitations": ["packet includes source hashes rather than embedding source bodies", "no token-budget estimator", "no remote context store"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 tools/validate.py and inspect tests/test_context.py." } --- FILE: evidence/IEPE-CORE-012-evidence.json (25 lines, 1.9 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-012.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-012", "candidateId": "initialization-protocol.1", "artifactRefs": ["docs/INITIALIZATION.md", "docs/ADOPTION.md", "work/IEPE-CORE-012.md"], "intentRefs": ["ROADMAP.md#m1-adoption-kit", "work/IEPE-CORE-012.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": {"type": "documentation review"}, "inputs": ["new-project adoption path", "existing-project reconciliation path", "conversational entry", "domain profiles"], "provenance": ["IEPE-CORE-012 documentation cycle"], "evaluations": [ {"dimension": "entry-mode coverage", "result": "greenfield and existing-project procedures are explicit", "evaluator": "documentation review", "evidenceRefs": ["docs/INITIALIZATION.md"]}, {"dimension": "authority preservation", "result": "conversation, observed behavior, and historical work cannot silently become governing intent", "evaluator": "protocol review", "evidenceRefs": ["docs/INITIALIZATION.md#mode-b-existing-project"]}, {"dimension": "maturity honesty", "result": "proposed command interface is labeled unimplemented", "evaluator": "conformance review", "evidenceRefs": ["docs/INITIALIZATION.md#proposed-command-interface"]} ], "baselineComparison": {"before": "adoption guide provided a minimum checklist and migration pointer", "after": "two complete initialization paths converge on an explicit operational handoff"}, "cost": null, "tradeoffs": ["the protocol specifies initializer behavior before implementing its command interface"], "limitations": ["no initializer CLI", "no external-project pilot of conversational initialization"], "qualification": "documented", "promotionRecommendation": "promote", "reproduction": "Read docs/INITIALIZATION.md and run python3 tools/validate.py." } --- FILE: evidence/IEPE-CORE-013-evidence.json (26 lines, 2.4 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-013.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-013", "candidateId": "agent-project-package.1", "artifactRefs": ["docs/AGENT_PROJECT_PACKAGE.md", "schemas/agent-package-manifest.schema.json", "tools/compile_package.py", "tests/test_package_compiler.py", "examples/agent-package/output/agent-package-manifest.json"], "intentRefs": ["ROADMAP.md#m1-adoption-kit", "work/IEPE-CORE-013.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": {"type": "local deterministic compiler", "language": "Python 3.12", "digest": "SHA-256"}, "inputs": ["declared canonical sources", "operating contract", "skills", "adapters", "source state", "exclusions"], "provenance": ["IEPE-CORE-013 package compilation cycle"], "evaluations": [ {"dimension": "determinism", "result": "identical input produces byte-identical manifest and corpus", "evaluator": "unittest", "evidenceRefs": ["tests/test_package_compiler.py"]}, {"dimension": "source safety", "result": "missing, escaping, cache, bytecode, and duplicate paths are rejected", "evaluator": "unittest and compiler validation", "evidenceRefs": ["tests/test_package_compiler.py", "tools/compile_package.py"]}, {"dimension": "release integrity", "result": "release classification requires clean source state", "evaluator": "unittest", "evidenceRefs": ["tests/test_package_compiler.py"]}, {"dimension": "authority preservation", "result": "generated artifacts are explicitly non-authoritative projections", "evaluator": "protocol review", "evidenceRefs": ["docs/AGENT_PROJECT_PACKAGE.md"]} ], "baselineComparison": {"before": "project agent files and compiled context had no portable package contract", "after": "a deterministic manifest and compiler bind governance, context, skills, adapters, provenance, and integrity"}, "cost": null, "tradeoffs": ["the initial compiler accepts an explicit source list rather than discovering authority automatically"], "limitations": ["no archive writer", "no signature beyond SHA-256 integrity", "no repository-state detector", "no external project package conformance run"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 tools/compile_package.py --config examples/agent-package/package-source.json --output examples/agent-package/output and python3 tools/validate.py." } --- FILE: evidence/IEPE-CORE-014-evidence.json (26 lines, 2.0 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-014.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-014", "candidateId": "worker-dispatch-interface.1", "artifactRefs": ["schemas/worker-dispatch.schema.json", "iepe_core/dispatch.py", "tests/test_dispatch.py"], "intentRefs": ["ROADMAP.md#m2-coordinator-reference", "work/IEPE-CORE-014.md"], "authorityRefs": ["docs/PROTOCOL.md", "docs/COORDINATOR.md", "AGENTS.md"], "environment": {"type": "local provider-neutral reference", "language": "Python 3.12"}, "inputs": ["active claim", "context digest", "worker identity", "role", "attempt", "permissions", "worker result"], "provenance": ["IEPE-CORE-014 coordinator cycle"], "evaluations": [ {"dimension": "permission containment", "result": "dispatch cannot enable permission denied by the context packet", "evaluator": "unittest", "evidenceRefs": ["tests/test_dispatch.py"]}, {"dimension": "provenance", "result": "result must match issue, claim, context, worker, and attempt", "evaluator": "unittest", "evidenceRefs": ["tests/test_dispatch.py"]}, {"dimension": "outcome fidelity", "result": "completed, failed, blocked, and stopped remain distinct", "evaluator": "unittest", "evidenceRefs": ["tests/test_dispatch.py"]}, {"dimension": "retry safety", "result": "duplicate work, active overlap, stale context, and invalid attempt sequence are rejected", "evaluator": "unittest", "evidenceRefs": ["tests/test_dispatch.py"]} ], "baselineComparison": {"before": "coordinator dispatch was represented only by a gate assertion", "after": "typed envelopes and results preserve permission, identity, context, attempt, and evidence lineage"}, "cost": null, "tradeoffs": ["the reference registry is synchronous and in-memory"], "limitations": ["no provider execution adapter", "no cancellation channel", "no durable queue", "no measured token or compute usage"], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 -m unittest tests.test_dispatch -v." } --- FILE: evidence/IEPE-CORE-016-evidence.json (82 lines, 3.9 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-core-016.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-016", "candidateId": "reference-pinned-project-bootstrap.1", "artifactRefs": [ "docs/INITIALIZATION.md", "docs/UPSTREAM_REFERENCE.md", "schemas/protocol-reference.schema.json", "schemas/agent-package-source.schema.json", "iepe_core/bootstrap.py", "tools/init_project.py", "tests/test_bootstrap.py", ".agents/skills/initialize-iepe-project/SKILL.md" ], "intentRefs": ["ROADMAP.md#m1-adoption-kit", "work/IEPE-CORE-016.md"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md", "docs/AGENT_PROJECT_PACKAGE.md"], "environment": { "type": "local deterministic reference and synthetic cross-domain pilot", "language": "Python 3.12", "validation": "jsonschema 4.26.0 and PyYAML 6.0.3 in isolated environment" }, "inputs": [ "project identity and originating intent", "explicit IEPE source and immutable revision", "work-graph provider", "evaluators", "promotion authority" ], "provenance": ["IEPE-CORE-016 implementation and conformance cycle"], "evaluations": [ { "dimension": "deterministic initialization", "result": "identical inputs produce identical generated files", "evaluator": "unittest", "evidenceRefs": ["tests/test_bootstrap.py"] }, { "dimension": "authority and overwrite safety", "result": "existing files are preserved without explicit overwrite and existing-project discovery preserves all inspected bytes", "evaluator": "unittest and synthetic pilot", "evidenceRefs": ["tests/test_bootstrap.py", "tools/init_project.py"] }, { "dimension": "protocol provenance", "result": "project profile, package source, and compiled manifest retain the same IEPE identity, source, version, and revision", "evaluator": "schema validation and package compiler", "evidenceRefs": ["schemas/protocol-reference.schema.json", "schemas/project-profile.schema.json", "schemas/agent-package-source.schema.json", "schemas/agent-package-manifest.schema.json"] }, { "dimension": "agent operability", "result": "a synthetic design project generated six validated process skills and an explicit read-only first-cycle prompt", "evaluator": "synthetic cross-domain bootstrap", "evidenceRefs": [".agents/skills", "iepe_core/bootstrap.py"] }, { "dimension": "repository conformance", "result": "16 schemas, 8 issue templates, 6 process skills, 14 evidence bundles, 16 example records, domain neutrality, and 46 reference tests pass", "evaluator": "tools/validate.py", "evidenceRefs": ["tools/validate.py", "tests/test_bootstrap.py"] } ], "baselineComparison": { "before": "initialization and command surfaces were documented but adopters had to assemble their own project-local operating layer", "after": "one command creates a reference-pinned, skill-equipped, package-ready project without claiming unresolved local authority" }, "cost": null, "tradeoffs": [ "the bootstrap projects procedural skill copies into the adopter while retaining upstream protocol authority", "greenfield defaults are explicitly provisional and require local confirmation before work becomes Ready" ], "limitations": [ "the initializer records but does not cryptographically resolve or attest the supplied upstream revision", "existing-project mode inventories but does not generate or apply a migration overlay", "conversational initialization is not implemented", "no live GitHub adapter or unrelated external project has completed the full IEPE trace" ], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Install requirements-dev.txt in an isolated environment, run python3 tools/validate.py, then run tools/init_project.py new and compile the generated .agents/package-source.json." } --- FILE: evidence/IEPE-INCIDENT-001-evidence.json (55 lines, 2.2 KiB) --- { "$schema": "../schemas/evidence-bundle.schema.json", "id": "evidence.iepe-incident-001.1", "projectId": "IEPE-CORE", "issueId": "IEPE-CORE-016", "candidateId": "livelock-prevention-v1", "artifactRefs": [ "docs/PROTOCOL.md", "docs/COORDINATOR.md", "docs/INITIALIZATION.md", "docs/NEGATIVE_RESULTS.md", "iepe_core/coordinator.py", "iepe_core/bootstrap.py", "schemas/project-profile.schema.json" ], "intentRefs": ["docs/PROTOCOL.md#constitutional-invariants"], "authorityRefs": ["docs/PROTOCOL.md", "AGENTS.md"], "environment": { "executionClass": "incident analysis and protocol synthesis" }, "inputs": ["SES project initialization governance livelock transcript"], "provenance": ["SES project adoption trial"], "evaluations": [ { "dimension": "livelock prevention", "result": "fingerprinted non-retryable blockers halt retries and transition to WAITING_EXTERNAL", "evaluator": "Coordinator reference state machine", "evidenceRefs": ["tests/test_coordinator.py"] }, { "dimension": "preflight capability probing", "result": "workspace write probe detects CAPABILITY_MISSING before discovery or overlay construction", "evaluator": "Bootstrap preflight probe", "evidenceRefs": ["tests/test_bootstrap.py"] }, { "dimension": "provisional profile generation", "result": "unassigned promotion authority yields profileStatus provisional without blocking initialization", "evaluator": "Bootstrap project profile generator", "evidenceRefs": ["tests/test_bootstrap.py"] } ], "baselineComparison": { "before": "livelock retries, capability checked late, promotion authority coupled to local setup", "after": "preflight capability probing, WAITING_EXTERNAL state, provisional profile support" }, "cost": null, "tradeoffs": ["Preflight write probe creates transient file in workspace"], "limitations": [ "Requires write access probe file cleanup" ], "qualification": "tested", "promotionRecommendation": "promote", "reproduction": "Run python3 -m pytest -v to execute test_coordinator.py and test_bootstrap.py livelock prevention tests." } --- FILE: evidence/traces/coordinator-traces.json (26 lines, 0.9 KiB) --- { "delivery": { "issueId": "DELIVERY-1", "finalState": "complete", "states": ["preflight", "reconcile", "select", "validate", "claim", "assemble_context", "dispatch", "observe", "evaluate", "disposition", "record", "close_loop", "complete"] }, "experiment": { "issueId": "EXPERIMENT-1", "finalState": "complete", "states": ["preflight", "reconcile", "select", "validate", "claim", "assemble_context", "dispatch", "observe", "evaluate", "disposition", "record", "close_loop", "complete"] }, "stopped": { "issueId": "STOP-1", "finalState": "stopped", "stoppedFrom": "preflight", "reason": "owning workspace is ambiguous", "resumeAuthority": "project owner", "evidence": ["workspace.conflict"] }, "invalidTransition": { "issueId": "INVALID-1", "source": "preflight", "attemptedTarget": "claim", "result": "rejected" } } --- FILE: evidence/traces/coordinator-typed-traces.json (23 lines, 1.0 KiB) --- { "valid": { "issueId": "EXPERIMENT-1", "finalState": "complete", "assertionIds": [ "assertion.EXPERIMENT-1.preflight.valid", "assertion.EXPERIMENT-1.state.reconciled", "assertion.EXPERIMENT-1.issue.selected", "assertion.EXPERIMENT-1.issue.ready", "assertion.EXPERIMENT-1.claim.valid", "assertion.EXPERIMENT-1.context.bounded", "assertion.EXPERIMENT-1.worker.dispatched", "assertion.EXPERIMENT-1.worker.result", "assertion.EXPERIMENT-1.evaluation.complete", "assertion.EXPERIMENT-1.disposition.selected", "assertion.EXPERIMENT-1.record.persisted", "assertion.EXPERIMENT-1.claim.released" ] }, "wrongType": { "required": "preflight.valid", "supplied": "issue.ready", "result": "rejected" }, "wrongSubject": { "issueId": "SUBJECT-1", "assertionSubject": "OTHER-ISSUE", "result": "rejected" }, "invalidated": { "assertionId": "assertion.INVALIDATED-1.preflight.valid", "valid": false, "result": "rejected" } } ======================================================================== ## SUBSYSTEM: OTHER PROTOCOL MODULES (2 files) ======================================================================== --- FILE: requirements-dev.txt (3 lines, 0.0 KiB) --- pytest==8.3.2 jsonschema==4.26.0 PyYAML>=6.0,<7.0 --- FILE: scripts/gen-llms.py (366 lines, 13.1 KiB) --- #!/usr/bin/env python3 """ gen-llms.py — Master Agent-First Publishing Architecture & Context Corpus Exporter for IEPE Protocol. Generates versioned llms index and full codebase corpus files in the top-level `.agents/` directory: .agents/llms.txt .agents/llms-iepe-v.txt .agents/llms-full.txt .agents/llms-full-iepe-v.txt """ import os import sys import re import json import glob import hashlib import subprocess from datetime import datetime ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..")) AGENTS_DIR = os.path.join(ROOT_DIR, ".agents") PYPROJECT_PATH = os.path.join(ROOT_DIR, "pyproject.toml") def get_root_version(): """Returns the IEPE protocol version from git tags or pyproject.toml.""" # 1. Try git describe --tags try: tag = subprocess.check_output( ["git", "describe", "--tags", "--abbrev=0"], cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True ).strip() if tag: return tag.lstrip("v") except Exception: pass # 2. Check pyproject.toml if os.path.exists(PYPROJECT_PATH): try: with open(PYPROJECT_PATH, "r", encoding="utf-8") as f: content = f.read() match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', content) if match: return match.group(1).lstrip("v") except Exception: pass return "0.2.0" def get_repo_identity(): """Collects git commit SHA, tag, and dirty state for IEPE Core.""" info = {} try: sha = subprocess.check_output( ["git", "rev-parse", "--short", "HEAD"], cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True ).strip() info["sha"] = sha status = subprocess.check_output( ["git", "status", "--porcelain"], cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True ).strip() if status: info["sha"] += " (dirty)" except Exception: info["sha"] = "unknown" try: tag = subprocess.check_output( ["git", "describe", "--tags", "--always"], cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True ).strip() info["tag"] = tag except Exception: info["tag"] = "untagged" return f"IEPE Core Protocol: v{VERSION} ({info['sha']})" VERSION = get_root_version() ABBR = "iepe" DATE = datetime.now().strftime("%Y-%m-%d") EXCLUDED_DIRS = { "_scripts", "scratch", "node_modules", "target", "worktrees", ".worktrees", ".git", ".github", ".vscode", ".pytest_cache", ".cache", "dist", "build", "coverage", "tmp", "temp", "out", "__pycache__", "iepe_core.egg-info", ".egg-info", } EXCLUDED_FILE_SUBSTRINGS = { "-lock.json", ".lock", "pnpm-lock.yaml", "yarn.lock", ".DS_Store", ".map", ".min.js", ".min.css", } ALLOWED_EXTS = { ".py", ".json", ".md", ".toml", ".txt", ".sh", ".yaml", ".yml", ".sql" } def is_excluded_dir(dir_name): lower = dir_name.lower() if dir_name in EXCLUDED_DIRS or lower in EXCLUDED_DIRS or dir_name.endswith(".egg-info"): return True if dir_name.startswith(".") and dir_name != ".agents": return True if dir_name.startswith("__") or "__" in dir_name: return True if "worktree" in lower: return True return False def read_file(file_path, rel_path): """Reads UTF-8 source byte-faithfully, rejects binary input, and raises on I/O errors.""" try: with open(file_path, "rb") as f: raw_bytes = f.read() except OSError as e: raise RuntimeError(f"Failed to read file {rel_path}: {e}") if b"\x00" in raw_bytes: print(f"[gen-llms] skipping binary file containing NUL bytes: {rel_path}") return None, raw_bytes try: return raw_bytes.decode("utf-8"), raw_bytes except UnicodeDecodeError: print(f"[gen-llms] skipping non-utf8 encoded file: {rel_path}") return None, raw_bytes def is_excluded_file(file_name): lower = file_name.lower() if ( file_name.endswith(".lock") or file_name.endswith("-lock.json") or file_name.endswith("-lock.yaml") or file_name.endswith("-lock.yml") or lower in {"cargo.lock", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb"} ): return True if file_name.startswith("._") or file_name.endswith(".pyc"): return True for sub in EXCLUDED_FILE_SUBSTRINGS: if sub in file_name: return True return False def read_agents_dir_files(): """Reads doctrine files from .agents/ surface (AGENTS.md and skills/*/SKILL.md).""" entries = [] agents_md_path = os.path.join(AGENTS_DIR, "AGENTS.md") if os.path.exists(agents_md_path): rel_path = ".agents/AGENTS.md" content, _ = read_file(agents_md_path, rel_path) if content is not None: entries.append((rel_path, content)) skills_dir = os.path.join(AGENTS_DIR, "skills") if os.path.exists(skills_dir): for root, dirs, files in os.walk(skills_dir): dirs[:] = [d for d in dirs if not is_excluded_dir(d)] for f in sorted(files): if f != "SKILL.md" or is_excluded_file(f): continue full_path = os.path.join(root, f) rel_path = os.path.relpath(full_path, ROOT_DIR) content, _ = read_file(full_path, rel_path) if content is not None: entries.append((rel_path, content)) return entries def read_source_files(): entries = read_agents_dir_files() agents_rel_paths = {rel for rel, _ in entries} for root, dirs, files in os.walk(ROOT_DIR): if root == ROOT_DIR: dirs[:] = [d for d in dirs if d != ".agents" and not is_excluded_dir(d)] else: dirs[:] = [d for d in dirs if not is_excluded_dir(d)] for f in files: ext = os.path.splitext(f)[1] if (ext in ALLOWED_EXTS or f in {"pyproject.toml", "LICENSE"}) and not is_excluded_file(f): full_path = os.path.join(root, f) rel_path = os.path.relpath(full_path, ROOT_DIR) if rel_path in agents_rel_paths: continue content, _ = read_file(full_path, rel_path) if content is not None: entries.append((rel_path, content)) sorted_entries = sorted(entries, key=lambda x: x[0]) return sorted_entries def categorize_files(source_files): categories = { "Protocol Architecture, Doctrine & Governance": [], "Canonical Contract Schemas & Protocol Definitions": [], "Core Reference Implementation (iepe_core)": [], "Core Tools & Utilities": [], "Examples & Protocol Fixtures": [], "TestSuite & Verification Gates": [], "Operational Work Graph & Issues": [], "Verification & Execution Evidence": [], "Other Protocol Modules": [] } for rel, src in source_files: line_count = len(src.splitlines()) size_kib = round(len(src.encode('utf-8')) / 1024, 1) item = (rel, line_count, size_kib) if rel in {"AGENTS.md", "README.md", "ROADMAP.md", "LICENSE", "The-Project-Is-the-Benchmark.md", "pyproject.toml"} \ or rel == ".agents/AGENTS.md" \ or rel.startswith(".agents/skills/") \ or rel.startswith("docs/"): categories["Protocol Architecture, Doctrine & Governance"].append(item) elif rel.startswith("schemas/"): categories["Canonical Contract Schemas & Protocol Definitions"].append(item) elif rel.startswith("iepe_core/"): categories["Core Reference Implementation (iepe_core)"].append(item) elif rel.startswith("tools/"): categories["Core Tools & Utilities"].append(item) elif rel.startswith("examples/") or rel.startswith("fixtures/"): categories["Examples & Protocol Fixtures"].append(item) elif rel.startswith("tests/"): categories["TestSuite & Verification Gates"].append(item) elif rel.startswith("work/"): categories["Operational Work Graph & Issues"].append(item) elif rel.startswith("evidence/"): categories["Verification & Execution Evidence"].append(item) else: categories["Other Protocol Modules"].append(item) return categories def make_agent_rel_link(rel_path): if rel_path.startswith(".agents/"): return os.path.relpath(rel_path, ".agents") return "../" + rel_path def main(): os.makedirs(AGENTS_DIR, exist_ok=True) # Clean up stale/previous llms artifacts in .agents/ for pattern in ["llms*.txt"]: for p in glob.glob(os.path.join(AGENTS_DIR, pattern)): try: os.remove(p) except Exception: pass ident_summary = get_repo_identity() source_files = read_source_files() categorized = categorize_files(source_files) total_lines = sum(len(src.splitlines()) for _, src in source_files) manifest_lines = [ "# IEPE Protocol Master Index", f"> Protocol Root Version: v{VERSION} | Generated: {DATE} | Total Modules: {len(source_files)} files | Total Lines: {total_lines:,} lines", f"> Protocol Identity: {ident_summary}", "", "## Core Protocol Doctrine & Governance", f"- [AGENTS.md]({make_agent_rel_link('AGENTS.md')}): IEPE Master AI Agent Operating Contract", f"- [README.md]({make_agent_rel_link('README.md')}): IEPE Architecture Overview", f"- [ROADMAP.md]({make_agent_rel_link('ROADMAP.md')}): IEPE Development Roadmap", f"- [The-Project-Is-the-Benchmark.md]({make_agent_rel_link('The-Project-Is-the-Benchmark.md')}): Operational Doctrine", f"- [docs/PROTOCOL.md]({make_agent_rel_link('docs/PROTOCOL.md')}): IEPE Formal Specification", f"- [docs/INITIALIZATION.md]({make_agent_rel_link('docs/INITIALIZATION.md')}): Project Initialization Standard", f"- [docs/ADOPTION.md]({make_agent_rel_link('docs/ADOPTION.md')}): Adoption & Reconciliation Guide", "", ] for cat, items in categorized.items(): if items: manifest_lines.append(f"## {cat} ({len(items)} files)") for rel, lcnt, size in items: link = make_agent_rel_link(rel) manifest_lines.append(f"- [{rel}]({link}) ({lcnt} lines, {size} KiB)") manifest_lines.append("") manifest_content = "\n".join(manifest_lines) + "\n" sep = "=" * 72 def banner(title, info=""): extra = f" [{info}]" if info else "" return f"\n{sep}\n## {title}{extra}\n{sep}\n\n" full_parts = [ f"# INTENT AND EVIDENCE PROJECT ENGINE (IEPE): CONSOLIDATED MASTER RESEARCH & CODEBASE CORPUS\n", f"Protocol Root Version: v{VERSION} ({DATE}) | Modules: {len(source_files)} | Total Lines: {total_lines:,}\n", f"Protocol Identity: {ident_summary}\n\n", f"TABLE OF CONTENTS & SUBSYSTEM SUMMARY:\n" ] for cat, items in categorized.items(): if items: full_parts.append(f" - {cat}: {len(items)} files\n") full_parts.append(f"\n{sep}\n\n") for cat, items in categorized.items(): if items: full_parts.append(banner(f"SUBSYSTEM: {cat.upper()} ({len(items)} files)")) for rel, lcnt, size_kib in items: src = next(s for r, s in source_files if r == rel) full_parts.append(f"--- FILE: {rel} ({lcnt} lines, {size_kib} KiB) ---\n{src}\n\n") full_content = "".join(full_parts) corpus_sha256 = hashlib.sha256(full_content.encode("utf-8")).hexdigest() digest_header = f"> Corpus Payload SHA-256 (excluding this field): {corpus_sha256}\n" manifest_content = manifest_content.replace(f"> Protocol Identity: {ident_summary}\n", f"> Protocol Identity: {ident_summary}\n{digest_header}") full_content = full_content.replace( f"Protocol Identity: {ident_summary}\n\n", f"Protocol Identity: {ident_summary}\nCorpus Payload SHA-256 (excluding this field): {corpus_sha256}\n\n", ) with open(os.path.join(AGENTS_DIR, "llms.txt"), "w", encoding="utf-8") as f: f.write(manifest_content) with open(os.path.join(AGENTS_DIR, f"llms-{ABBR}-v{VERSION}.txt"), "w", encoding="utf-8") as f: f.write(manifest_content) with open(os.path.join(AGENTS_DIR, "llms-full.txt"), "w", encoding="utf-8") as f: f.write(full_content) with open(os.path.join(AGENTS_DIR, f"llms-full-{ABBR}-v{VERSION}.txt"), "w", encoding="utf-8") as f: f.write(full_content) full_kib = round(len(full_content.encode("utf-8")) / 1024) print( f"gen-llms: generated .agents/llms.txt, .agents/llms-{ABBR}-v{VERSION}.txt ({len(manifest_content)} bytes) and .agents/llms-full.txt, .agents/llms-full-{ABBR}-v{VERSION}.txt ({full_kib} KiB, {len(source_files)} source files included) [SHA256: {corpus_sha256[:16]}]" ) if __name__ == "__main__": main()