Session Handoff — 2026-05-07-a

Trigger: post-#1764 truth-sync (sync PR opened from docs/sync-actioncard-contract-1764; merge commit recorded after merge). Filename follows docs/dev/HANDOFF_TEMPLATE.md Usage Notes (handoff-YYYY-MM-DD-b.md suffix convention; -a is the second handoff on 2026-05-07 after handoff-2026-05-07.md). Two handoffs ship on 2026-05-07 because two distinct landings happened: the opaque receipt storage stack (#1755/#1756/#1757/#1758/#1759 → captured by #1762's handoff) and the May-7 close-out cycle (#1761/#1762/#1763/#1764 → captured here).

Session Goal

Close ICN #1713 by publishing the generic ActionCard contract surface for institution packages, then truth-sync the May-7 close-out cycle (#1761 sled retry fix; #1762 prior state sync; #1763 / #1735 Dependabot maintenance; #1764 ActionCard contract publication itself) into docs/STATE.md and docs/PHASE_PROGRESS.md. Doc/control-plane only with one runtime fix in icn-commons.

Decisive Test

Can a new organizer enter the system mid-cycle, switch into the right scope, see the summit's current phase, understand what was decided, know what is blocked, receive their obligations, trace why they exist, and continue the work without private oral history?

Unchanged from the 2026-04-15 handoff. Every move is judged against whether it makes that more answerable. The ActionCard contract publication advances "receive their obligations, trace why they exist" by giving partner packages a generic ICN contract to validate their card templates against — institution-specific semantics stay in institution packages while ICN core ships only the generic primitive.

Final State (Verified)

main HEAD (pre-this-sync-PR)

f7c3bf73 docs(contracts): publish ActionCard contract for institution packages (#1764)

Open PRs

(none open at handoff write-time, verified via gh pr list --state open returning []. Dependabot may surface follow-on bumps automatically.)

Open coordination/control issues (not implementation)

Branches

• docs/sync-actioncard-contract-1764 — local + remote at handoff write-time. This sync PR.
• main — origin/main at f7c3bf73 (post-#1764) at handoff write-time.

Cycle landed in order

Issues closed

Required-check status (each PR's final gates)

#1764 final gates (all required checks passed on the rebased SHA abe7ff96): claude-review (4m46s), Format Check, Clippy, Test, TypeScript SDK, Build Release, Documentation Control Plane, Documentation CI Summary, Check Documentation Freshness, Generate Documentation Index, Lint Architecture Doc, Agent Tooling Drift Check, Change Scope, Firewall Contract Enforcement, Kernel Forbidden Dependencies, Meaning Firewall Check, Regulatory Compliance Linter, Secrets Placeholder Check, Accessibility Tests. Skipped (normal for docs-only): Backup Validation, Security Audit, Test Coverage, Web UI, claude, Pilot Provenance Invariant. mergeStateStatus was BEHIND on first merge attempt (main had moved forward via #1763); rebased onto current main, force-pushed with --force-with-lease, CI re-ran clean, then squash-merged with mergeStateStatus: CLEAN.

Validators (this session, observed outputs)

• git diff --check — clean
• python3 docs/scripts/validate-action-card.py — OK: docs/contracts/institution-package/action-card.example.json validates against https://intercooperative.network/contracts/institution-package/action-card.schema.json
• python3 .github/scripts/compliance_linter.py — 0 violations (107 files scanned)
• python3 docs/scripts/doc_control_check.py --repo . --registry docs/registry.toml --strict — OK: doc control check passed (778 docs markdown files under docs/); 36 enforcement warnings (baseline; no new warnings; corpus 777 → 778 from this handoff itself)
• bash ops/scripts/drift-check.sh — STATUS: PASS (0 errors, 0 warnings)

What Changed

1. Opened and merged #1764

Branch docs/actioncard-contract-1713 from main at c0a614ee. Added:

• docs/contracts/institution-package/action-card.example.json — fictional proposal/vote ActionCard with all required fields plus optional deadline and domain_id. Uses fictional ids (prop-example-2026-05-07-001, domain-example-fictional-cooperative); contains no NYCN-specific nouns. Validates against the existing schema.
• docs/scripts/validate-action-card.py — draft-2020-12 JSON Schema validator, mirrors validate-preview-review.py / validate-rehearsal-evidence.py. Defaults to validating the bundled example; accepts a partner-side card path positional; supports --schema for pinned-version validation. Stdlib-only format: date-time and format: uri checkers registered for symmetry with the other contract validators.

Modified:

• docs/contracts/institution-package/README.md — Files table now lists schema + example + validator; Stability section cites ADR-0027 § Card kind taxonomy ("growable by ADR amendment") and documents the schema's DNS-backed $id retain-temporarily decision per docs/contracts/schema-id-audit.md (review by 2026-06-30 tracked by #1742); Validation guidance now includes explicit emitted-vs-gated source kind enumeration with tracking-issue cites, regulatory-safe vocabulary list (obligation, allocation, settlement, unit, position, receipt, provenance, evidence — explicitly not payment / wallet / balance / currency), explicit "institution-specific semantics belong in institution packages, not in ICN core" guidance, a worked CLI command block for the new validator, and partner-package vendor-or-invoke-from-CI guidance. Last Reviewed advanced 2026-05-04 → 2026-05-07.
• docs/registry.toml — institution-package README entry: last_updated and last_reviewed advanced 2026-05-04 → 2026-05-07; description refreshed to mention the new example, validator, and schema-id-audit retention decision.

One substantive Copilot review finding addressed pre-merge (commit ffb4d791 on the branch, squashed into merge commit f7c3bf73): the positional CLI argument was packet (and the default constant was DEFAULT_PACKET) — leftover from validate-preview-review.py where "packet" is correct. Renamed to card / DEFAULT_CARD to align with the schema, ADR-0027, README, and runtime struct (ActionCard in icn/apps/governance/src/http/models.rs:235). Mechanical rename only; bundled example revalidated clean afterward.

mergeStateStatus: BEHIND on first merge attempt (main had moved forward via #1763 after my branch was created); rebased onto current main, force-pushed with --force-with-lease, full CI re-ran clean (claude-review 4m46s on the rebased SHA abe7ff96), confirmed mergeStateStatus: CLEAN, then squash-merged.

2. Manually closed #1713 with an acceptance-criteria comment

PR body intentionally avoided GitHub's auto-close regex (closes ... #N directly). After merge, closed #1713 by hand with a comment enumerating each of the six acceptance criteria and the merged-PR evidence path for each. Comment URL: https://github.com/InterCooperative-Network/icn/issues/1713#issuecomment-....

3. STATE.md truth-sync (docs/STATE.md)

• New 2026-05-07 (post-#1761 / #1762 / #1763 / #1764) sync edit comment block at the top, immediately before the existing 2026-05-07 (post-#1755 / #1756 / #1757 / #1758 / #1759) block. Records each landing in the May-7 close-out cycle, the #1713 closure, and the explicit non-claims.
• Top-of-file "Current status (2026-05-07 snapshot)" paragraph extended to include a second paragraph naming the May-7 close-out cycle and the ActionCard contract publication.
• Updated the post-#1755/#1759 paragraph: replaced "PR #1761 (open at this sync write-time)" with "PR #1761 (merged 2026-05-07; closed #1760)".
• Appended five new rows at the top of "Recently merged (since 2026-04-15)" table: #1764, #1763, #1735, #1762, #1761.
• "Open PRs" table now shows the empty-queue note (verified via gh pr list --state open).
• "Open implementation follow-ups" table now shows the empty-queue note (#1760 closed by #1761 merge).
• New "ActionCard contract publication for institution packages" bullet block at the top of "What landed since Phase 1 (Charter Engine)" recording each artifact, the schema-id-audit retention decision, the #1713 closure, and the explicit hard-rule preservation.
• New "May-7 close-out cycle" bullet block recording #1761/#1762/#1763/#1735.
• References block extended with ADR-0027, the institution-package README, and the validator script. Latest handoff pointer updated 2026-05-07 → 2026-05-07-a; the prior 2026-05-07 handoff is preserved as a same-day historical artifact.

4. PHASE_PROGRESS.md truth-sync (docs/PHASE_PROGRESS.md)

• Top-of-file phase paragraph extended to mention the May-7 close-out cycle and the ActionCard contract publication.
• New 2026-05-07 (post-#1761 / #1762 / #1763 / #1764) sync edit comment block recording each landing, the idea-0019 (#1748) acceptance-gate posture (unchanged from #1762), the #1713 closure (independent of #1748 gates), and the explicit non-claims.
• Phase 2 deliverables list extended with five new [x] entries crediting #1761, #1762, #1763 / #1735, and #1764.
• New top entry in "Decisions Made" recording the cycle landing, the #1713 closure, the substantive Copilot review finding addressed pre-merge, the $id retain-temporarily decision (#1742 review by 2026-06-30), the unchanged idea-0019 (#1748) acceptance-gate posture, the unchanged Phase 2 status, and the explicit "next move not yet selected" stance.

5. New session handoff

This file (docs/dev/handoff-2026-05-07-a.md). The prior 2026-05-07 handoff (docs/dev/handoff-2026-05-07.md) is preserved verbatim as the post-opaque-receipt-storage-stack handoff; this file is the post-May-7-close-out-cycle handoff.

6. Registry refresh

Regenerated docs/DOCUMENT_REGISTRY.md to reflect the +1 corpus delta (this new handoff under docs/dev/). The handoff falls under the existing [[doc_path_defaults]] rule with prefix = "docs/dev/" so no per-file overlay row is needed in docs/registry.toml.

What's Open

The next session picks one of these. None is selected here. The next session must choose deliberately from updated canonical truth, not auto-pilot.

• Additional idea-0019 ProcessTransitionReceipt classes — adding any of the seven remaining classes (ProcessSessionOpenedReceipt, DeliberationEntryRecordedReceipt, DecisionRecordedReceipt, ActivationCrossedReceipt, MutationPlanRecordedReceipt, MutationAppliedReceipt, EvidencePacketProducedReceipt) is now a one-file change in apps/governance because the opaque storage cascade landed in #1757/#1758/#1759. None of these is a separately scoped PR yet.
• idea-0019 (#1748) acceptance gate (b) — real visibility/privacy-boundary run with redaction in evidence export. Unchanged: not started.
• idea-0019 (#1748) acceptance gate (c) — accessibility-gate ProcessGateResult produced through docs/design/ORGANIZER_MEMBER_ACCESSIBILITY_GATE.md on a real surface. Unchanged: not started.
• idea-0019 (#1748) acceptance gate (d) — open-question triage: at least one of Q1 (ProcessTargetRef polymorphism), Q3 (DeliberationEntry kind taxonomy), or Q4 (HumanDecisionSet vs proposal/vote) resolved or explicitly deferred in writing. Unchanged: not started.
• idea-0020 (DAP) runtime dogfood — emitting at least one receipt under ADR-0026 for one DAP primitive. Unchanged: not started. The opaque storage cascade (#1757/#1758/#1759) means adding DAP receipt classes is the same one-file change that idea-0019 classes get.
• DAP §17 follow-up framing briefs — pre-RFC, decompose-only. Unchanged: not started.
• #1742 ActionCard $id compatibility review — calendar artifact for the audit's 2026-06-30 review. Not started; not due yet.
• Action-card runtime — remaining gates under #1646 (RFC-gated): signal_rule source path (gated on #1631 / #1711); obligation_lifecycle source path (gated on #1634 / #1712). Unchanged: not started.
• Control-plane cleanup, including unresolved/stale review-thread hygiene if inspection confirms it; pre-existing yaml-vs-registry drift on docs/ai/*, docs/architecture/INSTITUTION_PACKAGE_BOUNDARY.md, docs/design/*, docs/development/testing/governance-proof-layers.md, docs/onboarding/*, docs/planning/*, docs/plans/* is named here as a possible candidate but not selected.
• NYCN steward-facing communication-groups directory tool (NYCN #33) — verify status before reading; not in this repo. Carried forward.

Unsafe Assumptions

• This sync trusts that #1761/#1762/#1763/#1735/#1764 are themselves internally consistent; their squash commit messages and PR bodies are the audit record.
• "Open PRs" trusts gh pr list --state open --limit 20 at handoff write-time. Dependabot may open additional dev-dependency bumps before the next session.
• The schema-id-audit retain-temporarily decision (review by 2026-06-30) is honored by citation only: this PR did not run a fresh consumer enumeration for the ActionCard schema's $id. The audit's §5 enumeration of downstream consumers will happen in the eventual migration PR (or in #1742 if the review chooses non-migration with a refreshed review date).
• The schema's field-by-field match against ActionCard in icn/apps/governance/src/http/models.rs:235 is asserted by reading the file in #1764 prep but not verified by mechanical drift detection (which the README explicitly names as future work).
• The "no Stage 1.5 / Stage 2 / Stage 3 / Stage 4 / Stage 5" non-claim trusts the user's stage taxonomy verbatim from session prompts; this PR does not define those stages.
• Rust workspace verification was not run for this sync PR because no .rs files are touched. The May-7 cycle's only Rust change was #1761 (icn/crates/icn-commons/src/store.rs); that change is verified by #1761's own merged CI, not by this sync PR.

Next Move

Not selected here. Pick deliberately from the "What's Open" list at the next session.

Candidate next moves (named here so the next session can choose deliberately, not by inertia): (a) DAP runtime dogfood emitting at least one receipt under ADR-0026 for one DAP primitive — the next artifact called for by idea-0020's read-model promotion gate; (b) idea-0019 runtime dogfood emitting one of the seven remaining ProcessTransitionReceipt classes through the opaque cascade; (c) idea-0019 visibility/privacy-boundary run; (d) idea-0019 accessibility-gate ProcessGateResult on a real surface; (e) idea-0019 open-question triage on Q1/Q3/Q4; (f) one of the DAP §17 follow-up framing briefs (CCL hook-point catalog; expert/advisory across institution types; conflict object model; federation tally semantics; delegation runtime); (g) control-plane cleanup. None is selected here.

Architectural Decisions

No new architectural decisions were ratified this session. Existing architectural decisions reaffirmed:

1. Institution-specific semantics belong in institution packages, not in ICN core. ICN core ships generic primitives; packages translate their local templates. Codified in the institution-package README's Validation guidance, item 5. Aligned with ADR-0027.
2. Hand-maintained contract schemas are edited alongside contract work. OpenAPI export and generated TypeScript types guard the generated API contract via CI drift checks (icnctl api export-openapi, sdk/typescript regen); hand-maintained JSON schemas under docs/contracts/ are updated in the same PR as the API/OpenAPI change. Mechanical drift detection comparing the hand-maintained schema to serde-derived shapes is named as future work.
3. The default for new contract schemas is a non-DNS URN of the form urn:icn:contract:<short-name>:v<N>. Existing DNS-backed $ids (today: action-card.schema.json) are retained temporarily under the audit's per-schema review discipline; migration is a separate single-schema PR under audit §5 rules. Reaffirmed by this PR's README addition citing the audit decision.

Verification Commands

# 1. Confirm main HEAD is post-this-sync.
git fetch origin main
git log --oneline -1 origin/main
# expect: <sync-merge-sha> docs(state): sync ActionCard contract publication landing (#<sync-pr>)

# 2. Confirm Rust compile-clean against the cycle's runtime change.
cd icn
cargo check -p icn-commons
cargo test -p icn-commons --lib

# 3. Confirm contract validators still pass.
cd ..
python3 docs/scripts/validate-action-card.py
python3 docs/scripts/validate-preview-review.py
python3 docs/scripts/validate-rehearsal-evidence.py

# 4. Confirm doc-control plane clean.
python3 docs/scripts/doc_control_check.py --repo . --registry docs/registry.toml --strict
bash ops/scripts/drift-check.sh

# 5. Confirm firewall ratchet preserved.
python3 .github/scripts/firewall_denylist.py

# 6. Confirm the open issue list matches this handoff.
gh issue list --state open --limit 20
gh pr list --state open --limit 20

If any of (1)-(5) diverges from the expected state, audit the divergence before resuming work.

Truth-Plane Notes

• Declared project truth (loaded from): docs/STATE.md post-#1755/#1759 sync edit at session start; docs/PHASE_PROGRESS.md post-#1755/#1759 sync edit at session start. Both advanced this session to post-#1764 sync edits as part of this handoff's accompanying docs PR. The Phase 2 framing (still ⏳ partner-bound) is unchanged across this advance — only deliverable enumeration, references, and the post-#1755/#1759 paragraph's "PR #1761 (open at this sync write-time)" wording changed.
• Implementation truth (what was verified from code): ActionCard struct field-by-field match against docs/contracts/institution-package/action-card.schema.json (12 always-emitted required fields; 2 #[serde(skip_serializing_if = "Option::is_none")] optional fields; four enums with matching #[serde(rename_all = "snake_case")] values). Bundled example revalidates against the schema (OK: ... validates against ...).
• Execution truth (branch/PR/CI state confirmed): all five cycle PRs verified merged via gh pr view (states + merge SHAs); local working tree clean at handoff write-time; CI gate status confirmed via gh pr checks per PR; #1713 closure verified via gh issue view 1713 --json state,closedAt.
• Narrative truth (any strategy doc claims that may be stale): the post-#1755/#1759 sync edit's reference to "PR #1761 (open at this sync write-time)" was stale at this session's start and is corrected to "PR #1761 (merged 2026-05-07; closed #1760)" in this advance.
• Known conflicts between layers: none discovered this session beyond the stale "open at this sync write-time" wording in #1762's STATE.md edit, which is corrected by this PR.