# New Modular Builder — Binding System Goal Status: binding architecture and continuous implementation goal Legacy system: Nyx New system name: pending operator selection Placeholder token: `ProjectName` — replace only after the operator selects the name Repository: `/Users/ethanashihundu/projects/agent-orchestrator-nyx-core` Control-plane target: 3,000–6,000 executable lines before provider adapters Initial recipe limit: 6 Initial active implementation-worker limit per project: 3 Initial design-candidate limit: 3, and only for a new or rejected visual foundation ## Paste this into Codex ```text /goal Work continuously in /Users/ethanashihundu/projects/agent-orchestrator-nyx-core. Read and execute docs/goals/MODULAR_SYSTEM_BUILD_GOAL.md as the binding specification. ProjectName replaces the Nyx orchestration kernel while preserving its proven durability primitives; ProjectName is a placeholder until the operator selects a name from this document. Build the smallest graph-native, provider-neutral application-building system that satisfies every acceptance gate. Keep a direct lane for small work and use a dependency graph only when work is genuinely decomposable. Route product interpretation, architecture, planning, task decomposition, plan revision, and independent semantic review to gpt-5.6-sol/high. Route all write-enabled product implementation to gpt-5.6-luna/xhigh. Sol must decompose every implementation request until each Luna packet passes the Luna Fit Gate. One deterministic ProjectController owns state; Sol and Luna may propose or produce work but never own state, retries, locks, acceptance, or integration. Implement one accepted vertical slice before adding another recipe. Do not add microservices, a graph database, an arbitrary workflow DSL, another scheduler, nested supervisors, unbounded retries, or evidence with no named consumer. Preserve the Wobbleby-derived product-design standard while giving every product its own palette and content. Maintain the progress ledger, publish tested milestones to the architecture/control-plane site, and continue until the terminal acceptance conditions are met or a precise external blocker is reached. ``` ## 1. Objective Build ProjectName into a dependable application-building system that can handle both a contained fix and a multi-day product build without forcing both through the same ceremony. ProjectName must behave like a disciplined software-engineering organization: - a lead turns product intent into a bounded, dependency-aware plan; - implementation workers own isolated work items; - verification workers judge integrated behavior independently; - an integrator promotes accepted changes through one queue; - the deterministic controller owns state, resources, recovery, and truth. The system succeeds only when the integrated product satisfies its behavioral, visual, and release contract. Worker activity, exited processes, artifact counts, screenshots, and schema-valid receipts are not product success. ## 2. Naming decision The new system is a real break from Nyx, but its name remains an operator decision. Do not bake a candidate into package names, public URLs, state schemas, or permanent documentation until the operator selects it. ### Shortlist | Candidate | Pronunciation | Product idea | Current concern | |---|---|---|---| | **Keystone** | `KEY-stone` | One dependable authority keeps many modules coherent. | Strong and clear, but a common infrastructure word. | | **Morrow** | `MOR-oh` | A system that continuously builds what comes next. | Distinct tone; an unrelated AI/automation company exists. | | **Concord** | `CON-cord` | Plans, workers, resources, and product contracts operate in agreement. | Polished and relevant; already used by enterprise/privacy software. | | **Meridian** | `muh-RID-ee-un` | A stable reference line that keeps complex work aligned. | Premium feel, but broadly used in technology. | | **Axiom** | `AK-see-um` | Explicit rules and contracts govern intelligent execution. | Excellent rule-system fit, but a crowded software name. | | **Atlas** | `AT-lus` | A capable system carrying large product builds. | Mythic and pronounceable, but extremely crowded. | | **Soluna** | `so-LOO-nuh` | Directly represents Sol planning and Luna building. | Memorable model story, but ties the product name to current model roles and has existing non-agent brands. | | **Solune** | `SO-loon` | Blends Sol with the French-rooted *lune* for a compact sun–moon pairing. | Strong role story, but an existing ERP product uses the name. | | **Solána** | `so-LAH-nuh` | A smooth, human sun-rooted name in the tonal family the operator referenced through SZA. | The accent does not create practical separation from the globally established Solana blockchain and is awkward in package names and URLs. Treat as a sound direction unless clearance proves otherwise. | Names removed from the shortlist: - `Orrery`: operator rejected it as hard to pronounce. - `Rivet`, `Gantry`, `Ariadne`, `Lattice`, `Mosaic`, `Relay`, `Orbit`, `Forge`, `Tandem`, `Trellis`, `Braid`, and `Kestrel`: current products directly overlap AI agents, coding-agent workspaces, orchestration, or workflow control. The companion site must show the shortlist as an interactive naming board. A browser-local preview selection may update the visible mock brand, but it is not a binding product-name decision. After operator selection, perform a focused domain, package, repository, and trademark review before public release. Use `Nyx` only for legacy history, migrations, and extracted mechanisms. Use `ProjectName` as a temporary document token until selection. ## 3. Core decision ProjectName is a **graph-native modular monolith** initially. These terms answer different questions: - **Graph-native**: work is represented as dependency nodes, artifact versions, and resource claims. - **Modular**: design, implementation, verification, integration, release, and providers have typed boundaries and can be tested independently. - **Monolith**: one narrow control-plane process and one transactional store own authoritative state until measured scale requires separation. Do not begin with distributed services. The control plane must be boring, local, inspectable, and recoverable before any component is moved across a network boundary. ### 3.1 Unattended autonomy contract One accepted project request must run without intermediate human input. The operator supplies the goal and any standing authority once; ProjectName researches, plans, selects, implements, verifies, integrates, and produces the best complete result it can without pausing for taste, decomposition, architecture, or routine deployment decisions. Every project starts with a versioned `AutonomyPolicy` declaring: - allowed repository, process, network, browser, device, deployment, and credential-handle actions; - time, cost, provider, and concurrency budgets; - preview and production deployment targets when available; - destructive or irreversible action limits; - the safe fallback for an action outside policy. Binding behavior: 1. Sol researches ordinary ambiguity and records a reasonable, reversible assumption. It does not ask the operator to choose among ordinary product, architecture, library, copy, or visual options. 2. One design direction is the default. When multiple coded directions are justified, a fresh Sol context scores them against the product and visual contracts, names evidence, selects one, and the controller pins it. No operator checkpoint exists in the build workflow. 3. Luna never waits for subjective input. Missing implementation detail returns to Sol; Sol resolves it or chooses the safest contract-compatible default. 4. Preauthorized build, test, preview, and deployment actions proceed automatically. 5. If an external action lacks authority or credentials, finish every unaffected branch and substitute the safest useful result: local artifact, mock adapter, unsigned package, or preview deployment. Record the omitted action in the terminal report instead of idling. 6. Operator feedback after delivery creates a new revision goal. It is not evidence that the original system should have paused. 7. Unattended does not mean unsafe. The system never invents credentials, purchases, legal acceptance, production authority, or irreversible destructive permission. The normal terminal states are `complete`, `complete_with_bounded_exceptions`, `blocked_external`, and `failed_contract`. `needs_operator_review` is not a runtime state. ## 4. The two execution lanes ### 4.1 Direct lane Use for small or tightly coupled work: ```text contract -> implement -> affected verification -> integrate ``` Examples: - one bug fix; - a contained UI correction; - one API endpoint; - copy, style, or configuration repair; - work where one owner benefits from retaining the full context. The direct lane uses the same work-item, attempt, result, acceptance, and integration contracts as graph execution. It omits unnecessary graph ceremony. ### 4.2 Graph lane Use for long-running or genuinely decomposable work: ```text goal -> lead plan -> dependency DAG -> compatible parallel work -> independent acceptance -> ordered integration -> product proof ``` Examples: - a complete application; - a large cross-platform feature; - backend, frontend, and verification work that can overlap; - work using scarce build or device resources; - multi-day work that must survive provider and process failure. The recipe selector may recommend the graph lane only when at least one material dependency, parallel ownership boundary, scarce resource, or recovery need exists. ## 5. Authority and roles ### 5.1 ProjectController The ProjectController is deterministic code and the only writer of authoritative project execution state. It owns: - project status; - work-item status; - graph edges; - artifact and contract versions; - leases and resource grants; - attempt budgets; - acceptance recording; - integration ordering; - event append and read-model projection. It does not invent product direction, write application code, or aesthetically judge a product. ### 5.2 Lead agent The lead agent runs on `gpt-5.6-sol` with `high` reasoning. Sol plans every product change, including direct-lane work, but does not receive a model call for deterministic scheduling events. Sol may: - clarify and preserve the product contract; - propose a recipe; - create or revise a bounded dependency graph; - define work-item ownership and acceptance criteria; - classify semantic blockers; - propose a versioned plan revision. The lead cannot: - directly mutate authoritative state; - launch unregistered workers; - award acceptance; - bypass resource claims; - create new lifecycle states; - restart a complete plan because one node failed. ### 5.3 Workers All write-enabled implementation workers run on `gpt-5.6-luna` with `xhigh` reasoning. Luna receives one bounded implementation packet and returns one result envelope. Luna owns neither planning, scheduling, retries, acceptance, nor completion. ### 5.4 Verifiers Deterministic tests run first. Independent semantic, code, and visual review runs on a fresh `gpt-5.6-sol/high` context against an immutable commit or artifact set when the work's risk tier requires it and at every integrated milestone. A verifier may approve, reject, or return a precise blocker within its assigned acceptance domain. It may not repair the work it is judging in the same attempt. Do not pay for the same review twice. Low-risk, reversible leaf work may receive deterministic node acceptance and then be judged in the combined milestone review. Foundations, schemas, permissions, security boundaries, destructive migrations, user-critical behavior, and releases require independent review before promotion. ### 5.5 Integrator The integrator owns one authoritative queue, rechecks versions, promotes compatible results in topological order, runs affected integrated tests, and records the exact promoted commit. It may form one transactional integration batch from disjoint results sharing the same accepted epoch, but it never runs two promotions concurrently. ### 5.6 ResourceBroker The ResourceBroker grants logical write leases and physical resource leases. It owns no product state and never decides acceptance. ### 5.7 Binding model routes | Responsibility | Route | Write product code? | |---|---|---:| | Product interpretation and contract | `gpt-5.6-sol/high` | no | | Architecture and interface planning | `gpt-5.6-sol/high` | no | | Graph creation and task decomposition | `gpt-5.6-sol/high` | no | | Plan revision and blocker diagnosis | `gpt-5.6-sol/high` | no | | Independent semantic/code/visual review at risk boundaries and milestones | fresh `gpt-5.6-sol/high` | no | | Product implementation and bounded repair | `gpt-5.6-luna/xhigh` | yes, within packet | | State, scheduling, resource grants, retries, and integration | deterministic controller | only deterministic Git operations | There are no silent fallbacks. The route recorded on the attempt must match the role. The current Core code and older routing documents disagree about Luna-only versus Sol/Terra routing; ProjectName replaces both with one code-owned manifest from which runtime validation, documentation, and the UI are generated. ### 5.8 Luna Fit Gate Sol must keep decomposing until every Luna implementation packet passes all hard rules: 1. **One observable outcome.** One sentence describes the product or system behavior that becomes true. 2. **One primary write domain.** A task may read many pinned resources but ordinarily writes only one of `feature:*`, `design-system`, `app-shell`, `navigation`, `api-contract:*`, `data-schema:*`, or an equivalent domain. 3. **Accepted dependencies.** Every required interface, design foundation, schema, or upstream artifact is accepted and version-pinned. 4. **No unresolved product decision.** Luna is not asked to invent architecture, API shape, data schema, navigation grammar, visual foundation, or acceptance policy. 5. **Independent acceptance.** The result can be verified and accepted without waiting for another unfinished sibling to make it meaningful. 6. **Bounded attempt.** The expected implementation fits one uninterrupted attempt, normally 20–60 minutes. If Sol cannot confidently bound it below 60 minutes, split it. 7. **Bounded source surface.** One component, screen/state slice, endpoint, migration, or similarly cohesive area. One to six files and roughly 50–400 changed lines are planning heuristics, not success metrics; mechanical changes may exceed them when deterministic checks prove the transformation. 8. **Two to six concrete checks.** Acceptance criteria name observable behavior, exact tests, or rendered states—not “polished,” “complete,” or “works well.” 9. **Explicit exclusions.** The packet states what Luna must not change, refactor, redesign, or “clean up.” 10. **One integration destination.** The expected output commit and consumer are known before launch. Luna tasks must not be made artificially tiny. A packet must produce a meaningful vertical behavior or independently usable contract. Do not split a single component among simultaneous workers, create one task per CSS property, or require several incomplete microtasks before anything can be tested. ### 5.9 Mandatory Luna implementation packet Sol writes every packet in this form: ```yaml identity: projectId: workItemId: title: "one imperative verb + one concrete object" recipe: mode: cooperative | competitive outcome: oneSentence: userOrSystemValue: currentState: exactBehavior: relevantFiles: [] knownEvidence: [] pinnedInputs: baseCommit: contractVersion: foundationVersion: dependencyArtifacts: [] ownership: allowedPaths: [] writeDomains: [] readResources: [] exclusiveResources: [] implementation: requiredBehavior: [] requiredSequence: [] constraints: [] nonGoals: [] forbiddenChanges: [] acceptance: checks: [] commands: [] requiredEvidence: [] stopAndReturn: - contract_gap - needs_split - dependency_stale - resource_conflict - verification_failed ``` “Extremely descriptive” means structured and unambiguous, not enormous. The packet should normally stay between 800 and 2,000 instruction words, cite exact paths and versioned documents, and include only context relevant to the bounded outcome. Do not paste the entire repository, every audit, or an uncurated design archive into Luna's prompt. ### 5.10 Automatic split rules Sol must split or revise a task before dispatch when any condition is true: - its title contains independent outcomes joined by `and`; - it writes more than one consistency domain; - it combines foundation creation with feature implementation; - it combines implementation with its independent acceptance review; - it crosses unrelated directories or platforms; - it requires multiple unaccepted dependencies; - it contains an unresolved interface or visual decision; - its acceptance criteria cannot identify a single owner and result; - its estimated attempt exceeds 60 minutes or cannot be bounded; - a prior Luna attempt returns `needs_split` or `contract_gap` with evidence. Sol revises only the affected packet and downstream edges. It does not recreate the entire project plan. ### 5.11 Product-regularity rules for parallel Luna work - Pin a design foundation before parallel screen work. - Treat `design-system`, `app-shell`, `navigation`, API contracts, and schemas as the consistency spine. - Allow only one Luna writer on a consistency-spine domain at a time. - Allow parallel Luna implementation only for disjoint feature domains against pinned shared versions. - Integrate through one queue and rerun affected tests on the combined branch. - Run a fresh Sol review over the combined product at every milestone; do not require a redundant fresh review for every low-risk leaf. - A cross-cutting change becomes its own accepted foundation task before dependent implementation continues. ## 6. Minimal kernel The initial control plane contains only: 1. `ProjectController` 2. `ProjectStore` 3. `WorkGraph` 4. `EventLog` 5. `ResourceBroker` 6. `IntegrationQueue` 7. `ResultAcceptor` 8. provider adapters Recommended source shape: ```text apps/project-name/ src/ kernel/ project-controller.ts project-store.ts work-graph.ts event-log.ts resource-broker.ts integration-queue.ts contracts/ project.ts work-item.ts module.ts result-envelope.ts resources.ts modules/ scope/ research/ design/ implement/ verify/ release/ recipes/ direct-fix.ts backend-feature.ts ui-change.ts ui-foundation.ts long-build.ts release.ts adapters/ workers/ git/ platform/ ``` Directory shape is guidance. Acceptance depends on mechanism count and behavior, not matching these names. ## 7. State model ### Project ```text active | blocked_external | complete | canceled ``` ### Work item ```text queued | ready | running | validating | revising | accepted | blocked_external | canceled ``` ### Attempt ```text created | running | exited | collected | accepted | rejected ``` Rules: - `exited` means transport completion only. - Only acceptance may produce `accepted`. - No public or durable `succeeded -> stale` sequence exists. - No `awaiting_user` state exists. Ordinary uncertainty produces an autonomous research, default, split, repair, or replan action. - `blocked_external` is legal only under the terminal condition defined in section 21. - A local node failure does not reopen a project or completed siblings. - A project is complete only when every required terminal node is accepted and the product-level acceptance contract passes. - Stage names are read-model groupings, never mandatory durable entities. ## 8. Work-item and result contracts Every work item contains: ```yaml id: projectId: recipe: module: mode: cooperative | competitive | read_only scope: dependencies: [] baseCommit: contractVersion: foundationVersion: allowedPaths: [] reads: [] writes: [] exclusiveResources: [] acceptance: [] budget: attempts: 1 wallClockMinutes: modelCalls: ``` Every provider returns: ```yaml workItemId: attemptId: provider: baseCommit: outputCommit: contractVersion: foundationVersion: changedResources: [] evidence: [] tests: [] blockers: [] summary: ``` The controller rejects an envelope whose identity, base, contract, foundation, ownership, or output lineage cannot be proven. ## 9. Graph rules ### 9.1 Graph form - The active work graph is a directed acyclic graph. - Every node has at least one named consumer or is a terminal acceptance node. - Edges represent required data or acceptance dependencies, not vague ordering preference. - Plan revisions are versioned events with a reason and affected-node set. - Accepted nodes are immutable. A new requirement creates new work rather than rewriting history. - Complete graph epochs are compacted into a milestone summary while their events remain auditable. ### 9.2 Three parallelism modes **Cooperative** work produces disjoint results intended to merge. **Competitive** work produces isolated alternatives. Only one candidate may be promoted. Competitive nodes do not reserve the shared feature write lease until selection. **Read-only** work inspects immutable input and never edits product source. The controller must never infer one mode from prompt prose. Mode is explicit in the work-item contract. ### 9.3 Dependency invalidation - A changed artifact invalidates only nodes that consumed the changed version. - Non-breaking additions may preserve existing dependents after contract verification. - Breaking changes create a new artifact version and a bounded rebase/reverification set. - No foundation change automatically restarts the whole project. ### 9.4 Rolling planning horizon Massive goals are durable products, not giant prompts. ProjectName maintains four different horizons: | Horizon | What remains visible | Detail level | |---|---|---| | Outcome | The complete product, users, non-goals, success proof, and release boundary | Durable for the life of the project | | Architecture | Subsystems, dependency direction, security boundaries, and versioned interfaces | Concrete enough to prevent incompatible local decisions | | Integration | The next one or two accepted milestones and their critical dependencies | Fully graphed and acceptance-ready | | Execution | One Luna implementation packet | Exact paths, claims, steps, checks, evidence, and stop codes | Sol may maintain a coarse later-milestone map, but it must not fully decompose months of uncertain work. Normally only 6–24 nodes are implementation-ready or near-ready at once. Accepted evidence rolls the integration horizon forward; a changed decision revises only affected future nodes. Every milestone checkpoint stores accepted commits, interface and foundation versions, outstanding blockers, performance measurements, a compact decision record, and the smallest next horizon. Agents are replaceable. Restarting a process or model context must not erase the product's memory or require replaying the full conversation. #### Long-build stress test: a web browser This is an example **product ProjectName may be asked to build**, not a browser tool ProjectName needs in order to operate. It proves autonomous decomposition and continuation over a huge software horizon. “Build a browser” must first resolve which product is meant: - a browser application using a pinned WebKit or Chromium engine is a large but tractable application build; - a new browser engine includes networking, parsing, JavaScript execution, layout, painting, sandboxing, storage, media, accessibility, standards compatibility, and years of security hardening. It is a portfolio of programs, not one task. An initial browser-application horizon may be: 1. executable shell, URL loading, back/forward/reload, and crash-visible errors; 2. tabs, window lifecycle, session persistence, and restart recovery; 3. history, bookmarks, downloads, permissions, and settings; 4. privacy controls, sandbox boundaries, update/rollback, accessibility, and security testing; 5. optional deeper engine ownership, split into independently accepted subsystem programs only after the product shell proves the interfaces. Each milestone must run as a real product. Luna never receives “build a browser”; it receives one independently acceptable slice such as “restore the pinned tab set after a forced process restart.” ## 10. Resource and concurrency rules ### 10.1 Resource classes Logical consistency domains: - `design-system` - `app-shell` - `navigation` - `api-contract:` - `data-schema:` - `authentication` - `feature:` - `release-branch` Physical resources: - simulator or device; - the single initial `browser-session:primary` automation session; - build slot; - GPU; - port; - deployment environment; - provider concurrency slot. ### 10.2 Compatibility matrix | Claim A | Claim B | Same version/domain | Allowed | |---|---|---:|---:| | read | read | yes | yes | | read immutable vN | writer producing vN+1 | yes | yes, recheck at integration | | write | write | yes | no | | write | write | different domains | yes | | exclusive physical | any second claimant | same resource | no | | competitive candidate | competitive candidate | same target | yes, isolated | | integration promotion | integration promotion | same project | no | ### 10.3 Lease rules - One cooperative writer per consistency domain. - The central broker grants all leases in a deterministic global order; workers never compose locks themselves. - Logical leases expire and are recoverable. - Long model execution happens in an isolated worktree. Broad repository locks are not held for the entire generation period. - Integration performs optimistic base, contract, foundation, and ownership checks. - Scarce physical resources are held only while actually used. - Lease expiry never implies task failure; the controller first proves whether a live attempt still owns the process. - Fairness aging prevents one long project from starving short work. The worker-facing browser tool is a separate concern from a browser product. Expose one provider-neutral `BrowserHarness` contract and begin with one Playwright-backed session held through the ResourceBroker. Do not simultaneously maintain Playwright, Puppeteer, WebDriver, and BrowserUse paths. Add or replace an adapter only when a canary proves that the current contract cannot express a required interaction. The harness may navigate, inspect, capture, and exercise a running product; it never owns project truth or grants acceptance. ### 10.4 Throughput and critical-path rules Fast means minimum wall time to an accepted integrated product, not maximum simultaneous agents. - The controller prioritizes ready work by downstream unlock value, critical-path position, scarce-resource wait, and age. It does not use model judgment for ordinary queue ordering. - Sol resolves high-fan-out interfaces and product decisions early because one accepted foundation can unblock many Luna packets. - Dependency installation, repository checkout, code indexing, and deterministic build-cache warming may happen before a node is ready, but prewarming grants no product write lease. - Maintain content-addressed dependency, compiler, test, and rendered-asset caches keyed by exact inputs. Cache hits are evidence; stale or unverifiable cache entries are discarded. - Generate a lightweight symbol/import/test-impact map from source. Luna receives the relevant module entry point and nearby contract tests rather than a repository dump. - Run focused affected tests for a leaf result. Run combined affected tests for an integration batch. Run full system, security, platform, and release matrices only at named risk boundaries. - One integration queue may batch disjoint results from the same accepted epoch, apply them in topological order, and run the union of affected checks once. A failed batch is bisected or reverted deterministically. - Keep three active implementation workers initially. Raise the cap only when measurements show at least four ready disjoint write domains, available physical/provider resources, low integration wait, and no rework increase. Lower it when queueing, conflicts, or review debt rises. - Prepare the next Luna packet while the current critical-path packet runs, but do not dispatch against an unaccepted dependency. - Preserve worker environments between compatible packets only when source, credentials, processes, ports, and leases are proven clean; otherwise start from the pinned image. Track per node and milestone: planning latency, queue wait, model time, build time, verification time, integration wait, cache hit rate, critical-path duration, downstream nodes unlocked, rework, and accepted product value. Optimize the measured bottleneck. Do not add concurrency to compensate for slow tests, unresolved decisions, or a congested integration queue. ## 11. Initial recipes No seventh recipe may be added until at least three real tasks demonstrate that none of the existing recipes can express the required behavior without conditional distortion. ### `direct_fix` ```text reproduce/contract -> implement -> regression/affected tests -> integrate ``` ### `backend_feature` ```text interface contract -> implementation -> unit/integration verification -> integrate ``` ### `ui_change` ```text foundation check -> implementation -> behavior + visual verification -> integrate ``` ### `ui_foundation` ```text bounded research when needed -> 1–3 real-code directions -> autonomous independent selection -> pin foundation -> implementation -> behavior + visual verification -> integrate ``` One direction is the default. Two or three require a new product, a rejected foundation, or an explicitly unresolved visual thesis. A fresh Sol context selects the winner from running code against the binding product and visual contracts; the controller records the decision without an operator checkpoint. ### `long_build` ```text product contract -> coarse milestone map -> next 1–2 milestone horizon -> dependency-safe work waves -> continuous integration batches -> checkpoint + roll horizon -> affected/system verification -> final product proof ``` ### `release` ```text frozen commit -> platform/security/integration verification -> package/deploy -> rollback proof -> standing-policy release decision ``` Release is never an implicit tail attached to ordinary implementation. ## 12. Module admission rules A capability becomes a module only when at least one statement is true: 1. It needs an independent contract test. 2. Its failure must be isolated from the surrounding workflow. 3. It is reused by at least two recipes. 4. Its implementation or provider must be replaceable. 5. It has materially different resource or permission requirements. 6. It can run concurrently without weakening integrated consistency. Every module must declare: - typed input and output; - state owner; - side effects; - time, attempt, and model-call budget; - acceptance owner; - artifact consumers; - contract fixtures; - observed value: defects caught, rework prevented, or time saved. If a module adds recurring time and catches or prevents no measured failure over three representative uses, merge it into its nearest useful parent or remove it. ### 12.1 Source shape and AI navigability The codebase is optimized for a capable engineer or coding model to locate the correct responsibility, load a bounded amount of context, make one cohesive change, and prove it without reading a giant script. For handwritten implementation files: - target **200–400 logical lines per file on average within a module**; - treat **500 logical lines as a review trigger**, not an automatic rejection gate; - exclude generated code, vendored code, machine-authored migrations, and data fixtures from the target, while keeping their generators or schemas small; - permit a larger file when it represents one genuinely indivisible protocol, table, generated artifact, or cohesive state machine and the exception is documented beside the module contract; - track both module average and the over-500 tail so many tiny files cannot hide one navigation-hostile core file. Split a file when it has multiple independent reasons to change, crosses state or permission ownership, combines orchestration with provider details, or forces unrelated tests to load the same implementation surface. Keep code together when splitting would create forwarding wrappers, circular imports, one-function-file sprawl, or abstractions with no independent contract. Every runtime module must provide: 1. one obvious entry point; 2. a short responsibility and dependency-direction note; 3. colocated or directly discoverable contract tests; 4. explicit public exports rather than deep-import archaeology; 5. stable vocabulary matching graph nodes, resource claims, result envelopes, and operator UI; 6. a source-shape report showing logical-line distribution, files above 500 lines, dependency cycles, and documented exceptions. The source-shape report is advisory during ordinary iteration and binding at milestone acceptance: every flagged file must be split or consciously accepted with a cohesion reason. A passing line-count metric never compensates for bad boundaries, and a 520-line cohesive implementation is preferable to six opaque 90-line fragments. Sol must use module entry points and source-shape reports when preparing a Luna packet. Luna receives exact allowed paths and must return `needs_split` if the owned surface cannot be understood or changed as one responsibility without widening scope. ## 13. Anti-overengineering constitution These limits are binding for the initial system: | Mechanism | Limit | |---|---:| | Authoritative state writers per project | 1 | | Control-plane process | 1 | | Transactional state store | 1 | | Polling recovery loop | 1 slow safety sweep, not primary execution | | Retry decision paths | 1 | | Automatic retries per work item | 1 when classified retryable | | Initial recipes | 6 | | Default design directions | 1 | | Maximum bounded design directions | 3 | | Integration queues per project | 1 | | Active implementation workers per project | 3 initially | | Kernel executable LOC before adapters | 3,000–6,000 | | Handwritten implementation file target | 200–400 logical LOC average per module; review above 500 | Prohibited until separately justified by measured evidence: - microservices; - graph databases; - arbitrary workflow DSLs; - nested supervisors or agent managers; - separate scheduler, dispatcher, and mega-reconciler timers; - module-owned durable lifecycle states; - self-modifying workflows; - per-module databases; - unbounded candidate factories; - screenshot counts as quality; - artifact generation without a named consumer; - duplicated verification ownership; - mandatory full-system suites after every leaf result; - mandatory fresh-agent review of every low-risk leaf before milestone review; - full-detail decomposition of an entire long-lived product before its first milestone; - additional coordinator agents whose only product is another handoff; - repeated whole-repository or conversation-history prompt dumps; - full release matrices during ordinary work; - flags for unfinished subsystems left permanently wired into production. Every proposed new mechanism must answer: 1. Which measured failure does this prevent? 2. Why can an existing mechanism not own it? 3. What can be deleted when this is added? 4. How is it tested independently? 5. What is its removal trigger? No satisfactory written answers means no addition. ## 14. Legacy Nyx disposition ### Preserve and extract - single authoritative state-commit semantics; - append-only events, compare-and-set, and idempotency; - isolated worktrees and change-set verification; - leases, attempt limits, and process-group cleanup; - exact result and commit lineage; - bounded workers; - provider/model routing concepts; - one integration queue; - affected tests; - final real-platform release verification; - concise product and design contracts. ### Remove from the new runtime - mandatory six-stage state machine; - empty general scheduler; - independent scheduler, dispatcher, and mega-reconciler loops; - broad task/stage/product reopen semantics; - transient mechanical `succeeded` status; - global one-active-product guard; - VP2 or detached renders as product authority; - screenshot count, uniqueness, text-presence, or self-attestation gates; - validation-only facades and fake success receipts; - early full-platform and release validation; - default large candidate tournaments; - runtime legacy migration; - dormant watchdog, supervisor, and scheduler families. ### Rewrite behind new contracts - state engine -> small project/work-item store; - dispatcher and reconciler -> event-driven ProjectController; - result ingestion -> provider-neutral envelope plus acceptance adapters; - Codex launcher -> generic process lifecycle plus provider adapters; - operational status -> derived read model; - visual validation -> real integrated product judgment. Do not refactor the approximately 19,000-line Core in place. Build ProjectName beside it, extract proven primitives with focused tests, shadow-run, then switch authority. ## 15. Product-design standard ProjectName must make this standard available to every UI-building recipe. The standard derives from the successful Wobbleby mobile canary's product confidence, not its brand colors, mascot, content, or exact screen layouts. ### 15.1 Product-specific authority - Every product owns its palette, emotional tone, content, illustration family, and domain rules. - ProjectName supplies craft constraints, not one global theme. - Never copy Wobbleby's cobalt, orange, penguin, language, or composition into another product by default. - Named references such as Cash App, Uber, Airbnb, and Duolingo communicate product confidence and craft level, not assets to reproduce. ### 15.2 Canvas and color - Default reading canvas is true white or a deliberate dark product field. - No beige, cream, brownish off-white, dusty pastel, or gray-white full-page canvas unless the product contract explicitly requires it. - One dominant hue per screen and at most two supporting accents. - Gray communicates hierarchy, not brand. - Product color must remain readable at WCAG AA contrast for normal text. - Gradients require a product or state purpose; never use them as generic polish. ### 15.3 Typography - Default UI family: Inter or a similarly neutral, proven sans-serif. - Inter Tight may be used for large editorial display text. - Monospace is reserved for data, hashes, time, versions, logs, or system status. - No decorative serif, script, or fashionable display font unless the product contract proves it belongs. - Paragraphs remain regular weight; hierarchy comes from size, spacing, and contrast. - Use at most three type sizes inside one card. - Large headings use tight but readable tracking; body copy never imitates a marketing poster. ### 15.4 Shape hierarchy Radius communicates component type rather than applying one factory value everywhere: | Component | Default range | |---|---:| | status marker | 8px | | chip or segmented item | 10–14px | | input or standard button | 16–20px | | content card | 22–26px | | media card or sheet | 28–34px | | avatar or circular action | 999px | - No jagged square card systems merely to appear different. - No repeated pill for every container. - Default cards use a 1px beautiful outline. - Shadows are reserved for surfaces that physically float above another surface. - Never stack multiple diffuse shadows to simulate quality. ### 15.5 Spacing and composition - Use a 4px base grid with purposeful steps: 4, 8, 12, 16, 20, 24, 32, 40, 48. - Mobile horizontal gutter defaults to 20px and may reduce to 16px on narrow screens. - Major sections breathe at 28–40px. - Cards generally use 16–24px internal padding. - Different screens may use different compositions while sharing the same tokens, controls, and navigation grammar. - Do not reduce every product screen to the same stack of rounded cards. - Information hierarchy must be obvious in the first viewport. ### 15.6 Controls - Minimum touch target: 44 × 44px. - Primary mobile action height: approximately 56px. - Only one visually primary action in a viewport. - Every enabled visible control has a real observable effect. - Fields use persistent labels; placeholder text never replaces the label. - Selected, pressed, loading, success, error, disabled, empty, and offline states are designed where applicable. - Press feedback is restrained and immediate. - Do not add a generic “live pulse,” ambient heartbeat, or real-time-status button as decoration. Real-time status appears only when a genuine live resource or safety state requires it. ### 15.7 Icons, graphics, and character - Use one coherent rounded icon grammar, with Material Symbols Rounded as the default web/mobile reference. - Icons are paired with text when meaning is not universal. - Product graphics are original, flat 2D or deliberately code-native diagrams unless the contract calls for another medium. - No 3D plastic mascots, generic glossy AI spheres, fake glass dashboards, ribbon overlays, or clip-art decoration. - Generated raster characters require source, transparent final output, provenance, consistent construction, and real in-product use. - Characters never appear on medical, destructive, privacy, payment, or security decisions without a documented product reason. ### 15.8 Motion - Entry motion: roughly 240–320ms with a short settle. - Selection: roughly 160–200ms. - Button press: approximately 100ms down and 160–200ms release. - Respect reduced motion. - No infinite confetti, ornamental parallax, automatic carousel, wobbling dashboards, or scroll-jacking. ### 15.9 Visual acceptance - Judge real running screens, not detached mockups. - Verify loaded fonts, actual icons, real assets, representative data, navigation, and primary interactions. - Review the combined application after parallel screen implementation. - Machine measurements may identify overflow, contrast, radius, target-size, or similarity problems; they do not decide beauty. - One independent fresh-context visual review establishes and explains a new product foundation autonomously. - Passing HTML, screenshot hashes, or screenshot quantity never override visibly poor output. ## 16. ProjectName architecture/control-plane site Maintain a static, deployable companion site under `apps/modular-system-studio`. Neutral pre-name deployment: `https://modular-builder-lab.pages.dev/`. Do not replace this with a permanent branded project or URL until the operator approves the system name. It must provide: - the ProjectName thesis and naming rationale; - an interactive graph view with selectable scenarios; - visible node state, dependencies, mode, resource reads/writes, and exclusive resources; - direct-versus-graph decision guidance; - module and recipe map; - exact resource and anti-overengineering rules; - legacy keep/change/remove/add summary; - the complete product-design standard; - phased implementation roadmap; - future Hermes boundary; - a link to this exact goal document. The site is an architecture simulator and review surface first. It must not pretend to be connected to a live ProjectName daemon until it consumes authenticated runtime events. Cloudflare target: a static Pages deployment. No backend, D1, Durable Object, queue, or agent runtime is justified for the architecture site. ## 17. Future Hermes boundary Hermes is a future conversational operator, not another orchestrator. ```text operator <-> Hermes <-> signed ProjectName command API <-> ProjectController -> workers -> verifiers -> integration ``` Hermes may eventually: - explain project state in plain language; - create a draft goal or plan revision; - request ProjectName to start, pause, resume, or cancel authorized work; - answer what is running, blocked, waiting, or accepted; - request evidence and previews; - report an action that standing policy did not authorize and the safe fallback ProjectName chose. Hermes may never: - edit product code directly; - own project state; - acquire resource locks; - bypass recipe or permission policy; - declare implementation accepted; - integrate commits; - silently broaden user authority; - disguise a ProjectName blocker as conversational success. Hermes integrates only after ProjectName exposes a stable, versioned command/query API and the graph engine has passed multi-project recovery tests. Read-only explanation ships before mutating commands. ## 18. Implementation phases ### Phase 0 — Freeze and prove the baseline - Declare the clean ProjectName worktree and pinned starting commit. - Keep the dirty production checkout untouched. - Preserve legacy Core evidence and mechanism inventory. - Record baseline direct-task and long-task outcomes. - Finalize contracts and deletion/extraction map. Gate: one authoritative source location, one goal, and one before-state report. ### Phase 1 — Direct golden loop - Extract event, worktree, process-cleanup, lineage, change-set, and integration primitives. - Implement the minimal ProjectController and state model. - Implement `direct_fix` with Sol/high planning and one Luna/xhigh implementation adapter. - Distinguish transport exit from acceptance. - Prove normal completion, rejection, killed-worker recovery, and bounded retry. Gate: five representative direct tasks complete with no orphaned process, ambiguous state, or full-plan reopen. ### Phase 2 — Work graph and resources - Add DAG validation and ready-node calculation. - Add logical and physical resource claims. - Add central lease ordering, expiry, and fairness. - Add artifact/contract/foundation version checks. - Add serialized milestone integration. Gate: two projects progress concurrently; compatible nodes overlap; conflicting writers serialize; killing one worker does not disturb the other project. ### Phase 3 — Backend and UI modules - Add `backend_feature`, `ui_change`, and `ui_foundation`. - Pin design-foundation versions. - Add independent behavior and visual acceptance. - Prove cooperative, competitive, and read-only modes. Gate: one backend feature and one real UI vertical slice are accepted from running integrated products. ### Phase 4 — Long build - Add architecture/interface milestone support. - Roll a one-to-two-milestone planning horizon forward without losing the complete product contract. - Add dependency-safe implementation waves. - Add compatible integration batches and graph compaction. - Add system-level canary and bounded replanning. - Prove critical-path priority, warm-cache reuse, and measured wall-time improvement. Gate: a multi-module application milestone runs across interruption and resumes without duplicate work or global reset. ### Phase 5 — Release and authority switch - Add the isolated `release` recipe. - Shadow-run ProjectName beside legacy Core on matched canaries. - Compare autonomous contract acceptance, elapsed time, model cost, retries, recovery, and later human product judgment. - Switch authority only when ProjectName wins or matches the direct lane and materially improves complex work. - Archive legacy Core read-only. ### Phase 6 — Hermes, later - Stabilize versioned query API. - Ship read-only Hermes explanation. - Add signed, policy-checked commands one at a time. - Read the standing `AutonomyPolicy`; execute authorized commands and return safe fallbacks for unauthorized destructive, external, release, credential, or authority-expanding actions. ## 19. Verification strategy ### Kernel contract tests - duplicate event idempotency; - compare-and-set conflict; - graph cycle rejection; - dependency readiness; - lease compatibility and expiry; - attempt budget exhaustion; - killed process recovery; - stale base/foundation rejection; - integration ordering; - project completion proof. ### Module conformance tests Every module runs against shared fixtures proving input validation, result-envelope validity, no unauthorized state mutation, bounded retries, cleanup, and artifact-consumer lineage. ### End-to-end canaries 1. one-line contained fix; 2. backend feature with schema/API contract; 3. UI change against a pinned foundation; 4. competitive two-direction visual decision; 5. two simultaneous projects; 6. overlapping-writer conflict; 7. worker termination and restart; 8. long-build milestone resume; 9. browser-shell milestone: URL loading, tabs, session persistence, forced interruption, and exact resume; 10. frozen-commit release verification. ### Comparison metrics - autonomous product-contract acceptance and later human acceptance as an offline comparison metric; - integrated behavioral correctness; - elapsed wall time; - critical-path duration and downstream unlock latency; - planning, ready-queue, verification, and integration wait; - build/test cache hit rate; - provider/model calls and cost; - useful product-work percentage; - retry and reopen count; - recovery time; - orphan/leak count; - modules invoked and value produced; - artifacts produced but never consumed; - source files and prompt tokens Luna inspected before its first relevant edit. ## 20. Continuous execution rules - Work only on the earliest phase whose gate is not satisfied. - Within a phase, choose the smallest vertical slice that produces observable accepted behavior. - Integrate and preserve each accepted slice before beginning another. - Run affected checks after each integration and the phase gate before advancing. - Update the progress ledger after every accepted milestone or material blocker. - Do not convert an architectural question into code until a current canary requires the answer. - Do not weaken acceptance to preserve momentum. - Stop adding mechanisms when the current vertical slice is blocked; diagnose the actual blocker. - A new subsystem requires a deletion, consolidation, or explicit mechanism-budget exception. - Status reports describe accepted product/system change, evidence, blocker, owner, and next action—not worker count or generated volume. ## 21. Terminal conditions ### Complete The goal is complete only when: - the direct lane passes its canaries; - the graph lane passes dependency, conflict, concurrency, and recovery canaries; - the initial six recipes are either implemented and justified or explicitly removed as unnecessary; - a real UI vertical slice satisfies the product-design standard; - a long build resumes correctly across interruption; - the architecture/control-plane site reflects tested reality; - the Cloudflare deployment points to the exact tested site build; - the mechanism inventory demonstrates material reduction from legacy Core; - no critical outcome depends on an unimplemented Hermes feature; - legacy authority is switched only after comparative evidence. ### Blocked Report `blocked_external` only when every useful deliverable depends on unavailable credentials, unavailable hardware or service, destructive authority, an external purchase, or another capability the standing policy cannot safely replace. Ordinary ambiguity, aesthetic choice, architecture choice, and missing implementation detail never require operator input. ### Partial At a time boundary, preserve accepted work and report every unmet gate, exact evidence, and smallest next action. Never report architectural scaffolding as a complete system. ## 22. Progress ledger Update this section in place. Keep only the current phase summary and the last ten accepted milestones; detailed history belongs in events and run reports. Current phase: Phase 1 — Direct golden loop Current state: Phase 0 is accepted. Phase 1 now has a persistent SQLite project/event authority, atomic work-attempt-candidate-failure artifacts, deterministic success/rejection/retry/terminal transitions, independent candidate acceptance, an unattended controller, process-family cleanup, and restart-safe isolated Git workspaces. Cross-process restart reconciliation, real Luna/Git integration adapters, and representative direct canaries remain. Accepted milestones: - 2026-07-31: operator rejected Orrery; binding name remains pending while the researched shortlist is reviewed. - 2026-07-31: Sol/high assigned planning, decomposition, revision, and independent review; Luna/xhigh assigned all bounded write-enabled implementation. - 2026-07-31: AI-navigable source-shape rule accepted: 200–400 logical lines per handwritten implementation file on average, with a cohesion review rather than automatic rejection above 500. - 2026-07-31: rolling outcome, architecture, integration, and execution horizons accepted, with a browser application as the long-build stress test. - 2026-07-31: throughput contract accepted: critical-path priority, interface-first unblocking, clean reusable environments, content-addressed caches, affected checks, risk-tier review, and compatible integration batches. - 2026-07-31: unattended autonomy contract accepted: no intermediate human checkpoints, autonomous product and design selection, standing policy authority, safe fallbacks, and revision goals only after delivery. - 2026-07-31: Wobbleby mobile canary design contract selected as the craft reference, excluding its product-owned colors, mascot, copy, and layouts. - 2026-07-31: neutral architecture studio deployed to `https://modular-builder-lab.pages.dev/`; desktop and 402px layouts, naming preview, graph progression, goal artifact, security headers, and production runtime were verified. - 2026-07-31: Phase 0 runtime baseline and extraction inventory accepted; neutral Core contracts passed TypeScript, source-shape/cycle checks, and their initial 23 focused tests. - 2026-07-31: Phase 1 direct runtime expanded: SQLite compare-and-set authority, atomic packet/attempt/candidate/failure persistence, exact idempotency, independent acceptance, detached process-family reaping, deterministic Git workspace reuse, bounded autonomous retry, and evidence-backed terminal stop pass 51 focused tests across ten suites; 15 runtime files average 147 logical lines with a 459-line maximum. Current blocker: none. Operator name selection remains pending for permanent branding but does not block runtime Phase 1. Next action: persist launched process identity before waiting, reconcile a running attempt after a controller restart, connect the real Luna and Git inspection/integration adapters, then run representative direct canaries without adding a second scheduler or asking the operator.