@zeix/cause-effect 1.0.0 → 1.0.1

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

@@ -0,0 +1,55 @@
+<required_reading>
+Load references based on the question type — only what is needed:
+
+- API usage or call signatures → references/api-facts.md + references/source-map.md
+- Internal architecture, node shapes, ownership → references/internal-types.md
+- Graph propagation, flags, flush order → references/internal-types.md (then read `ARCHITECTURE.md` if still unclear)
+- Unexpected or counterintuitive behavior → references/non-obvious-behaviors.md
+- A thrown error → references/error-classes.md
+- Design rationale or constraints → `REQUIREMENTS.md` + `CLAUDE.md`
+- Comparing signal types or migration from React/Vue/Angular → references/source-map.md (then read `GUIDE.md`)
+</required_reading>
+
+<process>
+## Step 1: Categorise the question
+
+Identify which category applies:
+
+| Category | Signal words |
+|---|---|
+| API / call signature | "how do I use", "what does X return", "what are the options for" |
+| Internal architecture | "how does it work internally", "what is a node", "how is ownership tracked" |
+| Graph / propagation | "when does it re-run", "why did X not update", "what is FLAG_CHECK" |
+| Non-obvious behavior | "why does this not work", "is this a bug", "why is `watched` not firing" |
+| Error meaning | "what does X error mean", "when is Y thrown" |
+| Design rationale | "why was X designed this way", "why is null excluded", "why no X signal type" |
+| Signal type comparison | "when should I use Memo vs Task", "what is a Slot", "Sensor vs State" |
+
+## Step 2: Load the relevant references
+
+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.
+
+## Step 3: Read source if needed
+
+If the question requires knowing exact implementation details (option defaults, internal flag values, exact type signatures), use references/source-map.md to locate and read the relevant source file.
+
+Never guess at implementation details. If uncertain, read the source.
+
+## Step 4: Answer
+
+Ground every claim in a source. Cite the file when the answer is non-obvious (e.g. "per `ARCHITECTURE.md`…" or "in `src/nodes/memo.ts`…").
+
+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`).
+</process>
+
+<success_criteria>
+- Answer is grounded in authoritative sources, not inference
+- Source cited when the answer is non-obvious
+- Counterintuitive behaviors include a correct vs incorrect code example
+- Design answers distinguish constraints from conventions
+- No reference files loaded beyond what the question required
+</success_criteria>

package/skills/cause-effect-dev/workflows/fix-bug.md

@@ -0,0 +1,63 @@
+<required_reading>
+1. references/source-map.md — locate the relevant source file(s)
+2. references/non-obvious-behaviors.md — the bug may be a known gotcha
+3. references/internal-types.md — if the bug involves graph propagation, ownership, or node state
+4. references/error-classes.md — if the bug manifests as an unexpected thrown error
+</required_reading>
+
+<process>
+## Step 1: Reproduce
+
+Identify the smallest possible reproduction. If a failing test exists, run it:
+
+```bash
+bun test --test-name-pattern "name of failing test"
+```
+
+If no test exists, write one that demonstrates the incorrect behavior before touching any source.
+
+## Step 2: Read the relevant source
+
+Use references/source-map.md to locate the source file(s) involved. Read them in full. Do not guess at the cause before reading.
+
+## Step 3: Check known gotchas
+
+Read references/non-obvious-behaviors.md. Many apparent bugs are actually expected behaviors:
+- Lookup methods (`byKey`, `at`, `keyAt`, `indexOfKey`) do not create graph edges
+- Conditional signal reads can delay `watched` activation
+- A custom `equals` on an intermediate Memo suppresses entire downstream subgraphs
+
+If the reported behavior matches a known non-obvious behavior, explain it rather than patching it.
+
+## Step 4: Check graph-level issues
+
+If the bug involves unexpected re-runs, missing updates, or ownership/cleanup problems, read `ARCHITECTURE.md` for flag semantics and propagation rules.
+
+## Step 5: Identify the root cause
+
+Trace the failure to its origin — do not fix the symptom. Confirm the root cause by reasoning through the propagation path or ownership chain before writing any fix.
+
+## Step 6: Fix
+
+Apply the minimal change that addresses the root cause. Follow existing conventions:
+- Flag names and bitmask operations from `src/graph.ts`
+- Error types from `src/errors.ts`
+- Do not introduce new utilities if `src/util.ts` already covers the need
+
+## Step 7: Verify
+
+Run the full test suite:
+
+```bash
+bun test
+```
+
+All tests must pass. If the reproduction test did not exist before Step 1, confirm it now passes too.
+</process>
+
+<success_criteria>
+- Root cause identified (not just symptom suppressed)
+- Minimal fix applied
+- Reproduction test passes
+- `bun test` passes with no regressions
+</success_criteria>

package/skills/cause-effect-dev/workflows/implement-feature.md

@@ -0,0 +1,46 @@
+<required_reading>
+1. references/source-map.md — locate the relevant source file(s)
+2. references/api-facts.md — API constraints and callback patterns
+3. references/non-obvious-behaviors.md — if the change touches graph edges, ownership, or reactive tracking
+</required_reading>
+
+<process>
+## Step 1: Confirm scope
+
+Read `REQUIREMENTS.md`. Verify the feature is in scope — the signal type set is complete and new types are explicitly out of scope. If the request would add a new signal type, stop and explain this constraint.
+
+## Step 2: Locate relevant source
+
+Use references/source-map.md to identify:
+- Which signal file(s) in `src/nodes/` are involved
+- Which authoritative documents to read (README.md for API shape, ARCHITECTURE.md for graph-level changes)
+
+## Step 3: Read before writing
+
+Read the identified source file(s) in full. Do not propose or write any code before doing this.
+
+If the change touches graph propagation, flag semantics, or ownership: read `ARCHITECTURE.md` in full.
+
+If the change affects the public API surface: read the relevant section of `README.md` and `index.ts`.
+
+## Step 4: Implement
+
+Make the change. Follow existing conventions in the file:
+- Naming patterns (`createX`, `isX`, node shape fields)
+- Internal flag usage (defined in `src/graph.ts`)
+- Error types from `src/errors.ts`
+- Utility functions from `src/util.ts` before writing new ones
+
+## Step 5: Verify
+
+Run `bun test`. Fix any failures before considering the task done.
+
+If the public API changed, check that `README.md` and `index.ts` are consistent with the new behavior.
+</process>
+
+<success_criteria>
+- Feature works as specified
+- Follows existing naming and structural conventions
+- `bun test` passes with no regressions
+- Public API surface in `index.ts` and `README.md` is consistent with the change
+</success_criteria>

package/skills/cause-effect-dev/workflows/write-tests.md

@@ -0,0 +1,64 @@
+<required_reading>
+1. references/source-map.md — locate the signal type or module being tested
+2. references/api-facts.md — correct API usage for test cases
+3. references/non-obvious-behaviors.md — ensure gotchas are covered
+4. references/error-classes.md — cover expected error conditions
+</required_reading>
+
+<process>
+## Step 1: Identify what to test
+
+Clarify the scope before writing anything:
+- Which signal type or behavior is under test?
+- Is this a new test, an extension of existing coverage, or a regression test for a known bug?
+
+## Step 2: Read the source
+
+Use references/source-map.md to locate the relevant source file in `src/nodes/`. Read it in full. Tests must match what the implementation actually does, not what you expect it to do.
+
+## Step 3: Read existing tests
+
+Find the existing test file for the signal type (look adjacent to or named after the source file). Read it to understand:
+- Test structure and helper patterns in use
+- Which behaviors are already covered
+- Naming conventions
+
+## Step 4: Identify gaps
+
+Cross-reference the source, existing tests, and these reference files:
+- references/non-obvious-behaviors.md — are gotchas covered?
+- references/error-classes.md — are thrown errors tested?
+- references/api-facts.md — are all option variants exercised (e.g. `equals`, `guard`)?
+
+## Step 5: Write tests
+
+Follow the conventions of the existing test suite. Each test should:
+- Have a descriptive name that states the expected behavior
+- Be self-contained (no shared mutable state between tests)
+- Cover one specific behavior per test
+
+Priority order for coverage:
+1. Happy path (normal usage)
+2. Edge cases and boundary conditions
+3. Expected error throws (use `expect(() => ...).toThrow(ErrorClass)`)
+4. Non-obvious behaviors from references/non-obvious-behaviors.md
+5. Interaction with `batch`, `untrack`, `unown` if the signal participates in those
+
+## Step 6: Verify
+
+Run the full test suite:
+
+```bash
+bun test
+```
+
+All tests — new and existing — must pass.
+</process>
+
+<success_criteria>
+- Tests cover the specified signal type or behavior
+- Each test is self-contained and has a descriptive name
+- Expected error conditions are tested with the correct error class
+- At least one relevant non-obvious behavior is covered if applicable
+- `bun test` passes with no regressions
+</success_criteria>

package/skills/changelog-keeper/SKILL.md

@@ -1,59 +1,69 @@
 ---
-name: changelog
-description: Update CHANGELOG.md with user-facing changes. Use after meaningful code changes, when asked to add release notes, or to prepare a release.
+name: changelog-keeper
+description: >
+  Maintain CHANGELOG.md for the @zeix/cause-effect library. Use after meaningful code
+  changes, when asked to add release notes, or to prepare a release.
 user_invocable: true
 ---
 
-# Changelog Keeper
-
-Maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com) conventions.
-
-## Structure
+<objective>
+Maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com) conventions,
+adapted to this project's style: technically precise, developer-focused entries that include
+implementation detail when it explains *why* behavior changed or *how* to migrate.
+</objective>
 
+<structure>
 The changelog uses this heading hierarchy:
 
 ```markdown
 # Changelog
 
-## [Unreleased]
+## [Unreleased]        ← only present when unreleased changes exist
 
 ### Added
-### Changed
-### Deprecated
-### Removed
 ### Fixed
-### Security
 
-## 0.18.1
+## 1.0.0              ← released versions use bare version numbers, no brackets
 
-### Added
+### Changed
 ...
 ```
 
-- `## [Unreleased]` is always the first version section. New changes go here.
-- Only include categories that have entries.
-- Version 0.18.0 is the baseline. Do not document changes before it.
-
-## Adding entries
+- `## [Unreleased]` is only present when there are documented changes not yet released.
+  Create it at the top (below `# Changelog`) when documenting the first new change after a release.
+  It does not exist between releases.
+- Released versions use bare version numbers: `## 1.0.0`, `## 0.18.5`, etc. No brackets.
+- Only include category headings (`### Added`, `### Changed`, etc.) that have entries.
+- `## 0.18.0` is the baseline. Do not document changes before it.
+</structure>
 
+<adding_entries>
 1. Read `CHANGELOG.md`.
-2. Determine which changes are user-facing by inspecting the diff (`git diff main..HEAD -- src/ index.ts` or as directed).
-3. Classify each change into exactly one category: Added, Changed, Deprecated, Removed, Fixed, or Security.
-4. Write concise bullets describing user-visible behavior. Use backticks for public API names.
-5. Do not duplicate existing entries.
-6. Edit the file in place using the Edit tool.
-
-## Preparing a release
-
+2. Inspect the diff to identify changes: `git diff main..HEAD -- src/ index.ts` or as directed.
+3. If there is no `## [Unreleased]` section, create one immediately below `# Changelog`.
+4. Classify each change into exactly one category: Added, Changed, Deprecated, Removed, Fixed, or Security.
+5. Write entries following the style guide below.
+6. Do not duplicate existing entries.
+7. Edit the file in place using the Edit tool.
+</adding_entries>
+
+<preparing_a_release>
 When asked to release a version:
 
-1. Move all `[Unreleased]` entries under a new `## X.Y.Z` heading.
-2. Leave an empty `## [Unreleased]` section above it.
-3. Update `version` in `package.json` and the `@version` tag in `index.ts` to match.
-
-## Entry style
-
-- One behavior change per bullet.
-- Factual and concise; skip implementation-only details.
-- Include migration notes under Changed or Removed when behavior breaks compatibility.
-- Bold the API name or short summary at the start: `- **\`createMemo\` \`watched\` option**: description...`
+1. Rename `## [Unreleased]` to `## X.Y.Z` — do not leave an empty `[Unreleased]` section behind.
+2. Update `version` in `package.json` to match.
+3. Update the `@version` tag in `index.ts` to match.
+</preparing_a_release>
+
+<entry_style>
+- **One behavior change per bullet.**
+- **Bold the API name or short summary** at the start, followed by a colon:
+  `- **\`createMemo\` \`watched\` option**: description…`
+- **Include implementation details** when they explain *why* the behavior changed, *how* the
+  fix works, or *what internal invariant* is preserved. This changelog is read by developers
+  and AI agents integrating or contributing to the library — precision is expected.
+- **Use before/after framing for Fixed entries**: "Previously, X. Now, Y."
+- **Include migration notes** under Changed or Removed when behavior breaks compatibility.
+  State clearly what consumers must change and why.
+- Use backticks for all public API names, internal types, flags, and file names.
+</entry_style>

package/skills/tech-writer/SKILL.md

@@ -0,0 +1,94 @@
+---
+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.
+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/`.
+
+For consumer projects using `@zeix/cause-effect` as a dependency, use the `cause-effect`
+skill instead.
+</scope>
+
+<essential_principles>
+**Read source before writing.** Always read the current state of the relevant source file(s)
+and the target document before making any changes. Never update from memory.
+
+**Tone adapts to audience.** Each document has a distinct primary reader and register.
+See references/tone-guide.md. Violating the tone is as wrong as a factual error.
+
+**Concise over comprehensive.** Every sentence must justify its presence. Cut anything
+that does not add information the reader needs. Technical accuracy is non-negotiable;
+length is not.
+
+**Surgical edits only.** Update what changed. Do not rewrite sections that are still
+accurate, and do not add commentary about what was updated.
+</essential_principles>
+
+<intake>
+What do you need to do?
+
+1. **Update after a code change** — `src/` or `index.ts` has changed and documents need
+   to reflect it
+2. **Review consistency** — check that all documents reflect the current source
+3. **Update a specific document** — you know exactly which one
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|---|---|
+| 1, "code changed", "after change", "just merged", "new feature", "bug fix" | workflows/update-after-change.md |
+| 2, "review", "consistency", "check", "audit", "verify" | workflows/consistency-review.md |
+| 3, "specific", or names a document | See document routing below |
+
+**Document-specific routing (option 3):**
+
+| Document named | Workflow |
+|---|---|
+| `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 |
+| `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 JSDoc" / "inline docs" → workflows/update-jsdoc.md
+- "update requirements" → workflows/update-requirements.md
+- "review all docs" / "check consistency" → workflows/consistency-review.md
+
+**After identifying the workflow, read it and follow it exactly.**
+</routing>
+
+<reference_index>
+All in `references/`:
+
+| File | Contents |
+|---|---|
+| document-map.md | Each document's audience, scope, update triggers, and consistency checks |
+| tone-guide.md | Writing tone, register, and conciseness rules per document type |
+</reference_index>
+
+<workflows_index>
+All in `workflows/`:
+
+| Workflow | Purpose |
+|---|---|
+| 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-requirements.md | Update `REQUIREMENTS.md` |
+| update-jsdoc.md | Update JSDoc comments in `src/` |
+| consistency-review.md | Review all documents for consistency with current source |
+</workflows_index>

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

@@ -0,0 +1,199 @@
+<overview>
+Every document the tech-writer skill maintains, with its audience, scope, what triggers an
+update, and what to verify in a consistency review. Load this reference whenever you need
+to determine which documents are affected by a change.
+</overview>
+
+<documents>
+
+<REQUIREMENTS_md>
+**Path:** `REQUIREMENTS.md`
+**Audience:** Stakeholders, potential contributors, library authors evaluating adoption
+**Register:** Formal, strategic, timeless — written to survive version bumps
+**Scope:** Vision, primary and secondary audience, design principles, signal type set,
+runtime environments, bundle size targets, non-goals, stability guarantees
+
+**Update triggers:**
+- A signal type is added to or removed from the library
+- A runtime environment is added or dropped
+- A bundle size target changes
+- A design principle is added, changed, or removed
+- The primary or secondary audience shifts
+- A non-goal is resolved or a new one is established
+- Stability guarantees change (version milestone, compatibility stance)
+
+**Do NOT update for:** bug fixes, new options on existing types, internal refactors,
+documentation or tooling changes.
+
+**Consistency checks:**
+- Signal type count in prose ("9 signal types") matches the table row count
+- Signal type table rows match the exports in `index.ts`
+- Non-goals do not contradict any feature currently in the library
+- Runtime environments list reflects current CI targets
+</REQUIREMENTS_md>
+
+<README_md>
+**Path:** `README.md`
+**Audience:** Developers integrating the library — library authors and framework integrators
+**Register:** Instructional, example-driven, precise — assumes TypeScript competence
+**Scope:** Installation, quick start, full public API reference, signal type selection guide,
+advanced usage patterns (batching, cleanup, scopes, watched callbacks)
+
+**Update triggers:**
+- Any factory function is added, removed, or has a changed signature
+- Any option is added, renamed, removed, or changes semantics
+- Any exported type is added, removed, or renamed
+- A behavioral guarantee changes (e.g. sync vs async execution, equality semantics)
+- A new advanced usage pattern is added to the library
+
+**Consistency checks:**
+- Every factory function in `index.ts` has a `### SignalType` section under `## API`
+- All `@param`-level option names match current factory signatures
+- Code examples in the API sections use current factory signatures and compile
+- "Choosing the Right Signal" table covers all signal types with accurate descriptions
+- "Advanced Usage" examples use current API
+</README_md>
+
+<GUIDE_md>
+**Path:** `GUIDE.md`
+**Audience:** Developers migrating from React, Vue, or Angular
+**Register:** Comparative, educational, approachable — draws explicit parallels to other frameworks
+**Scope:** Conceptual mapping from React/Vue/Angular primitives, key behavioral differences
+(synchronous effects, auto-tracked dependencies, non-nullable types, scope-based ownership),
+and signal types that go beyond what standard frameworks provide
+
+**Update triggers:**
+- A core factory name changes (breaks the "Familiar Core" comparison table)
+- A fundamental behavioral contract changes — sync execution, dependency tracking model,
+  nullability rules, or ownership semantics
+- A new signal type is added that goes "Beyond the Basics"
+- An existing "Beyond the Basics" signal type changes significantly enough that a framework
+  developer's mental model derived from the guide would now be wrong
+
+**Do NOT update for:** new options on existing signal types, minor signature tweaks, internal
+changes, or anything that does not change how a React/Vue/Angular developer would think about
+the library.
+
+**Consistency checks:**
+- "The Familiar Core" table references current factory function names (`createState`,
+  `createMemo`, `createEffect`)
+- "What Works Differently" sections describe current behavior accurately
+- "Beyond the Basics" signal type sections use current factory signatures and options
+- Code examples compile against current `index.ts`
+</GUIDE_md>
+
+<ARCHITECTURE_md>
+**Path:** `ARCHITECTURE.md`
+**Audience:** Contributors to the library; AI agents reasoning about internals
+**Register:** Technical, precise, internal-facing — implementation details are expected and correct
+**Scope:** Graph engine data structures (edges, node field mixins, concrete node types),
+automatic dependency tracking (`activeSink`, `link`, `trimSources`, `unlink`), change
+propagation (flag semantics, `propagate`, `refresh`, `setState`), effect scheduling (`batch`,
+`flush`), ownership and cleanup (`activeOwner`, cleanup storage, `createScope`), and a
+per-signal-type subsection describing each type's internal composition and lifecycle
+
+**Update triggers:**
+- The `Edge` type fields change
+- Node field mixins (`SourceFields`, `SinkFields`, `OwnerFields`, `AsyncFields`) change
+- A concrete node type is added, removed, or its composition changes
+- `activeSink` or `activeOwner` semantics change
+- `link()`, `trimSources()`, or `unlink()` behavior changes
+- Flag names or values change (`FLAG_CLEAN`, `FLAG_CHECK`, `FLAG_DIRTY`, `FLAG_RUNNING`)
+- `propagate()`, `refresh()`, `setState()`, `batch()`, or `flush()` behavior changes
+- A new signal type is added (add a subsection) or removed (remove its subsection)
+
+**Consistency checks:**
+- "Concrete Node Types" table matches node shapes defined in `src/graph.ts`
+- "Node Field Mixins" table matches field groups in `src/graph.ts`
+- Flag names match constants in `src/graph.ts`
+- Each signal type subsection describes current internal composition and lifecycle
+- No subsection references a removed type, flag, or function
+</ARCHITECTURE_md>
+
+<CLAUDE_md>
+**Path:** `CLAUDE.md`
+**Audience:** Claude (this model) at inference time
+**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
+
+**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
+
+**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
+
+**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>
+
+<jsdoc_in_src>
+**Path:** `src/nodes/*.ts`, `src/graph.ts`, `src/errors.ts`, `src/util.ts`, `src/signal.ts`
+**Audience:** IDE users (hover documentation), API consumers reading source
+**Register:** Brief, typed, precise — one-line summaries; `@param`/`@returns` only
+**Scope:** Public API functions and their parameters, return values, and non-obvious
+constraints. Internal helpers do not require JSDoc.
+
+**Update triggers:**
+- A public function's parameter is added, removed, renamed, or retyped
+- A public function's return value or semantics change
+- A public function is removed (remove its JSDoc block with it)
+
+**Consistency checks (spot-check):**
+- `@param` names match current parameter names in the function signature
+- `@returns` descriptions match current return type semantics
+- No `@param` tags reference removed parameters
+- No `@example` blocks use deprecated API
+</jsdoc_in_src>
+
+</documents>
+
+<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 | —     | —    | —                | —      | —     | ✓ |
+
+\* For REQUIREMENTS.md: only the signal type table row. Not the prose count — update
+that to match automatically.
+</change_to_document_matrix>