Experimental ML primitives package

.agents/skills/adr-keeper/references/adr-index.md

@@ -1,28 +1,39 @@
 # ADR Index
 
-**Last updated:** 2025-01-01
-**Total ADRs:** 6
+**Last updated:** 2026-06-19
+**Total ADRs:** 17
 
 | # | ADR | Status | Related Requirements |
 |---|-----|--------|---------------------|
-| [0001](0001-reactive-task-stale-detection.md) | Reactive Task Stale Detection via Pending Node | ✅ Accepted | Unified Graph |
-| [0002](0002-match-handler-signature-design.md) | Match Handler Signature Design | ✅ Accepted | Utility Function Exports |
-| [0003](0003-equality-strategy-naming-convention.md) | Equality Strategy Naming Convention | ✅ Accepted | Minimal Surface |
-| [0004](0004-isequal-placement-and-deprecation.md) | isEqual Placement and Deprecation | ✅ Accepted | Minimal Surface |
-| [0005](0005-cycle-detection-omission-in-deep-equality.md) | Cycle Detection Omission in Deep Equality | ✅ Accepted | Bundle Size, Zero-Deps |
-| [0006](0006-scope-root-option-pattern.md) | Scope Root Option Pattern | ✅ Accepted | API Design |
+| [0001](../../../../adr/0001-reactive-task-stale-detection.md) | Reactive Task Stale Detection via Pending Node | ✅ Accepted | Unified Graph |
+| [0002](../../../../adr/0002-match-handler-signature-design.md) | Match Handler Signature Design | ✅ Accepted | Utility Function Exports |
+| [0003](../../../../adr/0003-equality-strategy-naming-convention.md) | Equality Strategy Naming Convention | ✅ Accepted | Minimal Surface |
+| [0004](../../../../adr/0004-isequal-placement-and-deprecation.md) | isEqual Placement and Deprecation | ✅ Accepted | Minimal Surface |
+| [0005](../../../../adr/0005-cycle-detection-omission-in-deep-equality.md) | Cycle Detection Omission in Deep Equality | ✅ Accepted | Bundle Size, Zero-Deps |
+| [0006](../../../../adr/0006-scope-root-option-pattern.md) | Scope Root Option Pattern | ✅ Accepted | API Design |
+| [0007](../../../../adr/0007-node-composition-via-field-mixins.md) | Node Composition via Field Mixins | ✅ Accepted | Minimal Surface, Unified Graph |
+| [0008](../../../../adr/0008-doubly-linked-list-edge-structure.md) | Doubly-Linked List Edge Structure | ✅ Accepted | Bundle Size, Minimal Surface |
+| [0009](../../../../adr/0009-activeSink-protocol-for-automatic-dependency-tracking.md) | activeSink Protocol for Automatic Dependency Tracking | ✅ Accepted | Explicit Reactivity |
+| [0010](../../../../adr/0010-flag-relink-mechanism-for-structural-reactivity.md) | FLAG_RELINK Mechanism for Structural Reactivity | ✅ Accepted | Unified Graph, Minimal Surface |
+| [0011](../../../../adr/0011-cascading-cleanup-protocol-in-unlink.md) | Cascading Cleanup Protocol in unlink() | ✅ Accepted | Unified Graph, Minimal Surface |
+| [0012](../../../../adr/0012-two-level-flagging-dirty-and-check.md) | Two-Level Flagging (DIRTY and CHECK) | ✅ Accepted | Minimal Work |
+| [0013](../../../../adr/0013-link-fast-path-optimizations.md) | link() Fast-Path Optimizations | ✅ Accepted | Performance |
+| [0014](../../../../adr/0014-two-path-access-pattern-for-composite-signals.md) | Two-Path Access Pattern for Composite Signals | ✅ Accepted | Performance, Unified Graph |
+| [0015](../../../../adr/0015-neuron-signal.md) | Neuron Signal | 🔄 Draft | — (experimental, out of 9-type scope) |
+| [0016](../../../../adr/0016-layer-signal.md) | Layer Signal | 🔄 Draft | — (experimental, out of 9-type scope) |
+| [0017](../../../../adr/0017-public-api-decoupling-for-ml-primitives.md) | Public-API Decoupling for ML Primitives | 🔄 Draft | Minimal Surface, Bundle Size |
 
 ---
 
 ## Status Legend
 
 - ✅ Accepted: Decision has been implemented and is in use
-- 🔄 Proposed: Decision is under discussion
+- 🔄 Draft: Decision is proposed but not yet finalized; details may change
 - ❌ Rejected: Decision was considered but not adopted
 - 🗑️ Superseded: Decision has been replaced by a newer ADR
 
-## Quick Links
+## Notes
 
+- **0001–0014**: Core graph-engine and API decisions, all accepted and in use. Documented in [ARCHITECTURE.md](../../../../ARCHITECTURE.md).
+- **0015–0017**: Experimental ML primitives (`Neuron`, `Layer`) and their extraction into the `correlation-prediction` package. These are outside cause-effect's 9-signal-type scope (see [REQUIREMENTS.md](../../../../REQUIREMENTS.md) Non-Goals) and remain Draft pending the extraction's first release.
 - [ADR Template](adr-template.md)
-- [ARCHITECTURE.md](../../../../ARCHITECTURE.md)
-- [REQUIREMENTS.md](../../../../REQUIREMENTS.md)

.agents/skills/architect/SKILL.md

@@ -110,7 +110,7 @@ What kind of task is this?
 | `ARCHITECTURE.md` | Current system design and key decisions |
 | `TODO.md` | Active task queue (create if absent) |
 | `NOTES.md` | Developer-written blockers and questions |
-| `CLAUDE.md` | Non-obvious behaviors — consult before making decisions about the API surface |
+| `.agents/skills/shared/references/non-obvious-behaviors.md` | Non-obvious behaviors — consult before making decisions about the API surface |
 </reference_index>
 
 <workflows_index>

.agents/skills/architect/workflows/architecture.md

@@ -3,7 +3,7 @@
 
 1. `REQUIREMENTS.md` — goals, constraints, non-negotiables
 2. Relevant sections of `ARCHITECTURE.md` — understand the current system
-3. `CLAUDE.md` — non-obvious constraints that affect the design surface
+3. `.agents/skills/shared/references/non-obvious-behaviors.md` — non-obvious constraints that affect the design surface
 
 ## Step 2: Explore the codebase
 

.agents/skills/architect/workflows/review-api.md

@@ -18,7 +18,7 @@ Read changed source files in full. Do not review from the handoff summary alone.
 
 ## Step 4: Evaluate DX and consistency
 
-Read `CLAUDE.md` and `ARCHITECTURE.md` for established patterns:
+Read `.agents/skills/shared/references/non-obvious-behaviors.md` and `ARCHITECTURE.md` for established patterns:
 - Is the API ergonomic? Would a library consumer write this naturally?
 - Is naming consistent with the existing surface?
 - Are defaults sensible? Is it easy to misuse?

.agents/skills/architect/workflows/triage.md

@@ -13,7 +13,7 @@ Read the issue or report fully. Identify what the user expected, what happened,
 
 To classify correctly:
 - Read `REQUIREMENTS.md` (Must Have / Should Avoid / Out of Scope)
-- Read `CLAUDE.md` — many apparent bugs are documented non-obvious behaviors
+- Read `.agents/skills/shared/references/non-obvious-behaviors.md` — many apparent bugs are documented non-obvious behaviors
 - Search the source if needed to confirm whether the behavior is by design
 
 ## Step 3: Resolve
@@ -37,7 +37,7 @@ To classify correctly:
 </process>
 
 <success_criteria>
-- Issue classified with clear reasoning grounded in REQUIREMENTS.md or CLAUDE.md
+- Issue classified with clear reasoning grounded in REQUIREMENTS.md or `.agents/skills/shared/references/non-obvious-behaviors.md`
 - Won't do: user has a specific explanation
 - All other resolvable cases: a correctly formatted task in TODO.md
 - Unclear cases: escalated to the user, not guessed

.agents/skills/cause-effect-dev/references/source-map.md

@@ -6,7 +6,7 @@ Where to find things in the @zeix/cause-effect codebase. Read this before locati
 | What you need | Where to look |
 |---|---|
 | Vision, audience, constraints, non-goals | `REQUIREMENTS.md` |
-| Mental model, non-obvious behaviors, TS constraints | `CLAUDE.md` |
+| Mental model, non-obvious behaviors, TS constraints | `.agents/skills/shared/references/non-obvious-behaviors.md` |
 | Full API reference with examples | `README.md` |
 | Mapping from React/Vue/Angular patterns; when to use each signal type | `GUIDE.md` |
 | Graph engine architecture, node shapes, propagation | `ARCHITECTURE.md` |
@@ -40,6 +40,6 @@ Each signal type lives in its own file under `src/nodes/`:
 - Changing graph traversal, flags, or flush order → read `src/graph.ts` + `ARCHITECTURE.md`
 - Adding or changing error conditions → read `src/errors.ts`
 - Adding a shared utility → check `src/util.ts` first; add there if it belongs to multiple nodes
-- Checking type constraints or TS-specific decisions → read `CLAUDE.md`
+- Checking type constraints or TS-specific decisions → read `.agents/skills/shared/references/non-obvious-behaviors.md`
 - Verifying a feature is in scope → read `REQUIREMENTS.md`
 </quick_lookup>

.agents/skills/cause-effect-dev/workflows/answer-question.md

@@ -6,7 +6,7 @@ Load references based on the question type — only what is needed:
 - Graph propagation, flags, flush order → references/internal-types.md (then read `ARCHITECTURE.md` if still unclear)
 - Unexpected or counterintuitive behavior → ../shared/references/non-obvious-behaviors.md
 - A thrown error → ../shared/references/error-classes.md
-- Design rationale or constraints → `REQUIREMENTS.md` + `CLAUDE.md`
+- Design rationale or constraints → `REQUIREMENTS.md` + `.agents/skills/shared/references/non-obvious-behaviors.md`
 - Comparing signal types or migration from React/Vue/Angular → references/source-map.md (then read `GUIDE.md`)
 </required_reading>
 
@@ -29,7 +29,7 @@ Identify which category applies:
 
 Read only the reference files listed for that category above. Do not load references speculatively.
 
-If a reference points to an authoritative document (`ARCHITECTURE.md`, `GUIDE.md`, `REQUIREMENTS.md`, `CLAUDE.md`), read that document only if the reference files do not fully resolve the question.
+If a reference points to an authoritative document (`ARCHITECTURE.md`, `GUIDE.md`, `REQUIREMENTS.md`, `.agents/skills/shared/references/non-obvious-behaviors.md`), read that document only if the reference files do not fully resolve the question.
 
 ## Step 3: Read source if needed
 
@@ -43,7 +43,7 @@ Ground every claim in a source. Cite the file when the answer is non-obvious (e.
 
 For counterintuitive behaviors, include a minimal code example showing the correct pattern alongside the incorrect one. Use the examples in references/non-obvious-behaviors.md as a model.
 
-For design rationale questions, distinguish between hard constraints (stated in `REQUIREMENTS.md`) and soft conventions (described in `CLAUDE.md`).
+For design rationale questions, distinguish between hard constraints (stated in `REQUIREMENTS.md`) and soft conventions (described in `.agents/skills/shared/references/non-obvious-behaviors.md`).
 </process>
 
 <success_criteria>

.agents/skills/tech-writer/SKILL.md

@@ -2,15 +2,14 @@
 name: tech-writer
 description: >
   Keep developer-facing documents up to date with the @zeix/cause-effect source code:
-  README.md, GUIDE.md, ARCHITECTURE.md, REQUIREMENTS.md, CLAUDE.md,
-  .github/copilot-instructions.md, and JSDoc in src/. Use after code changes, to verify
-  consistency, or to update a specific document.
+  README.md, GUIDE.md, ARCHITECTURE.md, REQUIREMENTS.md, AGENTS.md, and JSDoc in src/.
+  Use after code changes, to verify consistency, or to update a specific document.
 user_invocable: true
 ---
 
 <scope>
 This skill is for the cause-effect library repository. It expects source files at `src/`
-and `index.ts`, documentation at the project root, and agent instructions at `.github/`.
+and `index.ts`, documentation at the project root, and agent instructions at `AGENTS.md`.
 
 For consumer projects using `@zeix/cause-effect` as a dependency, use the `cause-effect`
 skill instead.
@@ -55,14 +54,14 @@ What do you need to do?
 |---|---|
 | `README.md` or `GUIDE.md` | workflows/update-public-api.md |
 | `ARCHITECTURE.md` | workflows/update-architecture.md |
-| `CLAUDE.md` or `copilot-instructions.md` | workflows/update-agent-docs.md |
+| `AGENTS.md` | workflows/update-agent-docs.md |
 | `REQUIREMENTS.md` | workflows/update-requirements.md |
 | JSDoc / `src/` | workflows/update-jsdoc.md |
 
 **Intent-based routing (clear intent without selecting a number):**
 - "document the new API" / "update README" → workflows/update-public-api.md
 - "update the architecture doc" → workflows/update-architecture.md
-- "update CLAUDE.md" / "add non-obvious behavior" → workflows/update-agent-docs.md
+- "update AGENTS.md" / "add non-obvious behavior" → workflows/update-agent-docs.md
 - "update JSDoc" / "inline docs" → workflows/update-jsdoc.md
 - "update requirements" → workflows/update-requirements.md
 - "review all docs" / "check consistency" → workflows/consistency-review.md
@@ -87,7 +86,7 @@ All in `workflows/`:
 | update-after-change.md | Determine which documents to update after a code change, then update them in order |
 | update-public-api.md | Update `README.md` and `GUIDE.md` |
 | update-architecture.md | Update `ARCHITECTURE.md` |
-| update-agent-docs.md | Update `CLAUDE.md` and `.github/copilot-instructions.md` |
+| update-agent-docs.md | Update `AGENTS.md` |
 | update-requirements.md | Update `REQUIREMENTS.md` |
 | update-jsdoc.md | Update JSDoc comments in `src/` |
 | consistency-review.md | Review all documents for consistency with current source |

.agents/skills/tech-writer/references/document-map.md

@@ -110,56 +110,32 @@ per-signal-type subsection describing each type's internal composition and lifec
 - No subsection references a removed type, flag, or function
 </ARCHITECTURE_md>
 
-<CLAUDE_md>
-**Path:** `CLAUDE.md`
-**Audience:** Claude (this model) at inference time
+<AGENTS_md>
+**Path:** `AGENTS.md`
+**Audience:** Coding agents (Claude, Copilot, ZCode/GLM, Cursor) at inference time; also the
+canonical skill index for the project
 **Register:** Terse, direct, AI-optimized — every token has a cost; no explanatory padding
-**Scope:** Spreadsheet-cell mental model for all 9 signal types; internal node shapes and the
-`activeSink`/`activeOwner` dual-pointer model; non-obvious behaviors that a competent reactive
-developer would not predict from the public API alone
+**Scope:** Project type and core concepts, code style (naming, generics, pure-function
+annotations), key patterns (signal `.get()`/`.set()`, proxy reactivity, callbacks, batch/
+untrack), file structure mapping `src/` modules to responsibilities, error-handling entry
+points, and the index of available agent skills
 
 **Update triggers:**
-- A signal type is added (extend the mental model list and node shapes)
-- Internal node shapes change (`src/graph.ts` field composition)
-- `activeSink` or `activeOwner` semantics change
-- A non-obvious behavior is introduced, changed, or resolved
-- An existing non-obvious behavior entry becomes inaccurate
-
-**Consistency checks:**
-- Mental model list covers all 9 signal types
-- Internal Node Shapes block matches `src/graph.ts`
-- `activeOwner`/`activeSink` description is accurate
-- Every non-obvious behavior entry is still correct for the current implementation
-- No entry describes behavior that has since changed or been removed
-</CLAUDE_md>
-
-<copilot_instructions_md>
-**Path:** `.github/copilot-instructions.md`
-**Audience:** GitHub Copilot during code generation
-**Register:** Structured, pattern-oriented — code examples are generation templates, not prose
-**Scope:** Project overview, core architecture summary (node types, edge structure, graph
-operations, flags), signal type descriptions with factory names, key file paths, coding
-conventions (TypeScript style, naming, error handling, performance patterns), API design
-principles, common code patterns (signal creation, reactivity, type safety, resource
-management), build system
+- A factory function signature changes (update the corresponding pattern)
+- A new source file is added to `src/` (update the File Structure map)
+- A coding convention or key pattern is established or changes
+- The set of available agent skills changes (update the skill index)
 
-**Update triggers:**
-- A new signal type is added (add to signal types list, key files, and code patterns)
-- A factory function signature changes (update the corresponding code pattern)
-- A node type or flag is added, renamed, or removed (update Core Architecture section)
-- A new source file is added to `src/` (update Key Files Structure)
-- A coding convention or API design principle changes
-- A new common code pattern is established
+**Do NOT update for:** non-obvious behavior entries (those live in the shared reference),
+node-shape internals (those live in `ARCHITECTURE.md`), bug fixes that do not change
+conventions.
 
 **Consistency checks:**
-- Signal Types list covers all 9 signal types with accurate factory name and one-line
-  description
-- Key Files Structure lists all current `src/` and `src/nodes/` files
-- Code patterns in "Common Code Patterns" use current factory signatures and option names —
-  verify each against `index.ts`
-- API Design Principles accurately describe current conventions
-- Core Architecture node types and flags match `src/graph.ts`
-</copilot_instructions_md>
+- File Structure map lists all current `src/` and `src/nodes/` files
+- Code patterns compile against current `index.ts` (factory signatures, option names,
+  parameter order)
+- Skill index matches the skills present under `.agents/skills/`
+</AGENTS_md>
 
 <jsdoc_in_src>
 **Path:** `src/nodes/*.ts`, `src/graph.ts`, `src/errors.ts`, `src/util.ts`, `src/signal.ts`
@@ -185,14 +161,17 @@ constraints. Internal helpers do not require JSDoc.
 <change_to_document_matrix>
 Quick reference for update-after-change.md. Use this to identify affected documents.
 
-| Change type                        | JSDoc | ARCH | CLAUDE + copilot | README | GUIDE | REQ |
-|------------------------------------|-------|------|------------------|--------|-------|-----|
-| New signal type                    | ✓     | ✓    | ✓                | ✓      | ✓     | ✓ * |
-| Changed public signature / option  | ✓     | —    | ✓ if behavior    | ✓      | ✓ if mental model | — |
-| Removed public API                 | ✓     | ✓ if structural | ✓       | ✓      | ✓ if documented | — |
-| New / changed non-obvious behavior | —     | ✓ if graph-level | ✓      | ✓ if affects usage | — | — |
-| Internal implementation change     | —     | ✓    | ✓                | —      | —     | — |
-| Vision / scope / constraint change | —     | —    | —                | —      | —     | ✓ |
+| Change type                        | JSDoc | ARCH | AGENTS | README | GUIDE | REQ |
+|------------------------------------|-------|------|--------|--------|-------|-----|
+| New signal type                    | ✓     | ✓    | ✓      | ✓      | ✓     | ✓ * |
+| Changed public signature / option  | ✓     | —    | ✓ if behavior | ✓ | ✓ if mental model | — |
+| Removed public API                 | ✓     | ✓ if structural | ✓  | ✓      | ✓ if documented | — |
+| New / changed non-obvious behavior | —     | ✓ if graph-level | — (shared ref) | ✓ if affects usage | — | — |
+| Internal implementation change     | —     | ✓    | ✓      | —      | —     | — |
+| Vision / scope / constraint change | —     | —    | —      | —      | —     | ✓ |
+
+Non-obvious behaviors are authored in the shared reference
+(`.agents/skills/shared/references/non-obvious-behaviors.md`), not in `AGENTS.md`.
 
 \* For REQUIREMENTS.md: only the signal type table row. Not the prose count — update
 that to match automatically.