Task + Task Loop Write Proposals — Canonical Contract (Phase 2G-d, Step 2G-d-a)

Status: Contract frozen (2G-d-a Thinking, 2026-06-24). Typed facade over the existing Knowtation /proposals lifecycle (SD-4 machinery — not a new write path). No implementation, no routes, no posture flip in this step. Mechanical implementation is 2G-d-b (Auto) on branch feat/phase-2g-d-write-proposals (branch off feat/phase-2g-c-loop-contracts or merged main when available).

Related:

• docs/TASK-STORE-CONTRACT-2G.md — one-time task read store (frozen).
• docs/TASK-LOOP-STORE-CONTRACT-2G-c.md — loop series + instance fields (frozen).
• scooling/docs/TASK-ADAPTER-CONTRACT-2G.md — one-time task consumer writes (frozen shapes).
• scooling/docs/TASK-WRITE-ADAPTER-CONTRACT-2G-d.md — Scooling consumer write boundary.
• docs/FLOW-AUTHORING-WRITEBACK-CONTRACT-7A-L1.md — SD-4 pattern reference.
• docs/TASK-LOOPS-AND-ORCHESTRATOR-PLAN.md — §3.3–§3.4 materialization + completion semantics.
• scooling/docs/CROSS-REPO-COORDINATION.md — SD-2, SD-4.

Scope fence (2G-d-a): propose shapes + scope×role write authority + review-before-write lifecycle

• optimistic concurrency + apply reconciliation rules + seven-tier test matrix + Tier 3 gate checklist only. Not in scope: Hub routes, CLI/MCP wiring, OpenAPI edits (land with routes in 2G-d-b), Scooling live wire, orchestrator dispatch (2G-e), classroom teacher authority (OD-9 defer), RRULE parser (2G-f).

Simple summary

Tasks and recurring task loops change the same safe way notes and Flows already do: you never edit the canonical copy directly. You submit a proposal — "here is the task or loop I want to create, the next occurrence I want to spawn, or the series I want to pause or cancel." A human reviews it; only after approval does Knowtation write to the portable store. Loop create adds a series template. Materialize adds one dated instance task linked back to the series (lazy — usually the next occurrence). Pause stops new instances but leaves existing ones visible. Cancel ends the series and, per the frozen OD-4 default, auto-cancels pending instances with an audit pointer — all in one approved apply. One-time task creates and status changes use the same proposal machinery. Everything stays off until a named Tier 3 authorization flips TASK_WRITES_ENABLED.

Technical summary

Task and task-loop durable writes are a typed facade over /proposals (SD-4), parallel to flow-authoring.mjs and delegation.mjs: validate payload → check scope×role write authority → create proposal with server-stamped proposal_kind + task_meta → existing evaluation/approve/apply. The portable index (hub_flow_store.json tasks[] / task_loops[]) changes only on approve→apply via reconcileApprovedTaskProposal. Optimistic concurrency uses taskst1_ / loopst1_ state ids (FNV-1a over canonical JSON). Materialization enforces (vault, loop_ref, occurrence_key) uniqueness. Cancel applies OD-4 cascade in the same atomic transaction. TASK_WRITES_ENABLED defaults off; Scooling TASK_WRITES_AUTHORIZED stays false until Tier 3.

0. Design decision — SD-4 extension (recorded, not a new write path)

Task and task-loop writes reuse SD-4. task_propose / task_loop_propose / task_instance_materialize validate structured payloads, then create standard proposals with source: "task", server-stamped proposal_kind, and task_meta for apply routing. Review, evaluation, approve, apply, and optimistic-concurrency checks are the same machinery notes and Flows use. The task index and loop index update only on approve→apply — never at propose time.

Rationale: one audited review path; no duplicated approve/apply logic; adapters never write canonical knowledge directly.

1. Surfaces (triple-exposed, identical contract)

All surfaces require TASK_WRITES_ENABLED (Knowtation, default off, §8) and resolve write authority server-side.

All converge on one handler family (lib/task/task-write.mjs):

• handleTaskProposeRequest — one-time task kinds.
• handleTaskLoopProposeRequest — loop create / pause / cancel.
• handleTaskInstanceMaterializeRequest — occurrence spawn.

No surface re-implements write logic — parity proven by deep-equality (§10 tier 2).

1.1 Common request fields

Every propose request includes:

Edit/status proposals on existing records require:

2. Write-authority model (scope × role, server-side, deny-by-default)

Reuses Flow/task read visibility plus a stricter write tier (mirrors FLOW-AUTHORING-WRITEBACK-CONTRACT-7A-L1.md §2):

3. Proposal kinds (server-stamped proposal_kind)

Non-goals (2G-d): task_loop_edit (recurrence/title/flow_id patch) — defer to 2G-f unless Tier 3 explicitly expands scope. Orchestrator graph writes — separate gate (not 2G-d).

4. Request / response shapes

4.1 task_create

{
  "proposal_kind": "task_create",  // ignored — server stamps
  "intent": "Add personal practice goal",
  "task": {
    "task_id": "task_practice_june",
    "kind": "personal",
    "scope": "personal",
    "title": "Daily scale practice",
    "workspace_id": "ws_personal",
    "due_at": "2026-06-30T17:00:00.000Z",
    "assignee_ref": null,
    "assigner_ref": null,
    "artifact_links": []
  }
}

• task_id required; must match TASK_ID_RE; collision in scope ⇒ 409 TASK_LINEAGE_CONFLICT.
• loop_ref / occurrence_key must be absent or null — use task_instance_materialize for loop instances.
• run_ref must be null at create (SD-2 run link is separate Flow run proposal path).

Response — knowtation.task_proposal/v0:

{
  "schema": "knowtation.task_proposal/v0",
  "proposal_id": "…",
  "proposal_kind": "task_create",
  "task_id": "task_practice_june",
  "loop_id": null,
  "base_state_id": "taskst1_…",  // absent-flow sentinel for create
  "scope": "personal",
  "auto_approvable": false,
  "status": "proposed",
  "review_queue": "task-writes"
}

4.2 task_status_update | task_assign | task_artifact_link

Same envelope pattern as §4.1 with task_id, base_state_id (required), and kind-specific patch fields documented in TASK-STORE-CONTRACT-2G.md §1. Status transitions must be valid enum moves; agents cannot auto-complete to done without policy (org may forbid via hub_task_write_policy.json).

4.3 task_loop_create

{
  "intent": "Weekly mentor check-in series",
  "loop": {
    "loop_id": "loop_mentor_w25",
    "kind": "mentor_checkin",
    "scope": "project",
    "title": "Weekly mentor check-in",
    "workspace_id": "ws_mentor",
    "status": "active",
    "recurrence": { "kind": "interval", "every": 1, "unit": "week", "anchor_at": "2026-06-23T09:00:00.000Z" },
    "timezone": "America/Los_Angeles",
    "flow_id": null,
    "boundary_policy": "propose_only",
    "memory_links": [],
    "handoff_refs": [],
    "until_at": null
  }
}

• Validates against TASK-LOOP-STORE-CONTRACT-2G-c.md §1 + recurrence subset (OD-2).
• loop_id collision ⇒ 409 TASK_LOOP_LINEAGE_CONFLICT.
• Initial status must be active (pause/cancel are separate proposal kinds).

4.4 task_loop_pause

{
  "intent": "Pause until summer break",
  "loop_id": "loop_mentor_w25",
  "base_state_id": "loopst1_…"
}

Semantics (plan §3.4):

• Sets loop status: paused.
• Does not cancel existing instance tasks.
• Blocks new materialization while paused (409 TASK_LOOP_NOT_ACTIVE at materialize propose).

4.5 task_loop_cancel

{
  "intent": "Series no longer needed",
  "loop_id": "loop_mentor_w25",
  "base_state_id": "loopst1_…"
}

Semantics (plan §3.4 + OD-4 default):

• Sets loop status: cancelled.
• Same atomic apply: all instance tasks where loop_ref === loop_id and status ∈ { pending, in_progress, blocked } → status: cancelled with skip_reason: series_cancelled (new optional field on task/v0, pointer-only audit).
• Instance tasks already done or cancelled are untouched.
• Apply records cascade_task_ids[] (ids only) on proposal task_meta for audit — no bodies.

4.6 task_instance_materialize

{
  "intent": "Spawn next school-trip occurrence",
  "loop_id": "loop_school_trip",
  "occurrence_key": "2026-W25",
  "occurrence_at": "2026-06-23T09:00:00.000Z",
  "due_at": "2026-06-28T17:00:00.000Z",
  "title_override": null
}

Materialization rules:

1. Uniqueness: (vault, loop_ref, occurrence_key) — duplicate ⇒ 409 TASK_OCCURRENCE_EXISTS.
2. Sets series_status_snapshot to loop status at spawn (active).
3. New task status: pending; run_ref: null until agent pass (SD-2).
4. Does not mutate the loop series row (except updated timestamp optional).
5. Lazy only in v0 — no eager horizon window (OD-3 defer).

Response — knowtation.task_instance_proposal/v0:

{
  "schema": "knowtation.task_instance_proposal/v0",
  "proposal_id": "…",
  "proposal_kind": "task_instance_materialize",
  "loop_id": "loop_school_trip",
  "task_id": "task_school_trip_2026_w25",
  "occurrence_key": "2026-W25",
  "base_state_id": "loopst1_…",
  "scope": "personal",
  "auto_approvable": false,
  "status": "proposed",
  "review_queue": "task-writes"
}

task_id is deterministic: task_<loop_token>_<sanitized_occurrence_key> with max length enforced by TASK_ID_RE (server rejects computed id overflow ⇒ 400 TASK_MATERIALIZE_INVALID).

5. Review-before-write lifecycle

Identical to SD-4 / 7A-L1 §3:

task_propose / task_loop_propose / task_instance_materialize
        │  validate + write-authority + concurrency precheck
        ▼
   POST /proposals  ──►  status: proposed  (source:"task", task_meta, intent)
        │
        ▼
   /proposals/{id}/evaluation  ──►  pass | fail | needs_changes
        │
        ▼
   /proposals/{id}/approve  ──►  base_state_id re-check (409 on conflict)
        │
        ▼
   reconcileApprovedTaskProposal  ──►  tasks[] / task_loops[] ONLY mutation

6. Optimistic concurrency

Materialize proposals include loop base_state_id so concurrent pause/cancel fails closed if loop changed between read and propose.

7. Apply reconciliation (reconcileApprovedTaskProposal)

Proposal body is JSON stored at meta/tasks/proposals/<proposal_id>.json (path convention parallel to delegation meta/delegation/…). task_meta on the proposal record:

{
  "record_kind": "task" | "task_loop" | "task_instance",
  "proposal_kind": "task_loop_create",
  "task_id": "…",
  "loop_id": "…",
  "occurrence_key": "…",
  "cascade_task_ids": ["…"]
}

8. Posture / gating (default off)

Enabling live writes is Tier 3 — see §9 checklist. Do not flip without explicit authorization.

Env double-lock when Tier 3 consumed (Scooling): SCOOLING_TASK_WRITES=enabled + KNOWTATION_HUB_TOKEN + KNOWTATION_HUB_VAULT_ID + compile-time TASK_WRITES_AUTHORIZED=true.

9. Tier 3 gate checklist (operator — consume once per authorization)

Each row must pass before flipping TASK_WRITES_ENABLED (Knowtation) and TASK_WRITES_AUTHORIZED (Scooling). One authorization, one session, consumed when DONE.

Explicit authorization record (operator fills on flip day):

Tier 3 TASK_WRITES — authorized YYYY-MM-DD by <principal>
Repos: knowtation @ <sha>, scooling @ <sha>
Gates flipped: TASK_WRITES_ENABLED=1 (KN), TASK_WRITES_AUTHORIZED=true (SC)
Pre/post curl matrix: docs/CROSS-REPO-COORDINATION.md (if staging push)

10. Error taxonomy

TASK_DRAFT_INVALID · TASK_SCOPE_DENIED · TASK_SCOPE_AMBIGUOUS · unknown_task · unknown_task_loop · TASK_LINEAGE_CONFLICT (409) · TASK_LOOP_LINEAGE_CONFLICT (409) · TASK_OCCURRENCE_EXISTS (409) · TASK_LOOP_NOT_ACTIVE · TASK_MATERIALIZE_INVALID · TASK_WRITES_DISABLED · TASK_CLASSROOM_AUTHORITY_REQUIRED · EVALUATION_REQUIRED (approve, unchanged).

11. Seven-tier test matrix (2G-d-b Auto)

Files: test/task-write-*.test.mjs. No network in unit tests. Run with TASK_WRITES_ENABLED toggled both ways.

Cross-repo I-T-LOOP-02: school-trip loop create (fixture fields) → materialize 2026-W25 → Scooling inert/live adapter read coherence with Knowtation store.

12. Acceptance (2G-d-a)

• [x] Proposal kinds, request/response shapes, write authority, lifecycle, concurrency, apply rules, materialize/pause/cancel semantics, posture, error taxonomy, seven-tier matrix, and Tier 3 checklist frozen here — contract only.
• [x] Ratified against TASK-STORE-CONTRACT-2G.md, TASK-LOOP-STORE-CONTRACT-2G-c.md, SD-4, plan §3.3–§3.4, OD-3/OD-4 defaults.
• [x] 2G-d-b implements on feat/phase-2g-d-write-proposals.
• [x] Posture remains off until Tier 3 checklist §9 consumed.

Non-goals (2G-d)

• task_loop_edit / recurrence patch proposals (2G-f).
• Orchestrator live dispatch (2G-e).
• TASK_LOOP_LIVE_READ_AUTHORIZED flip (separate Tier 3 session).
• Hosted canister task write index.
• Auto-approve task proposals (auto_approvable stays false v0).

Handover notes (for 2G-d-b — Auto)

1. Branch feat/phase-2g-d-write-proposals off latest loop-contract work; read this doc + scooling/docs/TASK-WRITE-ADAPTER-CONTRACT-2G-d.md — no redesign.
2. Implement lib/task/task-write.mjs + taskStateId / loopStateId in lib/note-state-id.mjs (or task-store.mjs exports); wire Hub routes, CLI, MCP, OpenAPI in the same change.
3. Extend proposal apply dispatcher to call reconcileApprovedTaskProposal when source === "task".
4. TASK_WRITES_ENABLED defaults off; seven tiers green before handover regen.
5. Do not flip Scooling TASK_WRITES_AUTHORIZED without Tier 3 §9 checklist + explicit operator authorization.