Skip to content

Commit 9622a9a

Browse files
author
Douglas Jones
committed
Track 3 T3-1 through T3-5: v2.0 roadmap update + Sable audit
T3-1: findings collected from T1-6 and T2-8 T3-2: docs/ROADMAP.md rewritten — evidence-driven, four v2.0 priorities T3-3: .kiro/specs/v2-language/ opened — requirements.md + tasks.md T3-4: dispatch pair filed T3-5: Sable audit — 4 findings, 2 P2s applied immediately v2.0 priorities (evidence-justified): P1: RPC API (Program 5 universal failure) P2: Static bind-before-when detection (Claude T1-4) P3: from-import in Rust parser (all three models needed CODIFIDE_RUNTIME=python) P3: Manifest docs field (AUD-T2-03) Deferred with reasons: effect inference, time-indexed types, editor integration, structural diff (no adoption evidence); parallel runtime beyond Shape A (blocked on RPC API) 289 tests passing, 0 regressions.
1 parent ab81926 commit 9622a9a

7 files changed

Lines changed: 519 additions & 45 deletions

File tree

‎.kiro/specs/v2-language/requirements.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Codifide v2.0 Language Work — Requirements
2+
3+
## Overview
4+
5+
v2.0 language work is driven by the Agent Adoption Initiative findings.
6+
Every requirement here is justified by at least one finding from Track 1
7+
(case studies) or Track 2 (infrastructure audit). Items without adoption
8+
evidence are not in scope.
9+
10+
Evidence base: `dispatches/2026-05-13-track1-summary.*`,
11+
`dispatches/2026-05-13-track2-sable-audit.md`,
12+
`dispatches/2026-05-13-track2-sable-reaudit.*`
13+
14+
---
15+
16+
## REQ-V2-1: RPC API
17+
18+
**Priority:** P1
19+
20+
**Evidence:** Program 5 (content-addressed composition) was the universal
21+
failure point across all three Track 1 sessions (T1-2, T1-3, T1-4). Every
22+
agent had to manually manage the store CLI, set `CODIFIDE_RUNTIME=python`,
23+
and write `from`-import syntax. The friction is in the composition layer,
24+
not the language semantics.
25+
26+
**Requirement:** A network interface (HTTP or gRPC) that accepts canonical
27+
CBOR, stores it, returns its hash, and resolves imports. Agents speak
28+
canonical form directly without surface syntax or CLI.
29+
30+
**Acceptance criteria:**
31+
- An agent can publish a symbol via HTTP POST and receive its SHA-256 hash
32+
- An agent can resolve an import by hash via HTTP GET
33+
- An agent can complete Program 5 of `docs/AGENT_TASK_SPEC.md` using only
34+
HTTP requests — no CLI, no `CODIFIDE_RUNTIME=python`
35+
- The API accepts canonical CBOR (primary) and canonical JSON (secondary)
36+
- The API is documented in `docs/RPC_API.md`
37+
38+
---
39+
40+
## REQ-V2-2: Static bind-before-when detection
41+
42+
**Priority:** P2
43+
44+
**Evidence:** Claude (T1-4) hit `unbound name: 'label'` when writing a `cand`
45+
block with a bind followed by a `when` guard. The pattern is syntactically
46+
accepted by the parser and fails at runtime with a misleading error. GPT-4o
47+
and Gemini avoided it by accident. Any agent reaching for idiomatic
48+
multi-branch dispatch will hit it.
49+
50+
**Requirement:** The parser detects bind-before-when statically and raises
51+
`ParseError` with a message explaining guard-before-body execution order.
52+
53+
**Acceptance criteria:**
54+
- `cand label <- f() when eq(label, x) "y"` raises `ParseError` (not
55+
`unbound name` at runtime)
56+
- Error message names the fix: move bind into body, use `if/then/else`
57+
- Existing programs with correct bind placement are unaffected
58+
- The runtime hint added in post-T1-4 fixes can be removed once the parser
59+
catches it statically
60+
61+
---
62+
63+
## REQ-V2-3: `from`-import in Rust parser
64+
65+
**Priority:** P3
66+
67+
**Evidence:** All three Track 1 agents needed `CODIFIDE_RUNTIME=python` for
68+
Program 5. The Rust parser does not support `from <hash> import name` syntax.
69+
This means the default runtime cannot do content-addressed composition.
70+
71+
**Requirement:** Implement `from <hash> import name, name` in the Rust parser
72+
and interpreter, with store resolution.
73+
74+
**Acceptance criteria:**
75+
- Program 5 of `docs/AGENT_TASK_SPEC.md` runs without `CODIFIDE_RUNTIME=python`
76+
- Byte-level conformance with Python runtime on all existing test programs
77+
- The `CODIFIDE_RUNTIME=python` note in `docs/AGENT_QUICKREF.md` can be removed
78+
79+
---
80+
81+
## REQ-V2-4: Manifest `docs` field
82+
83+
**Priority:** P3
84+
85+
**Evidence:** AUD-T2-03 (Track 2 Sable audit). An agent fetching
86+
`codifide.com/capability.json` cannot discover the cookbook, quickref, or
87+
`FOR_AGENTS.md` from the manifest alone.
88+
89+
**Requirement:** Add a `docs` field to the capability manifest schema with
90+
stable URLs for key agent-facing documents.
91+
92+
**Acceptance criteria:**
93+
- `python3 -m codifide capability | jq .docs` returns URLs for
94+
`FOR_AGENTS.md`, `AGENT_COOKBOOK.md`, and `AGENT_QUICKREF.md`
95+
- The manifest drift test catches changes to the `docs` field
96+
- `docs/CAPABILITY.md` documents the `docs` field schema
97+
98+
---
99+
100+
## Out of scope for v2.0
101+
102+
- Effect inference — no adoption evidence
103+
- Time-indexed types — no adoption evidence
104+
- Editor integration — no adoption evidence
105+
- Structural diff and merge — no adoption evidence
106+
- Hosted runtime / cloud service — v3.0 territory
107+
- Certification program — v3.0 territory
108+
109+
---
110+
111+
*Spec version 1.0 — May 2026*
112+
*Author: Douglas Jones + Claude*
113+
*Governed by: GOVERNANCE.md*

‎.kiro/specs/v2-language/tasks.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Codifide v2.0 Language Work — Tasks
2+
3+
## REQ-V2-1: RPC API (P1)
4+
5+
- [ ] **V2-1-1** Write `docs/RPC_API.md` — spec for the HTTP/gRPC interface
6+
- [ ] **V2-1-2** Design dispatch: endpoint shape, auth model, error responses
7+
- [ ] **V2-1-3** Implement POST `/symbols` — accept canonical CBOR, store, return hash
8+
- [ ] **V2-1-4** Implement GET `/symbols/<hash>` — return canonical CBOR by hash
9+
- [ ] **V2-1-5** Implement GET `/symbols/<hash>/imports` — resolve import graph
10+
- [ ] **V2-1-6** Test: agent completes Program 5 via HTTP only
11+
- [ ] **V2-1-7** File Quill/Glyph dispatch for RPC API completion
12+
- [ ] **V2-1-8** Sable audit of RPC API surface
13+
14+
## REQ-V2-2: Static bind-before-when detection (P2)
15+
16+
- [ ] **V2-2-1** Add scope tracking to the Python parser
17+
- [ ] **V2-2-2** Raise `ParseError` for bind-before-when with clear message
18+
- [ ] **V2-2-3** Add regression tests
19+
- [ ] **V2-2-4** Remove runtime hint only after BOTH Python (V2-2-2) and Rust (V2-2-5) parsers catch bind-before-when statically
20+
- [ ] **V2-2-5** Port to Rust parser
21+
- [ ] **V2-2-6** File Quill/Glyph dispatch
22+
23+
## REQ-V2-3: `from`-import in Rust parser (P3)
24+
25+
- [ ] **V2-3-1** Implement `from <hash> import name` in Rust lexer + parser
26+
- [ ] **V2-3-2** Implement store resolution in Rust interpreter
27+
- [ ] **V2-3-3** Conformance tests: byte-identical output with Python runtime
28+
- [ ] **V2-3-4** Remove `CODIFIDE_RUNTIME=python` note from AGENT_QUICKREF
29+
- [ ] **V2-3-5** File Quill/Glyph dispatch
30+
31+
## REQ-V2-4: Manifest `docs` field (P3)
32+
33+
- [ ] **V2-4-1** Add `docs` field to `generate_capability()` in `capability.py`
34+
- [ ] **V2-4-2** Update `docs/CAPABILITY.md` schema documentation
35+
- [ ] **V2-4-3** Regenerate `docs/capability-0.1.json`
36+
- [ ] **V2-4-4** Update manifest endpoint on publicsite
37+
- [ ] **V2-4-5** File Quill/Glyph dispatch
38+
39+
## Session Close
40+
41+
- [ ] **SC-1** `python3 -m codifide dispatch-check` exits 0
42+
- [ ] **SC-2** All open Quill readouts have paired Glyph YAMLs
43+
- [ ] **SC-3** session-close.readout.md and session-close.yaml filed

‎dispatches/2026-05-13-t3-roadmap-audit.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Sable Audit — v2.0 Roadmap
2+
3+
**Date:** 2026-05-13
4+
**Persona:** Sable
5+
**Scope:** `docs/ROADMAP.md`, `.kiro/specs/v2-language/`
6+
**Initiative:** Agent Adoption — Track 3, Task T3-5
7+
8+
---
9+
10+
## Audit scope
11+
12+
The v2.0 roadmap and the v2-language spec were written in one pass based on
13+
adoption findings. This audit checks internal consistency, evidence claims,
14+
and whether the acceptance criteria are testable.
15+
16+
---
17+
18+
## Findings
19+
20+
### AUD-T3-01 (P2) — REQ-V2-1 acceptance criterion is not independently verifiable
21+
22+
**What:** The RPC API acceptance criterion says "an agent can complete Program
23+
5 of `docs/AGENT_TASK_SPEC.md` using only HTTP requests." But
24+
`AGENT_TASK_SPEC.md` was written for CLI-based sessions. It does not describe
25+
an HTTP-based workflow. An agent following the spec cannot verify the RPC API
26+
criterion without a separate HTTP task spec.
27+
28+
**Fix:** When V2-1-1 (`docs/RPC_API.md`) is written, add an HTTP-based
29+
variant of Program 5 to the task spec, or write a separate
30+
`docs/AGENT_TASK_SPEC_RPC.md`. The acceptance criterion should reference a
31+
concrete, runnable test.
32+
33+
**Severity:** P2 — the criterion is correct in intent but not independently
34+
verifiable as written.
35+
36+
---
37+
38+
### AUD-T3-02 (P2) — REQ-V2-2 defers removal of the runtime hint
39+
40+
**What:** The tasks list says "remove runtime hint (now redundant with static
41+
detection)" as V2-2-4. But the runtime hint was added specifically because
42+
the parser doesn't catch bind-before-when. If V2-2 ships, the hint becomes
43+
redundant. If V2-2 is deferred or partially shipped (Python parser only, not
44+
Rust), the hint is still needed for the Rust runtime.
45+
46+
**Fix:** V2-2-4 should be conditional: remove the runtime hint only after
47+
both Python and Rust parsers catch bind-before-when statically (V2-2-2 and
48+
V2-2-5 both complete). The tasks list should reflect this dependency.
49+
50+
**Severity:** P2 — removing the hint prematurely would regress the Rust
51+
runtime user experience.
52+
53+
---
54+
55+
### AUD-T3-03 (P3) — "Deferred" section mixes two categories
56+
57+
**What:** The roadmap's deferred section lists items with "no adoption
58+
evidence" alongside "graph-native parallel runtime (beyond v2.0 Shape A)"
59+
which has a different reason — it's deferred until the RPC API is in place,
60+
not because of missing evidence. These are different kinds of deferrals.
61+
62+
**Fix:** Split the deferred section into two: "No adoption evidence" and
63+
"Blocked on other v2.0 work." The distinction matters for prioritization in
64+
future sessions.
65+
66+
**Severity:** P3 — cosmetic, but the distinction is real.
67+
68+
---
69+
70+
### AUD-T3-04 (P3) — v2.0 spec has no design document
71+
72+
**What:** `.kiro/specs/v2-language/` has `requirements.md` and `tasks.md`
73+
but no `design.md`. The RPC API in particular needs a design dispatch before
74+
implementation begins — endpoint shape, auth model, error responses, and
75+
whether it's a separate service or a CLI extension are all open questions.
76+
77+
**Fix:** V2-1-2 (design dispatch) is already in the tasks list. This finding
78+
confirms it should be the first task executed, not deferred.
79+
80+
**Severity:** P3 — the spec is incomplete but the gap is acknowledged.
81+
82+
---
83+
84+
## What I did not test
85+
86+
- Whether the four v2.0 acceptance criteria are achievable with the current
87+
codebase as a starting point. No implementation work was probed.
88+
- Whether the Rust parser's architecture supports scope tracking for
89+
bind-before-when detection without a major refactor.
90+
- Whether the RPC API design (separate service vs CLI extension) has
91+
implications for the content-addressed store's concurrency model.
92+
93+
---
94+
95+
## Overall assessment
96+
97+
The roadmap is internally consistent and evidence-justified. The four
98+
priorities are the right four. The deferred items are correctly deferred.
99+
The two P2 findings are fixable in the task list without changing the
100+
requirements. The roadmap is ready to execute against.

‎dispatches/2026-05-13-t3-roadmap-update.readout.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Track 3 — v2.0 Roadmap Update
2+
3+
**Date:** 2026-05-13
4+
**Persona:** Quill
5+
**Initiative:** Agent Adoption — Track 3, Tasks T3-1 through T3-4
6+
7+
---
8+
9+
## What happened
10+
11+
The v2.0 roadmap has been rewritten from scratch based on adoption evidence.
12+
The old roadmap was written before any real agent adoption data existed. The
13+
new one is justified item by item.
14+
15+
## What changed
16+
17+
**`docs/ROADMAP.md`** — complete rewrite:
18+
- Shipped section: v1.0, v2.0 Shape A, and Agent Adoption Initiative all
19+
documented accurately
20+
- v2.0 priorities: four items, each with evidence citation and acceptance
21+
criterion
22+
- Deferred section: five items from the old roadmap explicitly deferred with
23+
reasons — no adoption evidence for any of them
24+
- v3.0 territory: Moltbook integration, hosted runtime, certification
25+
26+
**`.kiro/specs/v2-language/`** — new spec opened:
27+
- `requirements.md`: four requirements, each justified by adoption findings
28+
- `tasks.md`: implementation tasks for each requirement
29+
30+
## The four v2.0 priorities
31+
32+
**P1 — RPC API.** The composition story is broken without it. Every agent
33+
hit Program 5 friction. The fix is not more documentation — it's removing
34+
the CLI layer entirely for agent-to-agent composition.
35+
36+
**P2 — Static bind-before-when detection.** One of three models hit it.
37+
The other two avoided it by accident. The parser should catch it, not the
38+
runtime.
39+
40+
**P3 — `from`-import in Rust parser.** The default runtime can't do
41+
content-addressed composition. That's a significant gap for the language's
42+
core value proposition.
43+
44+
**P3 — Manifest `docs` field.** Discoverability gap. An agent with only
45+
the manifest can't find the cookbook.
46+
47+
## What was explicitly deferred
48+
49+
Effect inference, time-indexed types, editor integration, structural diff,
50+
graph-native parallel runtime (beyond what shipped in v2.0 Shape A). None
51+
of these have adoption evidence. The old roadmap listed them as priorities;
52+
the new one doesn't.
53+
54+
## Assessment
55+
56+
The roadmap is now honest. It reflects what agents actually need, not what
57+
was planned before any agent used the language. The RPC API is the right
58+
P1 — it's the only item that would have prevented a failure across all three
59+
Track 1 sessions.
60+
61+
What I'm not yet sure of: whether the RPC API should be a separate service
62+
or an extension of the existing CLI. The design dispatch (V2-1-2) will
63+
settle that.

‎dispatches/2026-05-13-t3-roadmap-update.yaml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
dispatch:
2+
version: "1.0"
3+
date: "2026-05-13"
4+
persona: Glyph
5+
subject: "Track 3 — v2.0 roadmap update driven by adoption evidence"
6+
initiative: agent-adoption
7+
track: "3"
8+
tasks: [T3-1, T3-2, T3-3, T3-4]
9+
capability_hash: "sha256:713d6f6b3a6cfb747cec3bfba0f25331c61b0052bdd166523c175daa2c1f6756"
10+
artifacts:
11+
- "docs/ROADMAP.md (complete rewrite)"
12+
- ".kiro/specs/v2-language/requirements.md"
13+
- ".kiro/specs/v2-language/tasks.md"
14+
v2_priorities:
15+
- id: REQ-V2-1
16+
priority: P1
17+
name: "RPC API"
18+
evidence: "Program 5 universal failure — all three Track 1 models"
19+
- id: REQ-V2-2
20+
priority: P2
21+
name: "Static bind-before-when detection"
22+
evidence: "Claude T1-4 hit it; GPT-4o and Gemini avoided by accident"
23+
- id: REQ-V2-3
24+
priority: P3
25+
name: "from-import in Rust parser"
26+
evidence: "All three models needed CODIFIDE_RUNTIME=python for Program 5"
27+
- id: REQ-V2-4
28+
priority: P3
29+
name: "Manifest docs field"
30+
evidence: "AUD-T2-03 — manifest doesn't point to cookbook or quickref"
31+
deferred_with_reason:
32+
- item: "Effect inference"
33+
reason: "No adoption evidence — effects are well-understood by all models"
34+
- item: "Time-indexed types"
35+
reason: "No adoption evidence — no agent attempted time-dependent programs"
36+
- item: "Editor integration"
37+
reason: "No adoption evidence — manifest and store are the right agent interfaces"
38+
- item: "Structural diff and merge"
39+
reason: "No adoption evidence"
40+
- item: "Graph-native parallel runtime (beyond v2.0 Shape A)"
41+
reason: "Deferred until RPC API is in place"
42+
unknowns:
43+
- question: "Should RPC API be a separate service or CLI extension?"
44+
how_to_resolve: "Design dispatch V2-1-2"

‎dispatches/INDEX.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ Filename convention:
2727
| `t2-4-t2-5-t2-6-quickstart` | T2-4+T2-5+T2-6 — feedback template and agent-quickstart CLI | [md](./2026-05-13-t2-4-t2-5-t2-6-quickstart.readout.md) | [yaml](./2026-05-13-t2-4-t2-5-t2-6-quickstart.yaml) | |
2828
| `t2-7-track2-complete` | Track 2 complete — adoption infrastructure shipped | [md](./2026-05-13-t2-7-track2-complete.readout.md) | [yaml](./2026-05-13-t2-7-track2-complete.yaml) | |
2929
| `t2-9-manifest-note-field` | T2-9 — capability manifest note field added; is_bottom() caveat live | [md](./2026-05-13-t2-9-manifest-note-field.readout.md) | [yaml](./2026-05-13-t2-9-manifest-note-field.yaml) | |
30+
| `t3-roadmap` | | | | [md](./2026-05-13-t3-roadmap-audit.md) |
31+
| `t3-roadmap-update` | Track 3 — v2.0 roadmap update driven by adoption evidence | [md](./2026-05-13-t3-roadmap-update.readout.md) | [yaml](./2026-05-13-t3-roadmap-update.yaml) | |
3032
| `track1-sable` | | | | [md](./2026-05-13-track1-sable-audit.md) |
3133
| `track1-sable-post` | Track 1 Sable audit post-resolution — T1-6 | [md](./2026-05-13-track1-sable-post.readout.md) | [yaml](./2026-05-13-track1-sable-post.yaml) | |
3234
| `track1-summary` | Track 1 case study summary — agent adoption initiative gate dispatch | [md](./2026-05-13-track1-summary.readout.md) | [yaml](./2026-05-13-track1-summary.yaml) | |

0 commit comments

Comments
 (0)