codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/docs/problem-briefs/03-minimal-agent-context-integrity.md

@@ -0,0 +1,358 @@
+---
+brief_id: WF2-P03
+problem: "Different agent context and late discovery of coordination problems"
+status: hypothesis
+owner: null
+created_at: 2026-08-23
+approved_at: null
+implemented_at: null
+revision: 3
+---
+
+# Brief — Minimal Agent Context Integrity
+
+## 0. Evidence status
+
+The architectural omission is **confirmed**, but the claimed failure cause is **not confirmed**.
+
+Current role context supplies the Task Brief, current Plan when present, selected Knowledge Map
+sources, Task revision, write/read boundaries, commands, and role-specific stop conditions. It does
+not directly supply:
+
+- current Milestone objective and revision;
+- canonical upstream/downstream Task dependencies;
+- relevant sibling Task boundaries;
+- ownership reserved by another Task;
+- unresolved cross-Task prerequisites.
+
+This absence alone does not prove P03. The same late failure may instead mean:
+
+```text
+A. authoritative decomposition was wrong
+B. correct authoritative fact existed but was missing/stale in context
+C. correct fact was supplied but the agent reasoned incorrectly
+D. required fact did not exist in Workflow authority
+E. P01/P02 should have stopped the route before context mattered
+```
+
+P03 solves only B and stale-context variants.
+
+The Signal pre-M3 replay cannot establish B:
+
+- Workflow stopped at a legitimate project-memory human gate before Task materialization;
+- the synthetic Milestone was implemented outside Workflow;
+- one agent retained the full experiment context instead of receiving separate
+  Planner/Worker/Reviewer packets;
+- old active M3 Tasks and replacement decisions were intentionally excluded.
+
+Therefore no authoritative P03 enforcement may be materialized from the replay result alone.
+
+Implementation decision: **NO-GO**. A narrower prompt would be easy to generate, but without a
+confirmed category-B failure and authoritative sources for the projected facts it would only make
+context larger, not demonstrably more correct.
+
+## 1. Problem
+
+An authority-bearing agent decision can be locally valid yet globally inconsistent when a relevant
+coordination fact already known to Workflow is absent or stale in that role's context.
+
+Relevant facts can include:
+
+- Milestone objective;
+- current Task objective and boundary;
+- concrete upstream/downstream dependencies;
+- sibling boundary relevant to the decision;
+- ownership allocated to this or another Task;
+- unresolved prerequisite;
+- known blocker;
+- current authority revisions.
+
+Roles do not need identical prompts or full Milestone history. They need only the current facts
+required for the exact decision.
+
+## 2. Preconditions
+
+P03 cannot become authoritative until the facts it projects are authoritative elsewhere:
+
+- P01-A owns only mechanical Plan-feasibility evidence and does not supply semantic Task boundaries,
+  ownership, prerequisite, output, or admission facts.
+- Deferred P01-B or another approved authority must own those semantic facts before P03 can project
+  them.
+- P04 owns concrete Task dependency edges and predecessor status.
+- Existing Task/Plan/Knowledge authority owns local execution facts.
+- P02 owns Step dependency and Step semantic validity.
+
+P03 must not create substitute ownership, prerequisite, dependency, or Step models when those facts
+do not exist.
+
+If a required fact is absent from Workflow authority, the result is `context-insufficient` or a P01
+decomposition gap—not an invented empty list or implicit permission.
+
+## 3. Proposed solution
+
+If fresh replay validates the hypothesis, extend the current role-specific `ContextEnvelope` with a
+derived coordination projection equivalent to:
+
+```text
+CoordinationContext {
+  milestone {
+    id
+    objective
+    revision
+    planHash
+  }
+
+  task {
+    id
+    objective
+    revision
+    briefHash
+    planHash
+    baseBranch
+    evaluatedBaseHead
+    baseCommit?
+  }
+
+  upstreamDependencies[]
+  downstreamDependencies[]
+  relevantSiblingBoundaries[]
+
+  ownership {
+    owned[]
+    reservedByOthers[]
+    unknown[]
+  }
+
+  unresolvedPrerequisites[]
+  knownBlockers[]
+}
+```
+
+This is a logical projection, not a new authoritative schema object. It is rebuilt from current
+Workflow state and may be discarded at any time.
+
+Before `task start`, `baseCommit` is absent in current Task state. Planning and authorization
+context therefore uses `baseBranch` plus its evaluated HEAD, consistent with P01-A. After start,
+the recorded `baseCommit` may also be projected when the exact role decision requires it.
+
+### 3.1 Decision-specific projection
+
+Planner:
+
+- Milestone objective;
+- current Task boundary;
+- concrete relevant dependencies;
+- sibling ownership that constrains the proposed Plan;
+- unresolved prerequisites.
+
+Worker:
+
+- current Brief, Plan, and Step;
+- satisfied upstream outputs required by that Step;
+- write/ownership boundary;
+- current execution blockers.
+
+Reviewer:
+
+- reviewed authority and evidence;
+- relevant Task/Milestone boundary;
+- dependencies and ownership needed to evaluate findings;
+- no unrelated sibling implementation details.
+
+Coordinator:
+
+- runnable and blocked Task set;
+- unresolved dependency bindings;
+- current revisions and required human gates.
+
+### 3.2 Packet and chat-boundary compatibility
+
+Current Task-chat protocol deliberately excludes sibling Task details, sibling Plans, and
+Coordinator transcript from the TaskContextPacket. P03 must not bypass that isolation by copying
+them into chat text.
+
+If P03 is later approved, coordination facts must be generated by Core as a narrow authoritative
+`ContextEnvelope` projection. `relevantSiblingBoundaries[]` may contain only the normalized
+constraint needed by the current decision, its source authority, and freshness binding—not a
+sibling Brief, Plan, implementation detail, or chat history. The project-local gateway protocol and
+Core envelope schema must be revised together before this projection becomes mandatory.
+
+If the source authority cannot emit such a normalized constraint, P03 reports
+`context-insufficient`; it must not reconstruct one by reading and summarizing sibling prose.
+
+### 3.3 Sufficiency and freshness
+
+```text
+ROLE_CONTEXT_READY =
+  required_authoritative_facts_exist
+  AND required_facts_are_projected
+  AND relevant_bindings_are_current
+  AND no_known_context_conflict
+```
+
+Possible failures:
+
+```text
+context-insufficient
+context-stale
+```
+
+Minimum freshness bindings reuse existing authority:
+
+```text
+taskRevision
+briefHash
+planHash
+baseBranch / evaluatedBaseHead before start
+baseCommit after start when relevant
+milestoneRevision
+milestonePlanHash
+membershipRevision
+```
+
+Only bindings relevant to the role's decision are mandatory. A changed unrelated sibling must not
+invalidate a local decision.
+
+Old context is never repaired in place:
+
+```text
+authority changes -> old packet stale -> discard -> rebuild
+```
+
+### 3.4 Unknown does not mean permitted
+
+Projection must distinguish:
+
+```text
+known empty
+known owned by current Task
+known reserved by another Task
+explicitly unresolved
+not represented by Workflow authority
+```
+
+An empty list cannot silently represent the last two cases.
+
+## 4. Fresh hypothesis validation
+
+Historical active-Milestone recovery and old M3 Task identifiers are excluded from the mandatory
+materialization evidence. The new mandatory test is a fresh, version-pinned, role-separated replay.
+
+### 4.1 Fresh role-separated scenario
+
+From a clean pre-Milestone repository:
+
+1. Run Discovery without importing later active-Milestone state.
+2. Materialize Tasks with authoritative semantic boundary facts from P01-B or another approved
+   source and canonical P04 dependencies.
+3. Build Planner, Worker, and Reviewer packets independently.
+4. Give a Planner a proposal that would enter a sibling's authoritative scope.
+5. Verify that the relevant boundary is present without supplying the sibling's full Plan.
+6. Change a relevant authority revision and verify that the old result cannot authorize a
+   transition.
+7. Change an irrelevant sibling and verify that the local context remains usable.
+
+The replay must classify every detected conflict as A–E.
+
+### 4.2 Required category-B evidence
+
+P03 is supported only if at least one material case proves:
+
+```text
+the fact was authoritative and correct
+AND the role needed it
+AND the old packet omitted or stale-bound it
+AND P01/P02 did not already block the route
+AND the minimal projection prevents the harmful decision
+```
+
+Without this evidence, P03 remains deferred.
+
+The replay must also identify the exact pre-existing authority record and field from which every
+projected boundary, ownership fact, prerequisite, and blocker is derived. A fact recoverable only
+from agent reasoning, Coordinator chat, or a sibling Plan does not satisfy category B.
+
+### 4.3 Historical replay
+
+Historical completed Tasks may be used as additional regression evidence, but no specific old
+T07/T09/T10 topology is mandatory. Historical replay must not import active status, replacement
+authority, or later decisions into fresh Discovery.
+
+### 4.4 Successful-task controls
+
+Verify:
+
+- no unrelated sibling internals become mandatory;
+- no new agent call is introduced;
+- context stays within current budget;
+- previously successful local Tasks receive no systematic blockers;
+- repeated packet derivation is deterministic.
+
+## 5. Dependencies and conflicts
+
+- P03 depends on P01 boundary/prerequisite authority and P04 Task dependencies.
+- P01-A alone does not satisfy the first dependency; P03 requires deferred P01-B or an equivalent
+  approved semantic authority.
+- P03 may use P02 Step facts but cannot evaluate Step validity.
+- P03 must not duplicate Plan feasibility or semantic admission.
+- Full sibling Briefs/Plans, Coordinator chat history, and a global Context Graph are unnecessary.
+- Context freshness must reuse existing revisions/hashes rather than introduce a new credential or
+  evidence lifecycle.
+- Mandatory sibling-context projection would conflict with the current Task-chat isolation rule;
+  Core envelope and gateway protocol changes must be one reviewed contract change.
+
+## 6. Design approval gate
+
+P03 remains `NO-GO`. It may move from `hypothesis` to `approved` only when:
+
+1. Fresh role-separated replay demonstrates at least one category-B or stale-context failure.
+2. P01/P02 do not already fully prevent that failure.
+3. Every projected fact names an existing authoritative source and field.
+4. The minimal projection exposes the fact before the harmful decision.
+5. The Core-envelope and Task-chat protocol changes agree on the exact permitted sibling-boundary
+   projection.
+6. Missing authority is represented as insufficient/unknown, never permitted.
+7. Relevant and irrelevant freshness bindings are defined without a new credential lifecycle.
+8. Successful-task controls show no systematic blocker or material context-budget regression.
+
+## 7. Implementation acceptance
+
+P03 may move from `approved` to `implemented` only when:
+
+1. Relevant authority changes invalidate the old result.
+2. Irrelevant authority changes do not create false staleness.
+3. Different roles receive consistent values for the same fact.
+4. Packets are derived, disposable, deterministic, and contain no sibling Plan or chat transcript.
+5. Missing authority fails closed as `context-insufficient`.
+6. No new mandatory agent call or lifecycle stage is introduced.
+7. No global Context Graph, Contract Registry, ownership model, dependency model, or context
+   credential lifecycle is introduced.
+8. Fresh role-separated E2E and successful-task replay pass without systematic false blockers.
+
+## 8. Non-goals
+
+- fixing incorrect authoritative decomposition;
+- creating missing Task dependencies or ownership authority;
+- preventing reasoning errors when correct context was supplied;
+- full Milestone history or sibling Plans in every packet;
+- Coordinator/chat transcript transmission;
+- Plan feasibility or Step semantic validation;
+- replacement rewiring;
+- mandatory Design Review;
+- global knowledge/RAG/context graph.
+
+## 9. Decision log
+
+- 2026-08-23 — Revision 1 created as `hypothesis`.
+- 2026-08-24 — Current role-context omission confirmed by source inspection.
+- 2026-08-24 — Signal replay found insufficient evidence to attribute a material failure to missing
+  or stale role context.
+- 2026-08-24 — Mandatory old T07/T09/T10 replay removed; fresh role-separated replay is now the
+  approval gate.
+- 2026-08-24 — P01/P04 authority made an explicit prerequisite for P03.
+- 2026-08-24 — Revision 3 clarified that P01-A does not supply semantic boundary/ownership
+  authority, corrected the pre-start base binding, and made Core-envelope/gateway chat isolation a
+  joint compatibility gate.
+- 2026-08-24 — P03 remains `NO-GO` until category-B evidence names an exact pre-existing authority
+  source and proves that the minimal projection prevents a material error.
+- 2026-08-24 — Status intentionally remains `hypothesis`; category-B evidence is still absent.