diff --git a/docs/BUILD_LOG.md b/docs/BUILD_LOG.md index 687dfee..5d13eff 100644 --- a/docs/BUILD_LOG.md +++ b/docs/BUILD_LOG.md @@ -392,4 +392,17 @@ Evidence: `docs/v0.3/ADR-009-DECISION-FUTURES.md`; updated PRD, thesis, research - Added delayed AI-off transfer, longer-delay and field boundaries, privacy/minimization rules, ordered analysis, event contracts, and kill criteria that remove mechanisms when they do not add behavioral value. - Grounded the design in current coding-skill and human-agency research without treating immediate quizzes, surveys, interviews, or target thresholds as product evidence. -Evidence: `docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md` and updated experiment/execution handoff documents. No participants were enrolled, no target was measured, and implementation remains gated by the complete R7 expert audit plus R5/R6 runtime. +Evidence: `docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md` and updated experiment/execution handoff documents. No participants were enrolled, no target was measured, and implementation remains gated by the complete R7 expert audit plus R5/R5.1/R5.2/R6 runtime. + +## 2026-08-01 — Operator Projection / Dual Source hypothesis + +- Identified the remaining category gap: Intent Ledger, Operator Model, and Decision Futures were individually specified but the repository still appeared to be the only source of truth for both agents and humans. +- Proposed ADR-010: agents maintain the complete Software Source while a pure Operator Projection renders immutable human commitments, decisions, invariants, control handles, and bounded control evidence for critical seams. +- Defined a one-way event algebra, stale-base/concurrency rules, forward agent obligations, reverse Operator Deltas, derived display states, no-self-certification laws, deterministic invalidation, and a participant projection that does not require maintaining a DSL or reading a full diff. +- Distinguished the proposal from Microsoft Programming with Representations, Apple Athena, bidirectional views, tests, AI-generated architecture graphs, and model-driven development. +- Added a matched representation pilot. Operator Source is removed from the product core if it does not improve causal localization per active minute over the existing Intent Ledger and Operator Model projection. +- Triaged current practitioner remedies—generation/explanation, random code questions, second-agent review, AI-free quotas, contract-first work, spaced repetition, and simplification—into comparators or bounded supporting tactics. Added causal checksum and maintenance escrow as executable adaptations rather than comprehension rituals. + +An adversarial architecture review rejected a second mutable source and duplicate readiness state. The revised ADR makes “Dual Source” a falsifiable product metaphor over one event authority, separates stable node identity from immutable revision projections, keeps accountability failure off the production critical path, adds explicit R5.1/R5.2 runtime workstreams, and isolates live authority in R8 with matched prebuilt alternatives and separate speculative cost. + +Evidence: `docs/v0.3/ADR-010-DUAL-SOURCE-OPERATOR-SOURCE.md` and synchronized PRD, thesis, research, experiment, completion-audit, and handoff documents. This is a proposed projection and experiment, not implementation or skill-preservation evidence; full R7 remains the entry gate. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 79d9ed3..2ab8951 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -36,7 +36,8 @@ Branch `codex/shadow-cockpit-rnd` resets the product R&D thesis around **Dual-Co - The preregistered R7 collector froze 30 eligible patches from six repositories after evaluating 457 bounded eligibility records. Manifest `a4ef6cbfa48c66cb9d384bcc2834ecbfae8ff08810abfd1863b395b8aa47d149` contains 12 development and 18 held-out patches; `docs/v0.3/results/R7_CORPUS_COLLECTION.md` reports repository and first-match exclusion counts. No compiler or human outcome influenced selection. - The frozen R7 automatic audit passed its preregistered automatic threshold: 17/18 held-out identities compiled and 16/18 were valid end-to-end. The frozen blind expert packet set and deterministic rating join exist, but two independent ratings and adjudication remain pending. Full R7 has not passed; R5/R6 stay gated. - ADR-007 proposes an Executable Operator Model and shadow-control protocol. ADR-008 adds a bidirectional Intent Ledger for artifact accountability. ADR-009 adds Decision Futures and a Takeover Envelope so an on-time pre-reveal human commitment can determine a live integrated branch while agents retain implementation. Together they cover artifact accountability, demonstrated control, and real decision authority; none is implementation evidence. -- `docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md` now defines the draft four-condition human study needed to test the combined architecture against ordinary autonomous use and a fixed active-review comparator. It has no participants or measured outcomes and cannot be frozen until full R7 and the R5/R6 runtime exist. +- ADR-010 proposes Dual Source only as a falsifiable product metaphor: agents maintain the complete Software Source while a pure, sparse Operator Projection renders immutable human commitments and bounded control evidence. It owns no state or readiness authority and must beat the existing representation in a matched pilot before becoming core. +- `docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md` now defines the draft four-condition human study needed to test the combined architecture against ordinary autonomous use and a fixed active-review comparator. It has no participants or measured outcomes and cannot be frozen until full R7 and the R5/R5.1/R5.2/R6 runtime exist. - `GOAL_COMPLETION_AUDIT.md` maps the original product goal to current evidence. It explicitly records that the live agent plane, v0.3 cockpit, cold relay, delayed-transfer study, and skill-preservation claim remain incomplete. - The readiness ledger and v0.3 cockpit do not exist yet. R0–R4.5 remain a closed reviewed-fixture mechanism and do not execute arbitrary participant or workspace code. - No skill-retention or speed metric has been measured. Values in the PRD are predeclared R&D targets. @@ -156,9 +157,9 @@ No external input blocks the repository-owned fixture R0–R4.5 mechanism in `do ## Next ordered actions 1. Obtain and adjudicate two independent blind expert ratings for packet index `54d78382b3ddbe15cba1f8153275e8149d32ddaa5192163f99ca5f43d903e8fe`. -2. If full R7 passes, review ADR-007, ADR-008, ADR-009, and the R8 combined protocol together, then freeze the Operator Model, Intent Ledger, Decision Future, and Takeover Envelope schemas, hash domains, projections, evidence authorities, timing policy, selector ablations, and four-condition study contrasts before implementation. -3. Add the local readiness ledger and minimal cockpit only after the complete R7 expert gate passes. -4. Freeze and run the four-condition delayed-transfer pilot only after the technical runtime can instantiate every condition; run the longitudinal field pilot before making a sustained skill-retention claim. +2. If full R7 passes, review ADR-007–010 and the R8 combined protocol together, then freeze the baseline ledger/model schemas and one offline Operator Source prototype. +3. Implement the local R5 evidence ledger and run Experiment 2.5 with identical evidence in both projections; make Operator Source the R6 default only if it improves causal localization per active minute without increasing false confidence. +4. Build the minimal cockpit with the surviving projection, then freeze and run the four-condition delayed-transfer pilot; run the longitudinal field pilot before making a sustained skill-retention claim. ## Recent milestone commits diff --git a/docs/v0.3/ADR-009-DECISION-FUTURES.md b/docs/v0.3/ADR-009-DECISION-FUTURES.md index fd9ec61..1cef422 100644 --- a/docs/v0.3/ADR-009-DECISION-FUTURES.md +++ b/docs/v0.3/ADR-009-DECISION-FUTURES.md @@ -407,7 +407,7 @@ Preserves autonomous implementation and unrelated progress while giving a small This ADR does not authorize R5/R6 implementation. Before acceptance: 1. complete and adjudicate the two-rater R7 expert audit; -2. review ADR-007, ADR-008, and ADR-009 as one architecture; +2. review ADR-007–010 as one architecture and either accept Operator Source as their shared projection or remove the extra abstraction; 3. freeze Decision Future projections, hash domains, alternative validity, deadline semantics, and integration authority in `CONTRACTS.md`; 4. compile one offline natural disagreement fixture with a false-fork negative control; 5. compare shadow-only and live-influence modes before expanding the cockpit; diff --git a/docs/v0.3/ADR-010-DUAL-SOURCE-OPERATOR-SOURCE.md b/docs/v0.3/ADR-010-DUAL-SOURCE-OPERATOR-SOURCE.md new file mode 100644 index 0000000..17618f8 --- /dev/null +++ b/docs/v0.3/ADR-010-DUAL-SOURCE-OPERATOR-SOURCE.md @@ -0,0 +1,359 @@ +# ADR-010 — Operator Projection and the Dual Source hypothesis + +- **Status:** Proposed product hypothesis; not a fourth architectural subsystem +- **Date:** 2026-08-01 +- **Deciders:** repository owner after R7 adjudication +- **Extends:** ADR-007, ADR-008, and ADR-009 + +## Context + +PureFlow has mechanisms for three distinct problems: + +- the Intent Ledger accounts for every generated line without requiring a full-diff review; +- the Executable Operator Model records project behavior the developer has demonstrated they can control; +- Decision Futures give selected pre-reveal human commitments real integration authority. + +Together they are stronger than questions or explanations, but the product can still feel like a collection of instruments attached after code generation. The repository remains the only obvious source of truth. The human sees a projection of what agents changed, demonstrates control in isolated episodes, and occasionally chooses a live path, yet there is no single compact artifact that answers: + +- What intent has the human committed before seeing the result? +- Which causal and architectural decisions have bounded control evidence? +- Which observations, actuators, and recovery paths make that belief executable? +- Where did implementation drift from those commitments? +- What useful project model remains if the agent transcript and model disappear? + +A natural response is to make a DSL or natural-language specification the source of truth. That does not fit PureFlow. A domain DSL is expensive to introduce into arbitrary existing repositories, excludes behavior it cannot express, and tends to reduce the need for coding expertise rather than preserve it. Unstructured prose has the opposite problem: it is easy to generate and approve but cannot reliably constrain implementation or prove that it still matches behavior. + +The product may need a human-scale projection that is executable but does not pretend to replace general-purpose code or become a competing source of truth. + +## Decision + +PureFlow will test a product metaphor in which an agentic project is shown through two coupled views: + +1. **Software Source** — the complete files, dependencies, configuration, and tests executed by machines. Agents may write almost all of it. +2. **Operator Source** — the user-facing name for a compact, revision-bound `OperatorProjection` of human-committed intent, causal decisions, observable invariants, control handles, and recovery policies for critical seams. + +There is one architectural evidence authority: the existing immutable event stream plus Intent Ledger, Executable Operator Model, Decision Future, and `VerifiedReadiness` derivation. A pure **Operator Projection Compiler** reads those inputs and renders Operator Source plus an Operator Delta. It owns no mutable facts, performs no general bidirectional synchronization, and cannot promote evidence. “Dual Source” is therefore a falsifiable product/category hypothesis, not the name of a fourth subsystem. + +```text +human goal / pre-reveal commitment + │ + ▼ + Operator Projection + intent ─ decision ─ invariant ─ observe/actuate/recover + │ ▲ + │ forward obligations │ executable evidence + ▼ │ + autonomous build plane ─────► Software Source + ▲ │ + └──── reverse deltas ─────┘ + attributed / stale / contradicted / unknown +``` + +The category statement becomes: + +> Hypothesis: PureFlow can let agents write the full machine source while maintaining an evidence-bound operator projection that shows where human commitments and bounded control agree with it, diverge, or remain unknown. + +### Operator Source is not documentation + +An Operator Projection node exists only when it is bound to controller-owned evidence and a revision. It may contain: + +- a committed goal or bounded decision; +- a behavioral invariant with an executable observation; +- an architectural boundary and its permitted dependency direction; +- a discriminating experiment between viable causal models; +- an observation, actuator, and recovery route; +- a conditional policy committed before an outcome is revealed. + +Free-form summaries, generated tours, README prose, hidden chain-of-thought, and unexecuted model claims cannot become evidence-backed Operator Source. + +### Derived display states + +The projection displays a state derived from referenced immutable events. It does not store or mutate an independent authority field: + +| Display state | Derivation | May support human-readiness evidence? | +| --- | --- | --- | +| `proposed` | only an agent/compiler proposal exists | no | +| `committed` | a valid pre-reveal human commitment event exists | not by itself | +| `demonstrated` | scoped `CapabilityEvidence` supports the node at this revision | yes, within that evidence scope | +| `transferred` | the sole `VerifiedReadiness` derivation references a valid delayed adjacent result | yes, strongest bounded state | +| `stale` | a referenced source/evidence/control hash no longer matches | no current claim | +| `contradicted` | executable evidence contradicts the commitment | negative evidence | +| `unknown` | the projection cannot reconcile the inputs honestly | no | + +Opening, reading, accepting generated prose, or spending time in the editor never changes the event stream or derived state. The UI must say “committed intent” and “current evidence of bounded control”; it must not infer a person's current belief or broad ownership. + +### Forward compilation + +When a new valid human commitment event is appended, the compiler produces a bounded `AgentObligationSet` rather than direct code: + +- behaviors that must remain true; +- observations that must be preserved or added; +- allowed and forbidden dependency directions; +- recovery or rollback evidence required by the decision; +- unresolved ambiguity that requires a Decision Future or explicit autonomous default. + +Agents remain free to choose implementation details. A human commitment does not become a shell command, file path, patch, test oracle, branch name, or merge instruction. The normal sandbox and judge boundaries still apply. + +### Not a general bidirectional lens + +The word “synchronized” does not imply an automatic `put(view) → source patch`. Updating a compact view of arbitrary code is underdetermined: many implementations can satisfy the same intent, and silently selecting one would give the representation false authority. + +Operator Source therefore has a one-way event algebra: + +1. a reverse `get` derives the current projection and Operator Delta from versioned source plus evidence; +2. `commit(proposalHash, baseProjectionHash, payload)` appends an immutable commitment or decision event only when `baseProjectionHash` still names the current projection; stale bases are rejected and shown for explicit rebase; +3. forward compilation emits obligations and unresolved choices; +4. agents propose implementations, and the normal judge plus Decision Future protocol determines what may integrate; +5. agent/judge results may satisfy, contradict, or stale a projection node, but never edit the human commitment event. + +The controller serializes accepted commitment events per project and assigns a monotonic sequence number. Concurrent proposals may coexist; concurrent commits against the same base are accepted only when their declared semantic units do not overlap, otherwise the later commit must rebase. Projection conflicts are rendered as unresolved evidence, never last-write-wins truth. + +No generic write-back transforms Operator Source prose directly into Software Source. This deliberately gives up the convenience of an editable architecture diagram in exchange for unambiguous authority and auditable consequences. + +### Reverse reconciliation + +After an agent checkpoint, the Intent Ledger maps every changed line to a semantic unit and current attribution. The pure Operator Projection Compiler then computes an Operator Delta: + +- which projection nodes are still supported; +- which became stale or contradicted; +- which new behavior has no corresponding human-committed model or bounded control evidence; +- which mechanical/generated units are covered by reproducible receipts; +- which critical seam now exceeds the Takeover Envelope. + +The reverse pass may propose a node. It cannot silently edit or promote Operator Source. This prevents the same model that wrote the code from authoring a convincing human belief after the fact. + +### Human interaction + +The developer does not maintain YAML or approve a specification document. PureFlow exposes the smallest pending Operator Delta at an event-driven breakpoint: + +```text +Agent changed cache invalidation across 11 files. + +Software Source says: + tenant scope now participates in the cache key. + +Operator Source gap: + no demonstrated recovery route for cross-tenant contamination. + +[Choose discriminating trace] [Open takeover twin] [Let agents continue] +``` + +The human action must be information-dense: select evidence, predict a consequence, choose a boundary, direct a cold executor, or recover an adjacent fault. Agents may continue writing code and executing unrelated work. Budget `0` preserves full autonomy and creates no fake ownership state. + +### What “understanding every line” becomes + +Literal memory of every physical line is neither scalable nor verifiable. The projection aims to preserve the stronger engineering properties behind that phrase: + +- every changed line has an honest account in Software Source through the Intent Ledger; +- every critical behavior has an explicit, evidence-derived control state in the projection; +- the developer can navigate from a line to its intent, evidence, decision, and control surface; +- unsupported or machine-only areas remain visible rather than receiving an invented explanation; +- delayed executable takeover, not line recall, determines whether the model survived. + +This is analogous to understanding a program at source level rather than memorizing generated assembly. It does not excuse opaque code: any line without honest attribution remains debt, and any critical seam without human control remains outside the Takeover Envelope. + +## Non-normative contracts + +These shapes clarify the decision. They must not enter `CONTRACTS.md` before the R7 gate and architecture review. + +```ts +interface OperatorNode { + schemaVersion: 1; + nodeId: string; + projectId: string; + kind: "intent" | "decision" | "invariant" | "boundary" | "control-policy"; + createdByEventHash: string; +} + +interface OperatorNodeProjection { + schemaVersion: 1; + nodeId: string; + projectionHash: string; + predecessorProjectionHash?: string; + sourceTreeHash: string; + displayState: "proposed" | "committed" | "demonstrated" | "transferred" | "stale" | "contradicted" | "unknown"; + statement: string; + semanticUnitIds: string[]; + commitmentEventHash?: string; + capabilityEvidenceHashes: string[]; + verifiedReadinessHash?: string; + observeRefs: string[]; + actuateRefs: string[]; + recoveryRefs: string[]; + invalidatedByHashes: string[]; +} + +interface OperatorDelta { + schemaVersion: 1; + projectId: string; + baseTreeHash: string; + targetTreeHash: string; + retainedProjectionHashes: string[]; + staleProjectionHashes: string[]; + contradictedProjectionHashes: string[]; + proposedProjectionHashes: string[]; + uncoveredCriticalUnitIds: string[]; + intentLedgerHash: string; + operatorModelHash: string; + deltaHash: string; +} + +interface AgentObligationSet { + schemaVersion: 1; + projectId: string; + baseProjectionHash: string; + requiredBehaviorRefs: string[]; + requiredObservationRefs: string[]; + forbiddenBoundaryRefs: string[]; + recoveryEvidenceRefs: string[]; + unresolvedDecisionRefs: string[]; + obligationHash: string; +} +``` + +Internal and participant projections must differ. Participant views use sanitized workspace-relative labels and bounded prose. Canonical internal nodes use controller-owned IDs, deterministic ordering, strict evidence authorities, RFC 8785 canonicalization, and domain-separated hashes. + +## Relationship to existing components + +| Component | Question it answers | Operator Source relationship | +| --- | --- | --- | +| Flight Recorder | What observably happened during the run? | raw evidence input | +| Intent Ledger | Why does each generated unit exist, and how strong is that attribution? | total Software Source reconciliation | +| Executable Operator Model | What has the human demonstrated they can control? | capability-evidence input | +| Decision Future | Did a human commitment really affect integration? | creates live decision nodes | +| Takeover Envelope | Where can the human plausibly take over now? | derived coverage over current nodes | +| Operator Projection | What compact executable project model is supported by commitments and bounded evidence? | optional human-facing projection | + +Operator Source must be purely derived from these existing contracts plus immutable human commitment events. A separate mutable store, duplicate readiness state, or alternate evidence authority is rejected. + +## Architecture laws + +The eventual implementation must enforce: + +1. **No silent promotion.** Agent claims and reverse-compiled prose start `proposed`. +2. **No orphaned claims.** Every changed text line resolves through exactly one primary Intent Ledger unit or is labeled `accountability-unavailable`; this blocks attribution/readiness claims, not autonomous production. Only an independently configured high-risk production policy may gate integration. +3. **No false understanding.** Ledger coverage cannot promote an Operator Source node. +4. **No stale control.** A relevant source, evidence, or control-surface change deterministically derives affected projections as stale. +5. **No prose execution.** Statements cannot directly become commands, paths, patches, or judge logic. +6. **No hidden approval gate.** Budget `0`, skip, and timeout preserve normal autonomous delivery unless a separately configured production policy requires approval. +7. **No retroactive ownership.** A post-reveal agreement cannot become a committed or live-decision node. +8. **No representation monopoly.** Unsupported code remains visible through fallback hunks; the Operator Source never claims to fully specify arbitrary repositories. + +## Prior-art boundary + +Shared and intermediate representations are established: + +- Microsoft Programming with Representations uses domain-specific representations with guardrails to translate natural-language intent into programs, explicitly aiming to reduce the need for coding expertise. +- Apple Athena uses shared intermediate representations such as storyboards, data models, and GUI skeletons to scaffold iterative application generation. +- Bidirectional-transformation research studies lawful synchronization between a source and an editable view. +- executable specifications, model-driven engineering, traceability, tests, and architecture-as-code all predate PureFlow. + +PureFlow does not claim novelty for intermediate representations, executable specifications, or bidirectional views. The proposed contribution is narrower: + +> arbitrary existing software remains the sole complete executable source + agents retain implementation + a pure operator projection renders immutable human commitments and bounded control evidence + the generator cannot self-certify + delayed AI-off takeover tests whether that view is operationally useful + +This combination is a research hypothesis, not a proven global novelty claim. + +## Options considered + +### A. Keep code as the only source and generate explanations + +Simple, but the generator remains the authority for both implementation and its story. Explanations can improve navigation without preserving control. + +### B. Make a domain DSL the complete source of truth + +Strong inside a bounded domain, but incompatible with arbitrary existing repositories and shifts toward low-code generation. This is the Programming with Representations direction, not PureFlow's professional takeover goal. + +### C. Make tests the human source + +Tests are executable evidence but rarely encode architectural alternatives, causal models, diagnostic observations, or recovery policy. Agent-written tests may repeat the implementation's mistake. + +### D. Store a separate AI-generated architecture graph + +Adds another stale summary and lets the generator self-certify. A graph may visualize evidence but cannot own authority. + +### E. Operator Projection over existing evidence — selected for experiment only + +Keeps arbitrary code and full autonomy while testing a compact, executable, revision-bound project view that cannot be promoted by prose alone. Acceptance of this ADR authorizes the experiment and contract freeze, not a permanent product subsystem or category claim. + +## Experiment + +Run a pre-R8 representation pilot after full R7 and R5.1, before freezing the R6 projection. Use unfamiliar realistic TypeScript modules and matched active attention. + +Compare: + +1. Intent Ledger plus Executable Operator Model navigation; +2. the same mechanisms rendered through the Operator Projection with forward obligations and reverse deltas. + +Both conditions receive identical evidence, control episodes, agent output, and time budgets. The representation alone differs. + +Primary feasibility outcome: + +- time to produce the first valid causal hypothesis on an unseen adjacent fault. + +Secondary outcomes: + +- regression-free delayed adjacent completion; +- time to locate the controlling intent, evidence, and recovery route; +- incorrect causal claims and false confidence; +- maintenance time per meaningful checkpoint; +- stale-node detection and missed invalidation; +- rubber-stamp acceptance of proposed nodes; +- production critical-path cost; +- preference after completing the behavioral task. + +The representation pilot cannot replace the four-condition R8 controlled study. It selects or rejects a projection used inside Shadow control and Full PureFlow. + +### Falsifiers + +Reject Operator Source as a product-level abstraction if: + +- it does not beat the existing ledger/model projection on causal localization per active minute; +- developers treat proposed nodes as trustworthy generated documentation; +- projection and obligation derivation frequently produces ambiguous or misleading updates; +- maintenance cost breaches the frozen attention margin; +- stale nodes survive material code or evidence changes; +- bootstrapping arbitrary repositories requires a domain model or manual specification project; +- delayed takeover is flat or worse despite better immediate explanations; +- users cannot distinguish Software Source accountability from bounded human-control evidence. + +If the representation helps navigation but not takeover, retain it only as an optional code-navigation view and remove the dual-source category claim. + +## Consequences + +### Easier + +- explain the full product as one architecture instead of a bundle of questions and dashboards; +- preserve a compact project model when agent transcripts disappear; +- make human commitments, bounded control evidence, agent claims, and unknown areas visibly distinct; +- compile human decisions forward without asking the human to implement them; +- detect drift between recorded pre-reveal commitments and what agents shipped; +- connect total line accountability to critical-seam takeover evidence. + +### Harder + +- derivation and invalidation become central correctness problems; +- a useful granularity must be learned without becoming paperwork; +- participant projections must remain compact while preserving uncertainty; +- legacy repositories may begin with few human commitments or little bounded control evidence; +- a second “source” metaphor can overpromise unless claim boundaries remain explicit. + +## Entry and implementation gates + +This ADR does not authorize R5.1/R6 implementation. Before acceptance: + +1. complete and adjudicate the two-rater R7 expert audit; +2. review ADR-007–010 as one architecture and decide whether the projection is useful or unnecessary naming; +3. freeze one fixture's nodes, Operator Delta, obligations, projections, evidence authorities, invalidation rules, and hash domains; +4. add negative fixtures for self-certification, stale survival, ambiguous reverse updates, and omitted changed lines; +5. run the matched representation pilot before making Operator Source the default cockpit abstraction; +6. run the four-condition R8 and longitudinal studies before claiming skill preservation. + +## Research anchors + +- Microsoft Research, [Programming with Representations](https://www.microsoft.com/en-us/research/project/pwr/). +- Beason et al., [Athena: Intermediate Representations for Iterative Scaffolded App Generation with an LLM](https://machinelearning.apple.com/research/athena), IUI 2026. +- Matsuda and Wang, [Applicative bidirectional programming](https://doi.org/10.1017/S0956796818000096), Journal of Functional Programming, 2018. +- Yu et al., [Maintaining invariant traceability through bidirectional transformations](https://doi.org/10.1109/ICSE.2012.6227162), ICSE 2012. + +These sources establish representations, scaffolding, traceability, and bidirectional synchronization. They do not test developer skill preservation or validate this one-way Operator Projection. diff --git a/docs/v0.3/AGENT_EXECUTION.md b/docs/v0.3/AGENT_EXECUTION.md index de4555e..d7584f8 100644 --- a/docs/v0.3/AGENT_EXECUTION.md +++ b/docs/v0.3/AGENT_EXECUTION.md @@ -32,7 +32,7 @@ observable agent run Each phase ends in a coherent commit with tests. A downstream phase may start only when its acceptance checks pass. -Workstream IDs are stable references, not permission to execute in numeric order. The dependency graph is authoritative: R4.5 follows the guarded R0–R4 mechanism, and R7 gates all R5/R6 product-state/UI work. +Workstream IDs are stable references, not permission to execute in numeric order. The dependency graph is authoritative: R4.5 follows the guarded R0–R4 mechanism, and R7 gates all R5/R5.1/R5.2/R6 product-state/UI work. ## Target repository shape @@ -265,7 +265,7 @@ If a coherent episode cannot be produced without hand-writing logic for each pat - Bind every attempt once to its controller-issued ID, project, internal probe, claim hash, fixture manifest, catalog allowlist, and a sorted subset of the claim evidence. Tombstone all terminal attempts and reject replay or cross-project/hash reuse. - Treat timeout, cancellation, setup/launch failure, missing output, and runner error as `execution-error`; none may confirm a prediction that the check would fail. - Start with the deterministic no-model path. A configured Side Coach adapter may be added only after the same validator and capsule tests pass; its output remains an untrusted catalog selection or clarification. -- Keep results in the experiment layer. Do not persist or display readiness before the R7→R5/R6 gates. +- Keep results in the experiment layer. Do not persist or display readiness before the R7→R5/R5.1/R5.2/R6 gates. ### Acceptance @@ -312,9 +312,53 @@ If the fixture-only probe needs arbitrary participant code or model-generated te - relevant code changes mark previous evidence stale; - delete removes all local evidence for the selected project. +## Workstream R5.1 — Accountability and operator derivation + +**Entry gate:** R7 passes and ADR-007/008 evidence authorities are adjudicated. + +**Goal:** implement the Intent Ledger and Executable Operator Model as deterministic derivations, without an LLM certifying its own work. + +### Tasks + +- Persist immutable generation claims, source receipts, human commitment events, capability evidence, and invalidation events under one project-scoped event authority. +- Reconcile every changed text line to one primary semantic unit or label it `accountability-unavailable`; the label blocks accountability/readiness claims but does not block autonomous production. +- Derive operator-model nodes only from controller-owned actions and evidence hashes. +- Expose pure, versioned read APIs for ledger navigation, model snapshots, and invalidation deltas. +- Add canonicalization, domain-separated hash, stale-base commitment, overlapping-commit conflict, delete, and export fixtures. + +### Acceptance + +- an agent claim alone never becomes `supported`, committed, demonstrated, or transferred; +- omitted, overlapping, stale, contradicted, and unknown units remain visible; +- `commit(proposalHash, baseProjectionHash, payload)` rejects a stale base and never rewrites an earlier human event; +- a source/evidence change deterministically stales the affected derived view; +- budget zero preserves autonomous delivery while emitting honest accountability debt. + +## Workstream R5.2 — Decision Future controller + +**Entry gate:** R7 passes and ADR-009 timing/integration rules are adjudicated. + +**Goal:** make one pre-reveal human commitment capable of selecting a live integration path without putting the production swarm on the human critical path by default. + +### Tasks + +- Freeze comparable alternative hashes, autonomous default, evidence catalog, deadline, speculative budget, and integration rule before revealing outcomes or agent preference. +- Keep speculative heads isolated and make the controller—not an agent message—the sole integration authority. +- Record on-time, late, skipped, defaulted, integrated, discarded, and counterfactual outcomes without upgrading post-reveal agreement. +- Provide the same frozen alternative set for Shadow and Full experimental modes; vary only whether the commitment is binding. +- Add branch cleanup, crash recovery, duplicate-event, deadline, and concurrent-future fixtures. + +### Acceptance + +- a valid on-time commitment changes the integrated artifact exactly when the frozen rule says it should; +- skipped, late, invalid, or unavailable choices resolve to the frozen autonomous default; +- agent output cannot change the deadline, default, evidence catalog, or merge rule; +- base production cost and capped speculative cost are measured separately; +- unrelated production work does not wait for a human response. + ## Workstream R6 — Minimal cockpit -**Entry gate:** R7 technical corpus audit passes its preregistered threshold. +**Entry gate:** R7 passes; R5, R5.1, and R5.2 pass their technical fixtures; R7.5 selects or rejects the optional Operator Projection. **Goal:** expose the mechanism inside native IDE surfaces without turning the editor into a course. @@ -367,6 +411,24 @@ If the fixture-only probe needs arbitrary participant code or model-generated te Use the thresholds in `EXPERIMENTS.md`. If the compiler misses the gate, narrow or pivot before implementing prediction, counterfactual, multiple languages, or a full swarm manager. +## Workstream R7.5 — Operator Projection representation gate + +**Goal:** determine whether the Dual Source product metaphor is a useful projection or generated architecture theatre. + +This workstream starts only after full R7 and R5.1. It does not authorize the full cockpit. Build one offline pure projection over equivalent unfamiliar TypeScript fixtures with two views: Intent Ledger plus Operator Model, and the same evidence rendered as Operator Source plus Operator Delta. The projection owns no event, readiness state, or mutable authority. + +### Required artifacts + +- frozen participant projections with identical underlying evidence; +- preregistered causal-localization task, oracle, attention budget, and minimum worthwhile effect; +- deliberate `proposed`, `stale`, `contradicted`, and `unknown` nodes; +- no-self-certification and invalidation negative fixtures; +- de-identified result report separating navigation, confidence, and executable behavior. + +### Gate + +Operator Source may become the R6 default view only if Experiment 2.5 clears H9. Otherwise remove the projection and continue with the Intent Ledger and Operator Model directly. A better-looking diagram or higher preference score cannot pass this gate. + ## Workstream R8 — Human pilot **Goal:** test delayed transfer, not merely usability. @@ -378,8 +440,9 @@ Use [`R8_COMBINED_PILOT_PROTOCOL.md`](R8_COMBINED_PILOT_PROTOCOL.md) as the prer ### Entry gate - complete the frozen R7 expert ratings and adjudication; -- implement one versioned R5/R6 runtime capable of all four conditions; -- freeze ADR-007–009 schemas, hash domains, evidence authorities, invalidation, and timing rules; +- implement one versioned R5/R5.1/R5.2/R6 runtime capable of all four conditions; +- review ADR-007–010 together, then freeze the selected schemas, hash domains, evidence authorities, invalidation, and timing rules; +- run the matched Operator Source representation pilot; remove the dual-source projection if it does not improve causal localization per active minute; - pass technical fixtures for total changed-line reconciliation, operator-model invalidation, Decision Future integration integrity, and delayed-task isolation; - freeze the protocol, analysis code, task pairs, exclusions, and artifact hashes before enrollment. @@ -393,7 +456,7 @@ Use [`R8_COMBINED_PILOT_PROTOCOL.md`](R8_COMBINED_PILOT_PROTOCOL.md) as the prer - blinded scoring rubric; - raw-data minimization plan; - frozen four-condition protocol and ordered mechanism contrasts; -- Intent Ledger, Operator Model, Decision Future, and Takeover Envelope event schemas; +- Intent Ledger, Operator Model, selected Operator Source projection, Decision Future, and Takeover Envelope event schemas; - result report separating pilot targets from observed values. ### Gate @@ -412,15 +475,20 @@ flowchart LR R3 --> R4 R4 --> R45["R4.5 Control Pulse gate"] R45 --> R7["R7 Recovery + probe corpus audit"] - R7 --> R5["R5 Evidence ledger"] - R7 --> R6["R6 Cockpit"] + R7 --> R5["R5 Readiness evidence ledger"] + R7 --> R51["R5.1 Accountability + operator derivation"] + R7 --> R52["R5.2 Decision Future controller"] + R51 --> R75["R7.5 Operator Projection gate"] + R75 --> R6["R6 Cockpit"] R5 --> R6 + R51 --> R6 + R52 --> R6 R7 --> R8["R8 Human pilot"] R5 --> R8 R6 --> R8 ``` -R1, R2, and R3 may run in parallel only after R0 contracts are committed. R4 is the integration owner; R4.5 is the required Pulse boundary after that integration and remains outside the guarded Jules queue. R7 must pass before R5 or R6 starts. Avoid a free-running swarm editing the same contracts. +R1, R2, and R3 may run in parallel only after R0 contracts are committed. R4 is the integration owner; R4.5 is the required Pulse boundary after that integration and remains outside the guarded Jules queue. R7 must pass before R5, R5.1, or R5.2 starts; R5.1 precedes R7.5, and R7.5 selects or rejects the optional human projection before R6. Avoid a free-running swarm editing the same contracts. ## Definitions of done diff --git a/docs/v0.3/CONCEPTS.md b/docs/v0.3/CONCEPTS.md index 4404477..0b36b79 100644 --- a/docs/v0.3/CONCEPTS.md +++ b/docs/v0.3/CONCEPTS.md @@ -99,6 +99,7 @@ The production swarm builds normally. In parallel, the IDE compiles a high-value This combines four supporting mechanisms: - evidence-carrying generation supplies attribution and seam candidates; +- an optional Operator Projection renders commitments and bounded control evidence beside the complete agent-written Software Source, but only if its matched representation gate passes; - an attention scheduler chooses the smallest valuable human episode; - Decision Futures let a bounded pre-reveal human choice determine a live integrated path while agents implement alternatives; - executable fault/counterfactual practice produces behavioral evidence; @@ -225,6 +226,28 @@ real agent near miss This is a meaningful constraint: PureFlow should sometimes produce nothing rather than manufacture an easy question. The common interaction is evidence escrow plus executable recovery; a random function explanation remains only an experiment baseline. +## August 2026 concept triage + +The latest practitioner proposals are useful only when separated by the outcome they can establish: + +| Idea | Keep | Reject as product core | PureFlow adaptation | +| --- | --- | --- | --- | +| generation → explanation | fast orientation | fluency can masquerade as control | Active-comparator condition; never readiness evidence | +| random function question | cheap retrieval sample | arbitrary recall, interruption, easy gaming | low-cost probe baseline sampled only from current changed seams | +| second AI reviewer | code-quality redundancy | two models still cannot prove human understanding | autonomous build-plane verifier with no human-evidence authority | +| AI-free/retyping quota | exercises unaided recall | removes throughput and rewards typing | brief delayed AI-off takeover only as an outcome measurement | +| contract-first | preserves high-level choices | assumes the human can specify an unfamiliar system up front | pre-reveal Decision Future over bounded viable alternatives | +| spaced repetition / streaks | continuity and forgetting refresh | generic cards and engagement scores drift from project control | resurface stale high-criticality evidence; streak never enters readiness | +| “simplify to code I could write” | reveals accidental complexity | style familiarity is not causal control | compile the smallest observable/actuatable/recoverable seam, not a rewrite quota | + +Three new product hypotheses survive this triage: + +1. **Causal checksum:** at a meaningful checkpoint, one pre-reveal prediction plus its discriminating observation acts as a compact checksum of the operator's model. The executable result—not wording quality—determines whether it matched. +2. **Maintenance escrow:** the successful trace and repair remain sealed until the developer requests bounded evidence or exhausts the recovery ladder. This converts agent self-repair into future takeover practice without stopping production. +3. **Projection compiler:** “Operator Source” is only a pure rendering of immutable commitments and existing evidence. It is deleted if the matched H9 representation study does not beat direct Intent Ledger/Operator Model navigation. + +The architecture does not adopt “AI as a junior” as its operating model. Production agents may remain superhuman and fully autonomous; PureFlow preserves the human's ability to form causal models, select evidence, exercise consequential judgment, and recover the system. + ## Naming decision Avoid `Shadow Workspace`; Cursor already uses it for an AI validation environment. diff --git a/docs/v0.3/EXPERIMENTS.md b/docs/v0.3/EXPERIMENTS.md index e654aa8..4e0bf62 100644 --- a/docs/v0.3/EXPERIMENTS.md +++ b/docs/v0.3/EXPERIMENTS.md @@ -40,6 +40,10 @@ Project-scoped, time-stamped control evidence will predict delayed AI-off takeov The Intent Ledger will let developers locate the relevant intent, invariant, and evidence in generated changes faster than raw diffs or AI summaries, without false `supported` provenance. Navigation success is an accountability outcome, not proof of skill retention. +### H9 — Operator Projection improves causal orientation + +Rendering the same evidence through an Operator Projection and Operator Delta will reduce time to the first valid causal hypothesis on an adjacent fault compared with the existing Intent Ledger plus Operator Model views, without increasing false confidence or active attention. + ## What does not count as success - more questions answered correctly immediately after generation; @@ -218,6 +222,39 @@ This pilot is a feasibility and variance-estimation gate, not a confirmatory tes H5 requires a separately powered confirmatory comparison of policy 1 versus policy 3 using regression-free delayed adjacent-task completion as the primary outcome and attention time as a non-inferiority constraint. Before enrollment, preregister the minimum worthwhile transfer difference from pilot variance and the attention margin. H5 passes only if the transfer estimate exceeds that margin with the planned confidence bound and attention stays within its margin. If policy 2 performs as well as executable probing, narrow the mechanism claim; if the confirmatory policies perform alike, remove mid-run prompts from the core. +## Experiment 2.5 — Operator Projection representation pilot + +### Question + +Does the Operator Projection make existing control evidence more operational, or merely produce a more persuasive project summary? + +### Entry gate + +Run only after the complete R7 expert gate. Freeze one offline representation prototype, tasks, evidence, scoring, and active-time budget before participants see it. This pilot may gate the R6 projection but cannot establish skill preservation. + +### Conditions + +Use matched unfamiliar TypeScript modules and identical underlying evidence: + +1. Intent Ledger navigation plus an Executable Operator Model snapshot; +2. the same ledger/model data rendered as Operator Source nodes through a revision-bound Operator Projection and Operator Delta. + +Do not add extra tests, hints, explanations, or control episodes to condition 2. The representation is the only factor. + +### Outcomes + +- **Primary:** time to first valid causal hypothesis on an unseen adjacent fault; +- regression-free adjacent completion; +- time to locate controlling intent, evidence, and recovery route; +- incorrect causal claims and confidence calibration; +- stale-node detection and missed invalidation; +- active attention and maintenance cost; +- rubber-stamp acceptance of agent-proposed nodes. + +### Decision rule + +Freeze the minimum worthwhile time improvement and non-inferiority margins from a usability pilot before the confirmatory comparison. H9 fails if the projection does not improve causal localization per active minute, increases false confidence, hides unknown areas, or requires manual specification work. On failure, retain the Intent Ledger and Operator Model directly and remove Dual Source from the product category claim. + ## Experiment 3 — Controlled delayed-transfer study The complete preregistration template is [`R8_COMBINED_PILOT_PROTOCOL.md`](R8_COMBINED_PILOT_PROTOCOL.md). Freeze it before enrollment; this section is the decision summary. @@ -373,6 +410,10 @@ intent_ledger.opened intent_ledger.unit_selected intent_ledger.evidence_opened operator_model.snapshot +operator_source.snapshot +operator_delta.compiled +operator_source.node_committed +operator_source.node_invalidated takeover_envelope.snapshot decision_future.offered decision_future.committed diff --git a/docs/v0.3/GOAL_COMPLETION_AUDIT.md b/docs/v0.3/GOAL_COMPLETION_AUDIT.md index 82e5b06..d4d53b0 100644 --- a/docs/v0.3/GOAL_COMPLETION_AUDIT.md +++ b/docs/v0.3/GOAL_COMPLETION_AUDIT.md @@ -8,13 +8,13 @@ The original goal is broader than a compiler benchmark or an explanatory extensi | Requirement from the goal | Current evidence | Status | Evidence required for completion | | --- | --- | --- | --- | | Full agentic coding remains available | v0.1 is an IDE shell; v0.3 has a replay `AgentDriver`; ADR-006 selects a future live adapter | Incomplete | a live supported agent can plan, edit, test, and repair through the IDE on a real repository | -| Developer is not reduced to reading generated diffs | PRD, THESIS, ADR-007, ADR-008, and ADR-009 replace passive review with accountable generation, shadow control, and bounded live decisions | Architecture only | production UX demonstrates prediction, evidence selection, live influence, intervention, and recovery without requiring line-by-line review | -| Developer understands what the system does | R2 maps changed units to evidence; ADR-008 specifies total line reconciliation and explicit attribution debt | Partially represented, not proven | Intent Ledger exposes the current change account while the Executable Operator Model shows demonstrated causal claims, uncovered seams, contradictions, and delayed transfer | +| Developer is not reduced to reading generated diffs | PRD, THESIS, and ADR-007–010 replace passive review with accountable generation, an Operator Source, shadow control, and bounded live decisions | Architecture only | production UX demonstrates prediction, evidence selection, live influence, intervention, and recovery without requiring line-by-line review | +| Developer understands what the system does | R2 maps changed units to evidence; ADR-008 specifies total line reconciliation; ADR-010 proposes a compact executable Operator Source | Partially represented, not proven | Intent Ledger exposes the complete change account while the selected human projection shows current intent, decisions, causal claims, uncovered seams, contradictions, and delayed transfer | | Developer continues making engineering decisions | ADR-009 specifies Decision Futures, bounded live influence, dissent, and a Takeover Envelope | Not implemented | an on-time pre-reveal commitment determines a real integrated path and later predicts adjacent takeover better than shadow-only control | | AI can coach and question during work | Fixture-only precommitted Control Pulse exists; configured Side Coach remains bounded | Narrow fixture only | event-driven side interaction works during a live agent run and executable evidence, not an LLM score, adjudicates it | | AI may still write almost all code | Context-starved relay architecture explicitly allows this | Not implemented | a fresh agent writes a complete intervention from human-selected evidence and directive in the sandbox | | Skills remain available if AI disappears | Delayed AI-off adjacent takeover is the north-star metric | Unmeasured | preregistered controlled human study clears the delayed-transfer gate and later field evidence survives novelty | -| The product is more than a quiz/extension | Dual planes, SandboxRunner, Intent Ledger, compiler, judge, Operator Model, Decision Futures, and Takeover Envelope are designed | No v0.3 product runtime | readiness ledger, cockpit, live agent adapter, shadow/live-control flows, and local deletion/export work end-to-end | +| The product is more than a quiz/extension | Dual planes, SandboxRunner, Intent Ledger, Dual Source reconciliation, compiler, judge, Operator Model, Decision Futures, and Takeover Envelope are designed | No v0.3 product runtime | readiness ledger, selected Operator Source projection, cockpit, live agent adapter, shadow/live-control flows, and local deletion/export work end-to-end | | Autonomy speed is preserved | continuity rehearsal stays off-path; Decision Futures delay only one bounded integration boundary while agents execute alternatives and unrelated work | Unmeasured | production critical-path non-inferiority, speculative compute, and bounded attention pass the preregistered study | | Every generated line is accountable | PRD and ADR-008 require deterministic reconciliation to `supported`, `claimed`, `unattributed`, `contradicted`, or `stale` units | Architecture plus narrow TypeScript evidence only | real agent changes pass total line reconciliation and held-out expert attribution checks without invented provenance | @@ -25,7 +25,7 @@ The original goal is broader than a compiler benchmark or an explanatory extensi - frozen 30-patch corpus and preregistered automatic R7 audit; - automatic held-out result of 16/18 end-to-end valid episodes; - blind packet generation and deterministic two-rater join tooling; -- falsifiable product thesis and the proposed Operator Model, Intent Ledger, Decision Futures, and Takeover Envelope extensions. +- falsifiable product thesis and the proposed Operator Model, Intent Ledger, Decision Futures, Takeover Envelope, and Dual Source architecture extensions. ## What is not complete @@ -33,6 +33,7 @@ The original goal is broader than a compiler benchmark or an explanatory extensi - post-gate readiness ledger and v0.3 cockpit; - live Codex/Claude/OpenCode adapter accessible from this checkout; - context-starved relay on arbitrary supported project code; +- a validated human-source projection; Operator Source is proposed but has not passed Experiment 2.5; - Decision Futures with real bounded integration authority and an honest Takeover Envelope; - frozen four-condition delayed-transfer human experiment and participant evidence; - longitudinal evidence of skill preservation; @@ -49,8 +50,9 @@ The active goal may be marked complete only when all of these are true: 4. the developer can predict, choose evidence, direct a cold agent, recover, and make at least one pre-reveal decision that actually determines an integrated path; 5. local Operator Model state invalidates correctly as the code changes; 6. every changed line resolves through the local Intent Ledger to a bounded unit and an honest attribution state; -7. a delayed adjacent task demonstrates takeover without answer-generating AI; -8. the Full PureFlow condition beats the active diff/explanation/question comparator while preserving production speed, and its planned comparison with matched Shadow control isolates whether live decision authority adds value; -9. the runtime, deletion/export, packaging, and protected CI pass on supported platforms. +7. the selected human-facing projection exposes immutable human commitments and bounded control evidence without promoting agent prose or duplicating readiness authority, and re-derives stale when its software or evidence changes; +8. a delayed adjacent task demonstrates takeover without answer-generating AI; +9. the Full PureFlow condition beats the active diff/explanation/question comparator while preserving production speed, and its planned comparison with matched Shadow control isolates whether live decision authority adds value; +10. the runtime, deletion/export, packaging, and protected CI pass on supported platforms. Green unit tests for any individual component are necessary evidence, not completion of this goal. diff --git a/docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md b/docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md index 4f27c8b..b2338b7 100644 --- a/docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md +++ b/docs/v0.3/R8_COMBINED_PILOT_PROTOCOL.md @@ -1,6 +1,6 @@ # R8 combined human-control pilot protocol -**Status:** Draft. Freeze before enrollment. No participant run is authorized until the complete R7 expert gate passes and the R5/R6 runtime implements the tested conditions. +**Status:** Draft. Freeze before enrollment. No participant run is authorized until the complete R7 expert gate passes and the R5/R5.1/R5.2/R6 runtime implements the tested conditions. **Purpose:** test whether PureFlow can preserve autonomous coding speed while producing measurable project takeover ability, accountable understanding, and real engineering agency. @@ -37,10 +37,11 @@ Therefore R8 measures delayed executable behavior. It does not use confidence, e Enrollment may begin only after all of the following are true: 1. the two independent R7 ratings and adjudication clear the frozen expert gate; -2. R5/R6 implement all four conditions from one versioned runtime; -3. ADR-007, ADR-008, and ADR-009 schemas, hash domains, evidence authorities, timing rules, and invalidation rules are frozen; -4. held-out fixtures pass hidden-answer, production-isolation, line-reconciliation, and deterministic-oracle checks; -5. the protocol, analysis code, exclusions, minimum worthwhile effects, task pairs, and raw artifact hashes are frozen before condition outcomes are opened. +2. R5/R5.1/R5.2/R6 implement all four conditions from one versioned runtime; +3. ADR-007–010 selected schemas, hash domains, evidence authorities, timing rules, and invalidation rules are frozen without introducing a second readiness authority; +4. the matched Operator Source representation pilot either passes its frozen feasibility gate or removes ADR-010 from the tested projection; +5. held-out fixtures pass hidden-answer, production-isolation, line-reconciliation, and deterministic-oracle checks; +6. the protocol, analysis code, exclusions, minimum worthwhile effects, task pairs, and raw artifact hashes are frozen before condition outcomes are opened. The pilot estimates feasibility and variance. A power analysis based on blinded pilot aggregates must freeze the confirmatory enrollment size. A small convenience sample cannot clear the product claim. @@ -58,7 +59,7 @@ Randomize fixture/task-pair order with a preregistered balanced schedule. Partic ## 5. Four conditions -All conditions use the same agent model and version, task prompt, repository state, tests, documentation access, total production window, and token budget. +All conditions use the same agent model and version, task prompt, repository state, tests, documentation access, total production window, and base production token budget. Any speculative alternatives consume a separate capped budget and are reported as product cost. ### A. Autonomous / Cursor-like @@ -73,18 +74,18 @@ The same autonomous agent plus a fixed ten-minute post-hoc protocol: the same di The same autonomous agent plus: - Intent Ledger navigation; -- an Executable Operator Model snapshot; +- the selected Executable Operator Model projection, with Operator Source used only if its prior matched representation pilot passes; - one matched prediction, discriminating-observation, diagnosis, and recovery episode in a disposable twin. The participant's choice cannot alter the production branch. This isolates executable control practice from live authority. ### D. Full PureFlow / Decision Futures -Everything in Shadow control plus one genuine Decision Future. Before any outcome or autonomous preference is revealed, the system freezes comparable alternatives, an autonomous default, evidence catalog, deadline, and integration rule. An on-time participant commitment can determine the integrated production path. +Everything in Shadow control plus one genuine Decision Future. Before any outcome or autonomous preference is revealed, the controller prebuilds and freezes the same comparable alternative set, autonomous default, evidence catalog, deadline, and integration rule used to construct the matched Shadow fixture. An on-time participant commitment can determine the integrated production path. Late, skipped, defaulted, or counterfactual choices are recorded honestly and never upgraded to live-influence evidence. -Conditions B–D receive the same maximum ten minutes of active attention. The system may continue unrelated agent work while C or D is active. Speculative compute and any merge delay are reported separately from human attention. +Conditions B–D receive the same maximum ten minutes of active attention. The system may continue unrelated agent work while C or D is active. Shadow and Full receive the same frozen alternatives; randomization changes only whether the precommitted choice has live integration authority. Speculative compute and any merge delay are reported separately from human attention and from the identical base production budget. ## 6. Procedure @@ -115,7 +116,7 @@ After 48 hours, within a preregistered ±4-hour window: - give 45 minutes for a regression-free adjacent task; - require direct human diagnosis and editing because this phase models AI disappearance. -The transfer task shares an invariant, dependency seam, or data path with Phase A but uses a different failure family and cannot be solved by replaying the practiced mutation. +The transfer task shares an invariant, dependency seam, or data path with Phase A but uses a different failure family and cannot be solved by replaying the practiced mutation. Because Full may integrate a different alternative, transfer tasks must be branch-independent or each branch-specific form must pass a frozen blinded difficulty-equivalence pilot before enrollment. ### Phase C — Longer-delay subset @@ -196,6 +197,10 @@ intent_ledger.opened intent_ledger.unit_selected intent_ledger.evidence_opened operator_model.snapshot +operator_source.snapshot +operator_delta.compiled +operator_source.node_committed +operator_source.node_invalidated takeover_envelope.snapshot decision_future.offered decision_future.committed diff --git a/docs/v0.3/README.md b/docs/v0.3/README.md index f1fb3d0..7f4f28b 100644 --- a/docs/v0.3/README.md +++ b/docs/v0.3/README.md @@ -23,10 +23,11 @@ PureFlow v0.3 asks whether an AI IDE can keep autonomous coding fast while behav 17. [`OPERATOR_MODEL_SPEC.md`](OPERATOR_MODEL_SPEC.md) — draft post-R7 vertical-slice requirements, contracts, and ablations. 18. [`ADR-008-EVIDENCE-CARRYING-GENERATION.md`](ADR-008-EVIDENCE-CARRYING-GENERATION.md) — proposed bidirectional Intent Ledger for total change accountability without passive full-diff review. 19. [`ADR-009-DECISION-FUTURES.md`](ADR-009-DECISION-FUTURES.md) — proposed speculative live-steering protocol and project-scoped Takeover Envelope. -20. [`R8_COMBINED_PILOT_PROTOCOL.md`](R8_COMBINED_PILOT_PROTOCOL.md) — draft four-condition human protocol for delayed takeover, live authority, accountability, and readiness calibration. -21. [`GOAL_COMPLETION_AUDIT.md`](GOAL_COMPLETION_AUDIT.md) — requirement-by-requirement evidence separating infrastructure from the requested final product. -22. [`AGENT_EXECUTION.md`](AGENT_EXECUTION.md) — ordered implementation workstreams and acceptance gates. -23. [`JULES_LOOP.md`](JULES_LOOP.md) — guarded server-side execution queue for the audited R0–R4 slice. +20. [`ADR-010-DUAL-SOURCE-OPERATOR-SOURCE.md`](ADR-010-DUAL-SOURCE-OPERATOR-SOURCE.md) — proposed dual-source architecture: complete agent-written software plus a compact executable human control source. +21. [`R8_COMBINED_PILOT_PROTOCOL.md`](R8_COMBINED_PILOT_PROTOCOL.md) — draft four-condition human protocol for delayed takeover, live authority, accountability, and readiness calibration. +22. [`GOAL_COMPLETION_AUDIT.md`](GOAL_COMPLETION_AUDIT.md) — requirement-by-requirement evidence separating infrastructure from the requested final product. +23. [`AGENT_EXECUTION.md`](AGENT_EXECUTION.md) — ordered implementation workstreams and acceptance gates. +24. [`JULES_LOOP.md`](JULES_LOOP.md) — guarded server-side execution queue for the audited R0–R4 slice. ## Current truth @@ -39,7 +40,8 @@ PureFlow v0.3 asks whether an AI IDE can keep autonomous coding fast while behav - ADR-007 proposes an Executable Operator Model so episodes update a durable map of demonstrated control instead of remaining isolated exercises. It is architecture, not implemented evidence. - ADR-008 proposes an Intent Ledger that reconciles every changed line to supported, claimed, stale, contradicted, or explicitly unattributed semantic units. It is also architecture, not implemented evidence. - ADR-009 proposes Decision Futures so a bounded pre-reveal human commitment can determine a live integrated branch while agents implement alternatives and continue unrelated work. It is architecture, not implemented evidence. -- The draft R8 protocol now tests those mechanisms in four conditions. It is a preregistration template, not participant evidence, and remains blocked by full R7 plus the R5/R6 runtime. +- ADR-010 proposes the Dual Source product hypothesis: Software Source stays complete and agent-optimized, while an optional pure Operator Projection renders immutable human commitments and bounded control evidence. It is not a second store or evidence authority, and H9 must beat the existing views before it becomes core. +- The draft R8 protocol now tests those mechanisms in four conditions. It is a preregistration template, not participant evidence, and remains blocked by full R7 plus the R5/R5.1/R5.2/R6 runtime. ## Architecture shorthand @@ -47,6 +49,7 @@ PureFlow v0.3 asks whether an AI IDE can keep autonomous coding fast while behav production agent run → observable Flight Recorder → bidirectional Intent Ledger / total change account +→ Dual Source reconciliation / Operator Delta → high-value changed seam or attribution gap → controllability surface + operator-model delta → Decision Future or disposable Takeover Twin / context-starved relay diff --git a/docs/v0.3/RESEARCH.md b/docs/v0.3/RESEARCH.md index dba74dc..ae3ec45 100644 --- a/docs/v0.3/RESEARCH.md +++ b/docs/v0.3/RESEARCH.md @@ -205,6 +205,18 @@ The artifact-accountability problem has credible neighbors, so PureFlow cannot c ADR-008 therefore narrows the contribution to a combined mechanism: total changed-line reconciliation, untrusted agent claim references, executable evidence joins, visible attribution debt, and a separate Operator Model that only human actions can refresh. That combination remains a hypothesis until held-out expert attribution and delayed-transfer studies pass. +### Shared representations and the Operator Projection boundary + +[Microsoft Programming with Representations](https://www.microsoft.com/en-us/research/project/pwr/) uses a domain-specific representation with built-in guardrails to translate natural-language intent into programs, explicitly aiming to reduce the coding expertise required of downstream users. [Apple Athena](https://machinelearning.apple.com/research/athena) uses shared intermediate representations such as storyboards, data models, and GUI skeletons to scaffold iterative application generation. Bidirectional-programming research studies lawful synchronization between a source and an editable view. + +These precedents invalidate a novelty claim based on “an intermediate representation between prompts and code.” They also expose a different opportunity. PureFlow targets arbitrary existing repositories and aims to preserve professional takeover expertise rather than decouple users from it. ADR-010 therefore proposes Operator Source as a sparse view over immutable commitments and existing evidence authorities, not a domain DSL, full alternative program, or new source of truth. Its value must be tested against the existing Intent Ledger and Operator Model views under matched evidence and attention. + +### Community remedies and why they are comparators + +Current practitioner advice clusters around generation-then-explanation, ownership rituals, AI-free coding quotas, smaller iterations, contract-first work, spaced repetition, and a second AI reviewer. Anthropic's randomized study makes the concern concrete: participants using AI assistance on an unfamiliar library scored lower on immediate concept mastery, with debugging comprehension particularly affected. The same study also observed better outcomes when people used AI to build understanding rather than merely request an answer. + +These are useful baselines, not the PureFlow mechanism. Explanation and AI review can improve navigation or code quality without proving human control; retyping, quizzes, and AI-free quotas sacrifice the autonomy constraint; contract-first workflows cover only work where the human can specify the contract in advance. R8 therefore includes a strong post-hoc explanation/question comparator while PureFlow requires pre-reveal commitments, executable observation and recovery, and delayed adjacent transfer. + ## 5. Adjacent precedent: operational drills Reliability engineering already treats human response as something to exercise: @@ -231,7 +243,7 @@ This is meaningful differentiation within the reviewed landscape, not proof of a The defensible product core is therefore the combination: -> bidirectional Intent Ledger + Decision Futures + semantic scenario compiler + interruption-aware scheduler + executable evidence judge + longitudinal Takeover Envelope +> Intent Ledger + Decision Futures + semantic scenario compiler + interruption-aware scheduler + executable evidence judge + longitudinal Takeover Envelope, optionally rendered through a validated Operator Projection If PureFlow collapses back to explanations, questions, code tours, manual `TODO`s, or isolated bug games, it enters an already occupied category. diff --git a/docs/v0.3/THESIS.md b/docs/v0.3/THESIS.md index 38f37e0..9a8b2c9 100644 --- a/docs/v0.3/THESIS.md +++ b/docs/v0.3/THESIS.md @@ -149,6 +149,12 @@ Every changed line is either covered by a supported semantic unit with available ADR-008 makes this concrete as a bidirectional Intent Ledger. Agent-emitted intent links are untrusted claims; the ledger independently reconciles every changed line to a bounded semantic unit and labels the link `supported`, `claimed`, `unattributed`, `contradicted`, or `stale`. Derived artifacts may bind to a deterministic generation receipt. This creates navigable accountability without claiming that the developer read or memorized every token. +### Operator Projection / Dual Source hypothesis + +Code optimized for machine execution is not necessarily the best view for continuous human control. ADR-010 proposes testing two coupled views: the complete Software Source written largely by agents and a compact Operator Source projection containing human commitments, decisions, invariants, and control policies for critical seams. + +Operator Source does not replace code, own evidence, or let prose self-certify. It is a pure view over immutable commitments and the existing evidence authorities. The Intent Ledger reconciles every generated line; executable actions provide bounded control evidence; the projection exposes drift without silently rewriting commitments. The product hypothesis is stronger than “show the developer what changed” only if a matched experiment shows better causal orientation and delayed takeover than the underlying ledger/model views. + ### Readiness of the operator For a critical seam, the developer can: diff --git a/prd.md b/prd.md index 68c0c03..c840949 100644 --- a/prd.md +++ b/prd.md @@ -203,6 +203,19 @@ This is **evidence-carrying generation**, not proof of correctness. The Intent L The full decision, integrity rules, and falsifiable evaluation are specified in `docs/v0.3/ADR-008-EVIDENCE-CARRYING-GENERATION.md`. Like the Operator Model, it remains a post-R7 hypothesis. +## Operator Projection / Dual Source hypothesis + +PureFlow will test whether an agentic project is easier to own when shown through two coupled views. **Software Source** is the complete executable repository and may be written almost entirely by agents. **Operator Source** is the product name for a compact, revision-bound `OperatorProjection` of human-committed intent, decisions, invariants, observations, control handles, and recovery policies for critical seams. + +Operator Source is not a DSL, generated architecture document, separate mutable database, or second evidence authority. A pure compiler derives it from immutable commitment events, the Intent Ledger, Operator Model, Decision Future evidence, and the sole `VerifiedReadiness` derivation. Agent-generated nodes remain proposals. Pre-reveal commitment and executable evidence create only bounded claims; code and evidence changes deterministically derive affected projections as stale or contradicted. + +The bidirectional compiler therefore produces two deltas after a checkpoint: + +- a total Software Source account for every generated line; +- an Operator Delta showing which human commitments and bounded-control claims remain supported, became stale, were contradicted, or now leave a critical seam uncovered. + +This may give the developer a human-scale project view without asking them to maintain a specification language or read every physical line. ADR-010 defines the one-way event algebra, laws, prior-art boundary, and matched representation ablation. “Dual Source” remains a proposed category hypothesis until that ablation improves executable causal orientation over the existing views. + ## Executable Operator Model PureFlow maintains a second, local versioned view beside the program: the causal claims the developer has actually demonstrated for this project. @@ -211,7 +224,7 @@ It is not an AI-generated repository summary. A claim can become fresh only thro This gives the IDE a concrete answer to “what should the developer think about while agents keep coding?” It chooses the smallest action that reduces divergence between the running software and the operator's demonstrated model. A successful action should create a control dividend such as a regression probe, observation recipe, rollback path, or reusable recovery handle. -The Operator Model is specified in `docs/v0.3/ADR-007-EXECUTABLE-OPERATOR-MODEL.md`. Decision Futures and the Takeover Envelope are specified in `docs/v0.3/ADR-009-DECISION-FUTURES.md`. Both remain post-R7 hypotheses until the complete expert gate and human experiments pass. +The Operator Model is specified in `docs/v0.3/ADR-007-EXECUTABLE-OPERATOR-MODEL.md`. Decision Futures and the Takeover Envelope are specified in `docs/v0.3/ADR-009-DECISION-FUTURES.md`. ADR-010 proposes an optional human-facing projection over them, not another authority. All remain post-R7 hypotheses until the complete expert gate and human experiments pass. ## Autonomy Router @@ -300,7 +313,7 @@ The R&D architecture is: - VSCodium plus a bundled extension for the product surface; - adapters over existing coding-agent runtimes for the build plane; -- PureFlow-owned Flight Recorder, Intent Ledger, Controllability and Experience Compilers, Decision Futures, Executable Operator Model, Takeover Envelope, Takeover Twin, Evidence Judge, Readiness Map, and Autonomy Router. +- PureFlow-owned Flight Recorder, Intent Ledger, Controllability and Experience Compilers, Decision Futures, Executable Operator Model, Takeover Envelope, Takeover Twin, Evidence Judge, Readiness Map, Autonomy Router, and—only if H9 passes—a pure Operator Projection Compiler. This keeps the differentiating layer portable and avoids tying the thesis to a commercial editor fork. A deeper editor fork is justified only if a validated control experience requires unsupported workbench primitives.