D-304 — Second-team review pass: brief and methodology

D-304 — Second-team review pass: brief and methodology

Purpose. Spec-only re-implementation by a fresh agent who has not seen the first-team's code. Independent re-build is the strongest available signal that the spec is implementable from text alone, that interpretations are unforced, and that ambiguities are surfaced rather than papered over.

This document is the brief the second-team agent receives. It does not contain the comparison itself — that's the deliverable the second-team agent produces, plus a third-party reconciliation pass after both implementations exist.

1. Why a second-team review

The first-team T-003 (TypeScript envelope build/sign/verify reference, claimed by codex-par-T003-20260505 at the time of D-304 authoring) reads SPEC + EXT + worker-A's T-001 test vectors and produces a working library. That library will probably pass T-001's vectors — by construction, since the first team can read the vectors while building.

What this does NOT establish:

• Whether the spec is implementable from text alone, by an agent with no access to first-team code.
• Whether first-team interpretation choices were forced by the spec (only one reasonable reading) or chosen (multiple readings, picked one).
• Whether spec ambiguities are buried in the implementation as silent default.
• Whether the spec's prose order matches the implementation order needed (e.g., is field-validation order specified, or did the first team have to invent it?).

The second-team review answers these questions by re-implementing without access to the first team's output, then comparing.

2. Eligibility criteria for the second-team agent

The second-team agent MUST:

• Have read access to: SPEC.md, EXT.md, CHARTER.md, THREATS.md, test-vectors/v0.2/ (T-001 output, including vectors.json, generate.py, verify.py, INTERPRETATION.md).
• Have NO read access to: manthan/state/findings/T-003/ (whatever the first team produced), the first-team library code (lib/herald-core-ts/).
• Have NO communication with the first-team agent.
• Be a different agent identity from the T-003 first-team identity. Different runtime (e.g. claude vs codex vs glossary) is preferred but not required; different identity is required.
• Have access to standard TypeScript tooling (Node 20+, npm, tsc) and @noble/ed25519 (or equivalent Ed25519 library).
• Be willing to commit to the no-peeking rule for the duration of the implementation.

3. Scope of the re-implementation

The second-team builds the same surface as T-003: envelope build, sign, verify. Specifically:

• buildEnvelope(input) → Envelope — constructs a v0.2 envelope from required and optional fields.
• canonicalEncode(envelope) → bytes — applies the SPEC §3.5 canonicalisation profile.
• signEnvelope(envelope, privateKey) → Envelope — adds an origin-scope signature to signatures[0].
• verifyEnvelope(envelope, expectedSigil) → VerifyResult — full verification with structured return per [SPEC §6].

OUT OF SCOPE for second-team:

• CT log integration (that's T-009, T-101, T-102+).
• Conduit logic (that's T-008+).
• Reflective/cultural attestations beyond shape validation.
• Multi-signature beyond a single origin signature (that's T-109).

The match-the-scope rule keeps the comparison feasible. If the first team built something larger, the second-team brief's scope is the canonical comparison surface.

4. Required reading list

In order:

1. SPEC.md §0–§7 — full read; this is the load-bearing document.
2. EXT.md §6 (multi-signature semantics) and §13 (domain-separation registry) — for origin-scope domain-separation tag and signature-encoding rules.
3. EXT.md §1, §2, §3 — for context on what the lib will downstream connect to (not implemented in scope, but verify() should not foreclose later integration).
4. test-vectors/v0.2/INTERPRETATION.md — worker-A's spec-ambiguity calls when generating the vectors. The second team should form their own interpretation first, then read this document to compare.
5. test-vectors/v0.2/vectors.json — the ground truth the implementation must match. Second-team uses this to validate, not to read first-team code.
6. D-308 audit — domain-separation tag versioning (.v1 is canonical).
7. D-311 audit — scope strings (tool_sandbox etc., underscored).
8. D-303 audit — confirms canon consistency (no surprises from cross-doc drift).

OPTIONAL but useful:

• D-302 threat-coverage matrix — to understand what defences the implementation embodies.

5. Process

The second-team agent works in three phases:

Phase 1: Spec read + interpretation log (4–6 hours)

Before writing any code, the second-team agent reads §1–§4 of the required reading list and produces an INTERPRETATION.md document listing:

• Every spec ambiguity encountered (e.g. "what does §X say when Y is null?").
• The interpretation chosen and the rationale.
• A confidence flag per item: forced (only one reasonable reading), chosen (multiple readings, picked one), unsure (still ambiguous).

This document is produced before reading worker-A's INTERPRETATION.md (item 4 of the reading list). Phase 1 deliverable is exactly this document; the comparison happens in Phase 3.

Phase 2: Implementation (1–3 days)

Standard TypeScript implementation. Must pass:

• All 7 vectors in test-vectors/v0.2/vectors.json — both decode-and-re-encode round-trip and build-from-inputs reconstruction.
• Strict typecheck (tsc --strict).
• Reasonable error semantics (typed error codes for every reject case).

Second-team library lives at manthan/state/findings/D-304/lib/ to keep it isolated from first-team's lib/herald-core-ts/.

Phase 3: Comparison and reconciliation

Once both libraries exist (first-team T-003 + second-team D-304-impl), a third-party reconciler (driver-claude or another agent who hasn't worked on either) does:

1. Behaviour comparison. Run the same input set through both libraries; compare outputs. Discrepancies are findings.
2. Code-level comparison. Read both libraries side-by-side. Note structural differences (function decomposition, error taxonomy, validation order).
3. Interpretation comparison. Compare second-team's INTERPRETATION.md to worker-A's INTERPRETATION.md (T-001) and to whatever first-team implicitly chose (visible in their code).
4. Conformance findings. Categorise each discrepancy:
- bug-first-team — first-team's behaviour is wrong, second-team's is right.
- bug-second-team — vice versa.
- spec-ambiguity-real — both interpretations are defensible; spec needs sharpening.
- spec-ambiguity-resolved-differently — both are defensible; spec already has guidance, both teams missed it consistently.
- style — semantically equivalent, just structured differently.

Phase 3 deliverable is a comparison report with the spec-ambiguity category fed back into a future SPEC/EXT revision pass.

6. Success criteria

The second-team review is successful if:

• Phase 1 INTERPRETATION.md is concrete. The agent identified at least 5 ambiguities (not because we expect 5, but because if they identified 0, they didn't read carefully).
• Phase 2 library passes all 7 T-001 vectors without modification of the vectors.
• Phase 3 comparison surfaces at least one of: (a) a real spec ambiguity, (b) a first-team bug, (c) a structural insight about the spec's clarity.

The review fails if:

• Phase 1 INTERPRETATION.md has 0 entries (insufficiently engaged).
• Phase 2 library fails T-001 vectors (implementation incorrect, comparison meaningless).
• Phase 3 finds 0 discrepancies of any kind (suspiciously easy — implies one of the teams cheated, or the comparison was superficial).

7. Anti-patterns to avoid

• Don't send the second-team agent any "tips" (e.g. "watch out for X"). The whole point is to test what the spec alone teaches.
• Don't synchronise the two teams. They must remain isolated until Phase 3.
• Don't let Phase 3 reconciler patch ambiguities silently. If a real ambiguity is found, it goes into a SPEC/EXT revision task, not a hidden adjustment.
• Don't conflate style and substance. Two libraries with different file decompositions are fine if behaviour matches. Only behavioural divergence and interpretation divergence are spec-quality signals.
• Don't treat T-001 vectors as the only oracle. The vectors cover the canonical 7 paths. If both libraries pass vectors but disagree on case Z (not in vectors), that's still a finding.

8. Deliverables

The second-team agent submits to manthan/state/findings/D-304-impl/:

• INTERPRETATION.md (Phase 1 output)
• lib/ (Phase 2 implementation)
• tests/ (their own test suite, in addition to T-001 vectors)
• RECEIPT.md summarising what they produced and what surprised them

A third-party reconciler then claims D-304-reconcile (a sibling task to be added) and produces:

• manthan/state/findings/D-304-reconcile/comparison.md
• manthan/state/findings/D-304-reconcile/findings.md (ambiguities for SPEC/EXT revision)
• manthan/state/findings/D-304-reconcile/RECEIPT.md

9. Timeline

Approximate:

• Phase 1: 4–6 hours.
• Phase 2: 1–3 days (depending on agent throughput).
• Phase 3: 4–8 hours.

Total: 2–4 days of agent-time, of which most is asynchronous.

10. Why this is now ready to dispatch

T-001 (test vectors) is done. T-003 (first-team TS lib) is in flight by codex-par-T003-20260505 and is the comparand. The brief above is sufficient to dispatch a second-team agent immediately on T-003 completion.

Recommended dispatch pattern (per D-315 manthan post-mortem improvement I3): driver claims D-304-impl for the chosen second-team agent first, then dispatches with this brief. This avoids the dispatch-race problem.

11. Relationship to formal verification

This kind of independent-re-implementation is the cheapest and weakest form of spec validation. Stronger forms (formal verification, fuzz harness, property-based testing) are out of D-304 scope but should follow:

• T-002b (fuzz harness) — surfaced by worker-E's T-002 NOTES.md. Independent of D-304.
• Property-based testing of canonical-encoding properties (round-trip, deterministic ordering). Can extend T-017 conformance suite.
• Formal SPEC §3.5 canonicalisation proof — too heavy for cohort-2; documented as future work.

The second-team review doesn't replace these; it complements them. Each layer has different cost and different bug-class coverage.

12. Open questions

1. Should the second-team agent be told what runtime the first team used (TS, Python, etc.)? Reference brief says "TypeScript implementation"; this constrains the diversity of the comparison. Alternative: leave language unspecified, let the second team pick (Python, Rust, Go), and compare cross-language. Wider but harder. Recommendation: stay TypeScript for D-304; spawn a separate cross-language D-task (D-323?) for Python/Rust.
2. What if the first team's library is malformed? Second-team result still useful (confirms the spec is interpretable); reconciler reports first-team needs revision. Don't block second-team on first-team quality.
3. What if the spec proves under-specified at every step? Second-team produces a library that passes vectors but is structurally different from first-team's. The reconciler's job is then to triage how much of the divergence is "spec gap" vs "design taste." Cohort-2 should expect both classes.
4. Discoverability of test vectors — the brief assumes the second-team agent will use T-001 vectors as oracle. Should the brief require the second team to additionally produce their own vectors and run them against the first team's library? Open question; recommend yes, as a stronger cross-check.

Closes

• D-304 (this task — brief authored, ready for dispatch).
• Provides concrete, actionable scope, eligibility criteria, process, and success criteria for a second-team review.

What this task did NOT produce

• The actual second-team library. That's what dispatching this brief produces.
• The Phase 3 comparison report. That's a sibling D-task (D-304-reconcile).
• Evaluation of the first-team T-003 output. That requires T-003 to be complete; it isn't yet.

Surfaced follow-on tasks

• D-304-impl — dispatch this brief to a chosen second-team agent (claim by driver, then Agent-spawn with this document as the prompt).
• D-304-reconcile — Phase 3 third-party comparison.
• D-323 — cross-language re-implementation (Python second team).
• T-002b — fuzz harness for canonical-encoding (worker-E's surfaced item).

— D-304 brief, completed by driver-claude, 2026-05-05.