Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
175 commits
Select commit Hold shift + click to select a range
6062408
chore: update skills
clfhhc May 28, 2026
6ddd6ac
feat(ts): introduce @graphrefly/ts package with TypeScript support
clfhhc May 29, 2026
997ba4a
refactor(ts): clean up imports and enhance test structure
clfhhc May 29, 2026
05d15b4
chore: update conformance and design-review SKILL documentation
clfhhc May 29, 2026
633bf87
refactor: update design-review and dev-dispatch SKILL documentation f…
clfhhc May 29, 2026
4c26773
feat(tests): add comprehensive intra-graph rewire tests and enhance n…
clfhhc May 29, 2026
44e9d54
feat(qa): enhance QA workflow documentation and improve rewire functi…
clfhhc May 29, 2026
9e3a7c1
feat(ts): enhance graph operators and add async source functionality
clfhhc May 29, 2026
7434e69
refactor(tests): update dynamicNode and conformance tests for DATA ha…
clfhhc May 30, 2026
f79a6f0
feat(ts): implement higher-order operators and rewire functionality
clfhhc May 30, 2026
ed78645
feat(ts): add combinators and time operators to enhance graph functio…
clfhhc May 31, 2026
f366a5b
feat(ts): add agent context and skills documentation for GraphReFly
clfhhc May 31, 2026
997c7d0
feat(ts): enhance reactive data structures and time operators
clfhhc May 31, 2026
1f24154
fix(docs): update AGENTS.md and skills path for clarity
clfhhc May 31, 2026
97311b6
feat(tests): expand conformance tests and enhance batch functionality
clfhhc May 31, 2026
8ede353
feat(ts): add composition helpers and stratification functionality
clfhhc Jun 1, 2026
8561463
feat(ts): introduce internal collection policy helpers and enhance da…
clfhhc Jun 1, 2026
e5c884c
feat(ts): enhance reactive data structures with capacity policies and…
clfhhc Jun 1, 2026
3ea234a
fix lint
clfhhc Jun 1, 2026
188cd2e
feat(ts): add maxSize capacity policy to reactiveIndex and enhance AG…
clfhhc Jun 1, 2026
d85bd50
feat(tests): enhance higher-order and operator tests for batch proces…
clfhhc Jun 2, 2026
db645bf
feat(ts): add new exports for observe sink types and attachObserveSin…
clfhhc Jun 2, 2026
15b4d0f
feat(ts): add rendering functions and tests for DescribeSnapshot
clfhhc Jun 2, 2026
4f57c11
feat(ts): implement NodeCore and refactor Node class for improved sta…
clfhhc Jun 2, 2026
f6c0e4c
D77
clfhhc Jun 2, 2026
a644651
feat(ts): enhance graph and node management with NodeCore integration
clfhhc Jun 2, 2026
bedfd9d
feat(ts): implement deferred boundary task management in NodeCore
clfhhc Jun 2, 2026
e7a006e
refactor(ts): enhance Node and NodeCore with lifecycle and sync conte…
clfhhc Jun 2, 2026
3384167
feat(ts): add TypeScript probe for performance measurement
clfhhc Jun 2, 2026
7b8fc57
refactor(ts): transition NodeCore to use indexed arrays for state man…
clfhhc Jun 2, 2026
f2ece8f
feat(ts): enhance graph sources with new operators and tests
clfhhc Jun 2, 2026
e36f7c6
feat(ts): expand TypeScript package structure with new modules and te…
clfhhc Jun 2, 2026
1a6c447
feat(ts): enhance TypeScript package with new policy types and tests
clfhhc Jun 3, 2026
700c728
feat(tests): add error handling tests for async and sync iterators
clfhhc Jun 3, 2026
2ee8028
feat(tests): enhance data structure tests with new scenarios
clfhhc Jun 3, 2026
3cc96ba
feat(ts): enhance storage and logging capabilities with new append-lo…
clfhhc Jun 3, 2026
01a3aed
feat(ts): enhance storage capabilities with content-addressed KV and …
clfhhc Jun 3, 2026
489dd92
feat(ts): introduce strict JSON codec and enhance timestamp handling
clfhhc Jun 3, 2026
47f4365
feat(ts): add multi-writer append log and conditional-create capabili…
clfhhc Jun 3, 2026
b5a8b3d
feat(ts): introduce graph checkpointing and restore functionality
clfhhc Jun 3, 2026
338af17
feat(ts): implement graph restore functionality and enhance checkpoin…
clfhhc Jun 3, 2026
89edad4
feat(ts): enhance graph restoration and operator functionality
clfhhc Jun 3, 2026
d63dfd0
feat(ts): introduce define operator and enhance graph restoration
clfhhc Jun 3, 2026
a980c9e
feat(ts): add web storage backend and enhance storage functionality
clfhhc Jun 3, 2026
339ce8a
feat(ts): implement tiered read-through functionality and related types
clfhhc Jun 3, 2026
08fc9f8
feat(ts): add WAL frame functionality and append-log page reading
clfhhc Jun 3, 2026
cb212c5
feat(ts): add reactive cascading cache and browser storage backend
clfhhc Jun 3, 2026
40717c3
feat(tests): enhance IndexedDB testing and mock functionality
clfhhc Jun 4, 2026
fe63b1f
qa
clfhhc Jun 4, 2026
f6a668c
feat(ts): implement node versioning and enhance storage capabilities
clfhhc Jun 4, 2026
41fd763
qa
clfhhc Jun 4, 2026
920373d
feat(tests): enhance graph and node versioning tests
clfhhc Jun 4, 2026
c29b79f
feat(tests): add conformance tests for deferred boundary tasks
clfhhc Jun 4, 2026
4e0695b
feat(ts): enhance node versioning and testing capabilities
clfhhc Jun 4, 2026
8946b30
feat(tests): enhance node and graph versioning tests with strict JSON…
clfhhc Jun 4, 2026
354dac9
feat(ts): introduce strict canonical JSON byte handling for versioning
clfhhc Jun 4, 2026
b6b0727
feat(tests): enhance storage tests with versioned read and write capa…
clfhhc Jun 4, 2026
34c7c7e
feat(tests): expand storage tests for append log functionality
clfhhc Jun 4, 2026
f215bc7
feat(tests): enhance storage backend tests for key validation and err…
clfhhc Jun 4, 2026
31bc14a
feat(tests): enhance content-addressed KV tests for key handling and …
clfhhc Jun 5, 2026
6e8d990
feat(tests): improve storage tests for append log and change envelope…
clfhhc Jun 5, 2026
af9896c
feat(tests): enhance combinators and operators tests for error handli…
clfhhc Jun 5, 2026
48f873d
feat(ts): add LICENSE file and update package description
clfhhc Jun 5, 2026
03e9094
refactor(ts): update rewire methods for improved clarity and consistency
clfhhc Jun 5, 2026
632cb04
feat(ts): add graph diagnostics utilities and tests
clfhhc Jun 5, 2026
cfb907a
feat(ts): add node-only sources and enhance mergeMap functionality
clfhhc Jun 5, 2026
3a3ec74
feat(ts): introduce pipe operator for operator composition
clfhhc Jun 6, 2026
595348b
feat(ts): enhance sources with event handling and first value resolution
clfhhc Jun 6, 2026
4407fda
feat(ts): update build process and add peer dependency for @graphrefl…
clfhhc Jun 6, 2026
b3f5e24
feat(ts): enhance observability with new observe helpers and update t…
clfhhc Jun 6, 2026
14fd93d
feat(ts): introduce reactive views for enhanced data handling
clfhhc Jun 6, 2026
aba0c0a
feat(ts): implement viewCache for reactive data structures
clfhhc Jun 6, 2026
4a8e7bd
refactor(ts): migrate examples and documentation to @graphrefly/ts
clfhhc Jun 7, 2026
9306cb5
feat(ts): add new adapters and CQRS namespace for enhanced functionality
clfhhc Jun 7, 2026
9b43534
feat(ts): enhance sources with cron functionality and browser support
clfhhc Jun 7, 2026
a4f1612
feat(tests): add strict JSON number validation and enhance graph stat…
clfhhc Jun 7, 2026
aefa0db
feat(tests): add patterns inspection helpers and corresponding tests
clfhhc Jun 7, 2026
3788cde
feat(ts): enhance environment drivers and add new source functionalities
clfhhc Jun 7, 2026
ab41c08
feat(ts): enhance environment drivers and add resilience features
clfhhc Jun 8, 2026
06cf92b
feat(ts): add nodeProcessDriver for enhanced process management
clfhhc Jun 8, 2026
3f1eb29
feat(ts): introduce WebSocket session management for enhanced real-ti…
clfhhc Jun 8, 2026
cb69148
feat(ts): introduce wire bridge envelope system for enhanced data com…
clfhhc Jun 8, 2026
5901306
feat(ts): implement dynamic hub for flexible topic management in mess…
clfhhc Jun 8, 2026
234b338
feat(tests): add comprehensive CQRS tests for command handling and ev…
clfhhc Jun 8, 2026
ff5f79c
feat(ts): add topology event system for enhanced graph lifecycle obse…
clfhhc Jun 9, 2026
367a011
feat(ts): introduce TopologyGroup for enhanced graph lifecycle manage…
clfhhc Jun 9, 2026
b87eaa9
feat(ts): enhance graph topology management with mounted child event …
clfhhc Jun 9, 2026
36bd1ac
feat(ts): introduce worker-derived helpers for backend processing
clfhhc Jun 9, 2026
6269cf4
feat(ts): enhance messaging with standard topic constants and JSON sc…
clfhhc Jun 9, 2026
22d198e
feat(ts): migrate examples to use @graphrefly/ts package
clfhhc Jun 9, 2026
d21158a
feat(tests): add semantic memory tests for validation and filtering
clfhhc Jun 9, 2026
ca5ee4b
feat(tests): enhance graph checkpoint tests for D160 collection backe…
clfhhc Jun 10, 2026
8f07b26
feat(ts): enhance reactive collection persistence and restore functio…
clfhhc Jun 10, 2026
6239478
feat(ts): introduce agentic memory solution and related types
clfhhc Jun 11, 2026
4a38c6c
feat(ts): expand agentic memory types and enhance testing
clfhhc Jun 11, 2026
9fc0b3d
feat(ts): expand agentic memory storage and knowledge graph capabilities
clfhhc Jun 11, 2026
8ab7c8c
refactor(ts): retire @graphrefly/graphrefly package and update docume…
clfhhc Jun 11, 2026
6a123b0
refactor(ts): remove @graphrefly/cli package and update related docum…
clfhhc Jun 11, 2026
3231d22
feat(ts): introduce topology() method for pure structure snapshots
clfhhc Jun 11, 2026
0379069
feat(ts): enhance graph blueprint functionality and add new types
clfhhc Jun 11, 2026
c605cbd
Add D181 reactive layout solution
clfhhc Jun 11, 2026
55e8a08
refactor(ts): update reactive layout to use @graphrefly/ts package
clfhhc Jun 12, 2026
deeb8da
refactor(ts): update reactive layout to utilize graph-visible measure…
clfhhc Jun 12, 2026
2e26cb8
feat(ts): add new reactive layout subpaths for NodeCanvas, React Nati…
clfhhc Jun 13, 2026
3973504
feat(ts): add readiness, image size, and SVG bounds measurement provi…
clfhhc Jun 13, 2026
2ecc860
feat(ts): add optional peer dependency for canvas and enhance measure…
clfhhc Jun 13, 2026
56890cf
feat(docs): add README files for reactive-layout examples and recipes
clfhhc Jun 13, 2026
b713281
feat(tests): add comprehensive tests for agent runtime functionality
clfhhc Jun 13, 2026
5c209e2
feat(tests): expand agent runtime tests with new WorkItem mappings
clfhhc Jun 13, 2026
dd2a3fd
feat(tests): enhance agent runtime tests and introduce work-item runtime
clfhhc Jun 13, 2026
b76b95d
feat(tests): implement WorkItem domain action proposal tests and enha…
clfhhc Jun 13, 2026
b4535eb
feat(frameworks): update GraphReFly bindings for React, Solid, Svelte…
clfhhc Jun 13, 2026
62cf337
chore(docs): update framework example READMEs and add TypeScript pack…
clfhhc Jun 13, 2026
094d5ab
feat(ts): add work-queue support and update pull demand handling
clfhhc Jun 15, 2026
81a1149
feat(ts): implement event-flow pattern and related tests
clfhhc Jun 15, 2026
cf6da02
feat(tests): add conformance tests for PULL and RESUME handling
clfhhc Jun 16, 2026
e1e824e
feat(ts): add work-queue executors and related tests
clfhhc Jun 16, 2026
90ffe99
feat(ts): add work-item scheduling functionality and related tests
clfhhc Jun 16, 2026
73e7dc4
feat(ts): add work-item actions module and related tests
clfhhc Jun 16, 2026
c313ee1
feat(ts): enhance CQRS and orchestration capabilities with messaging …
clfhhc Jun 16, 2026
517c509
feat(ts): implement capability admission solution and related tests
clfhhc Jun 16, 2026
42be5ac
feat(ts): enhance work-item capability admission and scheduling tests
clfhhc Jun 17, 2026
63f6173
feat(ts): enhance agent runtime and orchestration with new projectors…
clfhhc Jun 17, 2026
3dec14a
chore(ts): update package versions and deprecate root package
clfhhc Jun 17, 2026
3a39cfc
feat(ts): enhance agent runtime with tool provider execution policies…
clfhhc Jun 17, 2026
55fd19b
feat(ts): enhance agent runtime with tool provider adapter functional…
clfhhc Jun 17, 2026
836b3bd
feat(ts): enhance agent runtime with tool provider adapter run functi…
clfhhc Jun 17, 2026
e79f0d3
feat(ts): enhance agent runtime with retention policies and related t…
clfhhc Jun 17, 2026
2517368
feat(ts): add diagnostics for closed retention evidence in agent runtime
clfhhc Jun 17, 2026
4d7a1cf
feat(ts): enhance agent runtime with retention scorer and request san…
clfhhc Jun 17, 2026
ab3934e
feat(ts): enhance agent runtime with improved data sanitization and p…
clfhhc Jun 18, 2026
ba31ffb
feat(ts): enhance agent runtime with comprehensive request sanitizati…
clfhhc Jun 18, 2026
eae0333
feat(ts): enhance agent runtime with improved request handling and sa…
clfhhc Jun 18, 2026
9bb3108
feat(ts): enhance agent runtime with refined retention gap handling a…
clfhhc Jun 18, 2026
4485c16
split long files
clfhhc Jun 18, 2026
7071d61
feat(ts): add comprehensive tests for agent runtime functionalities
clfhhc Jun 18, 2026
a5d320f
feat(deps): add graphrefly-canvas demo with dependencies
clfhhc Jun 18, 2026
1cdd4b6
feat(astro): add favicon link to index page
clfhhc Jun 18, 2026
41f2d16
refactor(graphrefly-canvas): remove demo files and configurations
clfhhc Jun 18, 2026
a2dc4de
refactor(ts): streamline agent runtime by removing unused adapter run…
clfhhc Jun 18, 2026
6a6cccc
feat(ts): enhance work item spawn actions with idempotency and valida…
clfhhc Jun 20, 2026
642876d
feat(ts): introduce workspace model for work item scheduling and enha…
clfhhc Jun 20, 2026
c6fa75a
feat(ts): add tool provider execution and runtime modules with tests
clfhhc Jun 21, 2026
e88305c
feat(ts): add tool provider adapters and enhance orchestration types
clfhhc Jun 21, 2026
c31ccb8
feat(ts): implement tool provider run retry functionality with tests
clfhhc Jun 21, 2026
cd5c684
feat(ts): add scheduled readiness functionality with comprehensive tests
clfhhc Jun 22, 2026
0135140
feat(ts): enhance work queue scheduled readiness functionality with t…
clfhhc Jun 22, 2026
ba41a7d
feat(ts): implement durable handoff diagnostics in workspace proposal…
clfhhc Jun 22, 2026
479c5e7
feat(ts): add diagnostics and repair review functionalities for works…
clfhhc Jun 22, 2026
3bda946
feat(ts): enhance workspace proposal repair review functionalities an…
clfhhc Jun 22, 2026
caa8bdc
feat(ts): add workspace proposal repair review controls
clfhhc Jun 22, 2026
1e84ea2
refactor(ts): update package references and enhance documentation
clfhhc Jun 22, 2026
3ef35b9
feat(ts): enhance workspace proposal family applications with new fun…
clfhhc Jun 23, 2026
d0f7a6e
feat(ts): introduce WorkspaceProposalProjectionRelease and related fu…
clfhhc Jun 23, 2026
5d6030a
feat(ts): add NestJS integration example and enhance biome configuration
clfhhc Jun 23, 2026
0bfacf1
feat(ts): enhance workspace proposal projection functionalities with …
clfhhc Jun 23, 2026
27acbae
feat(ts): enhance NestJS integration with D478 decorators and boundar…
clfhhc Jun 23, 2026
9a14080
feat(ts): enhance NestJS integration with D484 native provider bridge
clfhhc Jun 24, 2026
32f5e1c
feat(ts): enhance NestJS integration with D486 provider bridges and g…
clfhhc Jun 24, 2026
64adbbe
refactor(ts): remove deprecated SESSION-blueprint-stacked-pr-ownershi…
clfhhc Jun 24, 2026
7ed5f04
feat(ts): enhance NestJS integration with D488 WebSocket and microser…
clfhhc Jun 24, 2026
b36836d
feat(ts): enhance NestJS integration with WebSocket and microservice …
clfhhc Jun 24, 2026
f113c07
feat(ts): enhance NestJS integration with D494 provider ergonomics an…
clfhhc Jun 24, 2026
4cee6b0
feat(ts): update NestJS integration to D495 provider ergonomics and d…
clfhhc Jun 24, 2026
bdf05e8
feat(docs): update NestJS integration documentation and examples for …
clfhhc Jun 24, 2026
c6d8277
feat(compat-matrix): integrate new framework adapters and update depe…
clfhhc Jun 24, 2026
621f2d8
refactor(demos): update examples and remove deprecated demos
clfhhc Jun 25, 2026
2898486
feat(ts): introduce wireBridgeProtobuf for enhanced protobuf handling
clfhhc Jun 25, 2026
541ce62
feat(ts): enhance wireBridgeProtobuf with inbound event handling and …
clfhhc Jun 25, 2026
fea43c4
feat(ts): enhance wire bridge with ack-timeout command handling and e…
clfhhc Jun 25, 2026
fc9c4af
feat(ts): enhance wireEdgeGroup with cause tombstone management and r…
clfhhc Jun 26, 2026
24f70ea
refactor(demos): remove knowledge-graph demo and associated files
clfhhc Jun 27, 2026
a0d2fec
change all package reference
clfhhc Jun 27, 2026
903026f
refactor(pure-ts): remove deprecated package and associated files
clfhhc Jun 27, 2026
9c43312
chore: fix tests
clfhhc Jun 27, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
61 changes: 61 additions & 0 deletions .agents/skills/conformance/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
name: conformance
description: "Behavioral conformance check across GraphReFly language runtimes (ts/rust/py) for the clean-slate redesign. Replaces the old structural 'parity' diff. Parity = does each runtime satisfy the wave-protocol behavior (conformance scenarios) + dispatcher contract — NOT 'do the symbol sets match'. Use after implementing/changing substrate behavior in any runtime, or when adding a new protocol rule. Authors/runs language-agnostic scenarios and updates conformance.jsonl runtime status. Triggers: 'conformance', 'cross-lang check', 'does rust match', 'parity', 'run the conformance suite', 'is the substrate behavior consistent'."
argument-hint: "[rule-id | scenario-id | 'full'] [optional: runtime ts|rust|py]"
---

You are executing **conformance** for the clean-slate GraphReFly redesign.

**Parity is behavioral, not structural (D24).** There is NO `Impl` symbol-set to diff and NO
cross-track-ledger. Operators / sugar / inspection are **per-language and never in parity**
(D6/D27 — graph-layer wraps everything to `(ctx)=>void` before register). The ONLY parity
surface is: **wave-protocol behavior + dispatcher contract + handle format**. Conformance =
each runtime passes the same language-agnostic scenarios.

## Authority

| Source | Role |
|---|---|
| `~/src/graphrefly/spec/conformance.jsonl` | The scenario registry: `{id, name, covers:[rule-id], runtimes:{ts,rust,py}, status, note}`. |
| `~/src/graphrefly/spec/rules.jsonl` | The rules scenarios pin (`covers` must resolve here). |
| `~/src/graphrefly/spec/protocol.proto` | Protocol-contract IDL (DR-2) — the light structural anchor codegen'd into each runtime's interface stub. |
| `~/src/graphrefly/formal/*.tla` | TLA+ model (γ); property tests mirror its invariants. |

## Scope from $ARGUMENTS

- **rule-id** (e.g. `R-diamond`) → all scenarios whose `covers` includes it.
- **scenario-id** (e.g. `C-1`) → that scenario.
- **full** → every `status:"required"` scenario.
- optional **runtime** → restrict to one arm.

## Phase 1 — scenario integrity

1. Load `conformance.jsonl` + `rules.jsonl`. Verify every `covers` rule-id resolves (else HALT — fix the scenario or add the rule via `/spec-amend`).
2. List the **DR-5 required hard scenarios** and their status: `C-1` cross-graph diamond, `C-2` async-result-at-paused-node, `C-3` INVALIDATE×ctx.state×onInvalidate, `C-4` mixed sync/async diamond, `C-5` PAUSE-lockset multi-source. These are the load-bearing ones — behavioral parity is a blank cheque until they're green on each shipped runtime.

## Phase 2 — run / verify per runtime

For each in-scope `(scenario, runtime)`:
1. Locate/author the scenario harness in that runtime's conformance test dir (language-agnostic spec → per-runtime adapter; the scenario describes observable wave behavior, not a symbol call).
2. Run it. Record outcome.
3. Update `conformance.jsonl` `runtimes.<rt>`: `"todo" | "poc-pass" | "pass" | "fail"`.
4. Mirror the invariant as a property test (fast-check ts ↔ proptest rust ↔ hypothesis py) where the rule is property-shaped (L5-Q2 / D14).

## Phase 3 — report

| scenario | covers | ts | rust | py | verdict |
|---|---|---|---|---|---|

- **Behavior drift** = same scenario, different observable outcome across runtimes → this is the ONLY kind of parity gap. File it as a substrate bug in the lagging runtime (route fix via `/dev-dispatch` on that package).
- **Missing scenario** for a rule (rule's `covers_by` empty) → author it (this is the real risk under behavioral parity: untested behavior can drift silently — D24 residual). Flag via `/dashboard` Gaps (uncoveredRules).
- **NOT a gap:** a runtime having a different operator set / different sugar / different inspection ergonomics. Those are per-language by design — do not report them.

## Phase 4 — gate

Run `node ~/src/graphrefly/dashboard/build.mjs --check` (scenario↔rule links intact). For a runtime
to be declared "conformant", all `status:"required"` scenarios must be `"pass"` on its arm.

## Boundaries

Does NOT diff symbol sets (that's the retired structural model). Does NOT touch operators/sugar/inspection
(per-language). New protocol behavior must go through `/spec-amend` FIRST (scenario authored before code).
33 changes: 33 additions & 0 deletions .agents/skills/dashboard/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
name: dashboard
description: "Build / check the GraphReFly internal docs dashboard (jsonl single-source -> generated HTML with progress, structure map, gaps, search). Use when the user wants to see global project state, regenerate the dashboard, run the docs consistency gate (broken links / orphans / coverage gaps), or after editing any jsonl in ~/src/graphrefly (decisions/plan/spec/sessions/guide). Triggers: 'build the dashboard', 'check docs consistency', 'what are the gaps', 'show progress', 'regenerate dashboard', 'doc gate'."
argument-hint: "[--check (gate only) | (default: build + report)]"
---

You are executing **dashboard** for the clean-slate GraphReFly redesign.

**Repo:** `~/src/graphrefly` (clean-slate branch). All structured docs are jsonl (single source of truth, decision 2); the dashboard renders them into one searchable HTML view for the maintainer (decision 3). Schema contract: `~/src/graphrefly/dashboard/README.md`.

## What this skill does

1. **Run the generator:**
- `node ~/src/graphrefly/dashboard/build.mjs` → writes `dashboard/dashboard.html` + prints counts / gaps / broken-links / orphans report.
- `node ~/src/graphrefly/dashboard/build.mjs --check` → consistency gate only; **non-zero exit on broken links** (use as a pre-commit / CI gate).
2. **Interpret the report** for the user:
- **counts** — per-jsonl row counts (decisions/phases/rules/conformance/...).
- **gaps** — designPhases (status=design|gap) · openDecisions · deferredBacklog · uncoveredRules (no conformance) · todoConformance (runtimes=todo). This answers "哪里还有缺口".
- **broken links** — must be zero (session.locks → decision; phase.sessions → session; conformance.covers → rule; flowchart.explains → rule|D#). Legacy 3-digit D### / R# refs are external (old main), reported separately as OK.
- **orphans** — decisions referenced by no session (informational).
3. **If broken links exist:** locate the offending jsonl row, fix the id reference (or add the missing record), re-run `--check`.

## When the jsonl changed

After any edit to `decisions/`, `plan/`, `spec/`, `sessions/`, `guide/` jsonl — run `--check` to catch dangling references immediately (fixes P4 stale-premise + P6 link-rot). The generator is the enforcement mechanism for "single canonical, no broken cross-refs."

## UI styling

`build.mjs` emits a **placeholder shell** with the data model embedded. Visual design / interactive search is a separate `/frontend-design` pass — do NOT hand-style the HTML here; keep `build.mjs` focused on the data model + consistency checks. The dogfood endgame (phase CSP-8) rebuilds this dashboard *with GraphReFly itself* (jsonl producer → reactive views → HTML effect).

## Output

The counts + gaps + link-health report, a plain-language "where are the gaps / what's the progress" summary, and (unless `--check`) confirmation that `dashboard.html` was written. Flag any broken link as a blocker to fix before commit.
87 changes: 87 additions & 0 deletions .agents/skills/decision-guard/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
name: decision-guard
description: "GraphReFly clean-slate decision-consistency check. Loads the user's locked values/principles + the unified D-numbered decision log (decisions.jsonl) + recurring decision-process patterns. Use BEFORE answering any question of the form 'is this consistent with our decisions?', 'should I pick option A/B/C?', 'what about this proposed fix?', 'is X part of our scope?', 'is this a regression on a prior decision?'. Triggers: 'decision check', 'drift check', 'align check', 'is this consistent', 'should I pick', 'what about this', 'is this in scope', 'consistency review'."
argument-hint: "[short context of what you're being asked about — paste the proposal if relevant]"
---

# decision-guard — recall and apply locked decisions, values, invariants (clean-slate)

**Purpose.** Conversations lose context-window state quickly. This is the canonical recall
surface for the **clean-slate** redesign: invoke BEFORE answering decision questions to anchor
against the user's locked positions and prevent silent drift — especially when a chat proposes
a scope expansion mid-implementation, presents A/B/C as a fork, uses "completeness" to justify
expanding a locked slice, or builds on a premise that may be stale.

> **Clean-slate retired the old port model.** Do NOT reach for `rust-port-decisions.md`,
> `cross-track-ledger.md`, the `Impl` parity contract, `BindingBoundary`, the actor model, or
> 3-digit D### port decisions — those are old-`main` history. The clean-slate decision
> authority is below.

## Sources (load in order)

| Source | Role |
|---|---|
| `~/src/graphrefly/decisions/decisions.jsonl` | **Unified D# log** (D1–D33 + DR-*). Canonical record: `{id, layer, question, decision, rationale, supersedes, status}`. |
| `~/src/graphrefly/sessions/active/SESSION-clean-slate-redesign.md` (DS-1) | Full design narrative + 8 forced constraints + spec-amendment list + conformance hard scenarios. |
| `~/src/graphrefly/plan/antipatterns.jsonl` | Lessons / anti-patterns to flag against. |
| `~/src/graphrefly/spec/rules.jsonl` | Protocol rules — for "does the spec already pin this?". |
| Memory `feedback_*` files | The user's durable values/principles (below). |

## Locked values (durable — cite by name)

1. **No backward compat** (pre-1.0): structurally cleaner option, no legacy shims. `feedback_no_backward_compat`.
2. **No imperative triggers** in public API: reactive `ctx.up`/signals, not emitters/callbacks/timers+set; remove imperative paths when no caller depends. `feedback_no_imperative`.
3. **Single source of truth**: one canonical per concern; index points, never duplicates. `feedback_single_source_of_truth`.
4. **No autonomous decisions** (hard rule): surface spec↔code conflicts; don't silently pick; file-by-file review for multi-file rewrites. `feedback_no_autonomous_decisions`.
5. **No implement without approval**: decisions locked ≠ implementation approved. `feedback_no_implement_without_approval`.
6. **Verify premise before greenfield**: design tables lag code — grep symbols + check landed markers before a 9Q; stale premise = HALT. `feedback_verify_premise_before_greenfield`.
7. **Latest versions + context7** for current API docs. `feedback_latest_versions_context7`.
8. **Long-command observation discipline** (run-logged + DONE sentinel; no tail; no sleep-poll) and **subagent bg hygiene** (sync-verify or teardown before return). `feedback_long_command_observation`, `feedback_subagent_bg_hygiene`.

## Clean-slate floor (never violate)

**Sacred (L0.7):** topology declarative/serializable/inspectable · wave protocol is a public spec ·
wave protocol impl is **sync** · all fn go through dispatcher.

**Forced (F-*):** F-PERF (budget every abstraction) · F-PROTO-SPEC (spec+TLA++property) ·
F-SYNC-CORE (dispatcher.invoke sync void) · F-DISPATCH-ALL (no inline-fn bypass) ·
F-GRAPH-FIRST-API · F-NO-WEDGE-CUT (every primitive ≥2 segments) ·
F-NO-IMPL-DEFINED (spec-locked or explicitly undefined-by-design) · F-NO-LLM-ONLY.

**Red flags (HALT if proposed):** async in the sync wave core (async lives only in pools/wire-bridge) ·
inline-fn bypassing dispatcher · a primitive serving only LLM workflows · a protocol behavior left
"implementation-defined" · user-replaceable onMessage/onSubscribe · adding a 10th tier casually ·
graph-level shared mutable state accessed implicitly (must be explicit node + dep).

## Decision-process patterns (apply in order)

1. **Identify the governing D#.** Grep `decisions.jsonl` by `layer`/keyword. Is the proposal within a locked D's scope? Mid-implementation scope expansion = anti-pattern unless promoted to a NEW D#.
2. **Check the spec.** Does `rules.jsonl` pin the behavior? If yes, follow it — divergence is a bug, not a design call. If silent/ambiguous → real design HALT.
3. **Verify premise (value 6).** Has the symbol/surface already landed? grep before designing new surface.
4. **Apply values + floor.** Especially: no autonomous decisions, no imperative, single source of truth, sync-core/async-at-boundary, F-* constraints.
5. **Verdict:** `consistent (cite D#)` / `regression on D#` / `out-of-scope` / `needs new decision (don't auto-pick)`.
6. **Routing:**
- New fork, no governing D# → present options + recommend, **do NOT lock** → that's `/design-review` → user approval → append `decisions.jsonl`.
- Changes protocol behavior → `/spec-amend` (spec-first).
- Cross-runtime parity concern → `/conformance` (behavioral scenario, not structural diff).

## Common decision shapes

- **A/B/C (fix shape):** default = the option that **structurally extends an existing pattern** beats per-site workarounds.
- **Completeness vs discipline:** if a proposal closes a real semantic gap → formalize as a NEW D# (don't continue under the original D's banner). If speculative scope expansion → revert.
- **Orthogonal sub-decisions:** before locking two "orthogonal" sub-decisions, sketch ONE input exercising BOTH — confirm orthogonality survives the example (antipatterns.jsonl; the 30-second check that catches coupling at design-time).

## Scope boundaries

Read-mostly. Loads decisions + values + patterns; produces **decision + reasoning + relay-ready text**.
Does NOT run gates, apply fixes, or author scenarios — those are `/dev-dispatch` / `/qa` / `/conformance`
after a decision locks. Invoke when the question is "what should I decide?", not "what should I do?".

## Update protocol

When a new D# locks (after user approval): append to `~/src/graphrefly/decisions/decisions.jsonl`
(`{id, layer, date, question, decision, rationale, supersedes, status:"locked", session}`), update the
session's `locks` in `sessions.jsonl`, and run `node ~/src/graphrefly/dashboard/build.mjs --check`.
When a new anti-pattern recurs: append to `~/src/graphrefly/plan/antipatterns.jsonl` (+ a `feedback_*`
memory if generalizable). When a new durable value surfaces: add a `feedback_<name>.md` memory + a
pointer line here.
Loading