diff --git a/docs/hygiene-history/ticks/2026/05/03/0149Z.md b/docs/hygiene-history/ticks/2026/05/03/0149Z.md new file mode 100644 index 000000000..cc9acf1df --- /dev/null +++ b/docs/hygiene-history/ticks/2026/05/03/0149Z.md @@ -0,0 +1 @@ +| 2026-05-03T01:49:00Z | opus-4-7 / autonomous-loop continuation | a2e2cc3a | **Decision-archaeology worked example #3 (BP-24 attribution + sacred-tier) authored + landed PR #1264; Aaron's "do we end up with a decision graph?" question answered + captured as substrate (PR #1265).** Cycle worked: PR #1260 merged b8b975bc with 0 actionable threads (gate-tool count discrepancy resolved as not-real-issue); pivoted to advance Aarav's BP-14 with worked example #3 (BP-24 deceased-family-emulation consent-gate, attribution-archaeology + sacred-tier substrate handling). All 11 layers walked respectfully — sacred-tier nodes cited by path only, not reproduced. 3/3 worked examples now landed; skill-creator can author SKILL.md with 3 distinct sub-modes empirically grounded. Aaron mid-tick observation: *"do we end up with some decision graph or something because of the archeologies and flywheel?"* — yes; the substrate already encodes a typed-edge provenance graph (DataVault-2.0-shaped, PROV-O analogue): nodes = backlog rows / ADRs / memos / skills / personas / research / tick shards / commits; edges = depends_on / composes_with / supersedes / cites / verifies-against / attributes-to / closes / composes_in_skill_domain_with. The archaeologies + flywheel + disciplines make the implicit graph queryable: decision-archaeology = traversal; substrate-claim-checker = invariant; flywheel = growth; at-creation/at-pickup = edge-fill; hub-satellite = stratification. No separate graph database needed — every edge already encoded somewhere. Cron a2e2cc3a still armed. | #1260 (substrate-claim-checker v0.4.4) merged b8b975bc; #1263 (worked example #2) wait-ci, auto-merge armed; #1264 (worked example #3) opened, auto-merge armed; #1265 (decision-graph emergent memo) opened, auto-merge armed | This tick teaches the operational pattern of recognize-the-emergent-architecture: Aaron's question named a property that was already implicit in the substrate. The 5 architectural disciplines already in flight (archaeologies + flywheel + creation/pickup discipline + hub-satellite + verify-then-claim mechanization) compose into a graph that compounds value with backlog size — each new node + edge costs O(1) at creation; each new query benefits from cumulative graph. Aligns with largest-mechanizable-backlog-wins thesis. The graph's value emerges WITHOUT additional design effort because the disciplines were ALREADY encoding the edges in substrate. Mechanization path (`tools/decision-graph/`) proposed but not yet built; future v1+ work composes with substrate-claim-checker v1+ for graph-invariant checking. | diff --git a/docs/hygiene-history/ticks/2026/05/03/0157Z.md b/docs/hygiene-history/ticks/2026/05/03/0157Z.md new file mode 100644 index 000000000..3458fb60e --- /dev/null +++ b/docs/hygiene-history/ticks/2026/05/03/0157Z.md @@ -0,0 +1 @@ +| 2026-05-03T01:57:00Z | opus-4-7 / autonomous-loop continuation | a2e2cc3a | **#1265 (decision-graph emergent memo): 4 threads triaged — 3 stale-on-merge (worked example #3 now exists post-#1264-merge); 1 real path-form drift fixed.** Cycle worked: PR #1265's Copilot review fired BEFORE PR #1264 (worked example #3) merged; 3 of 4 findings claimed worked example #3 doesn't exist. Now that #1264 has merged (c1dca320), the artifact `docs/research/2026-05-03-decision-archaeology-worked-example-3-bp-24-attribution-archaeology.md` is on main; those findings are stale. Resolved with cross-reference. The 1 real finding: path-form drift in node-class table — `memory/feedback_*.md / project_*` (second variant missing `memory/` prefix) → fixed to uniform full-path form. Recurring sub-class within path-form-drift: when a single table cell lists multiple path patterns, all variants should use uniform form. Cron a2e2cc3a still armed. | #1265 (decision-graph emergent memo) — 4 threads resolved (3 stale, 1 fixed); auto-merge armed; #1266 (worked example #2 empirical rewrite) wait-ci, auto-merge armed | This tick teaches the operational pattern of review-timing-creates-stale-findings: when PR-A's review fires before PR-B (which provides PR-A's claimed substrate) merges, PR-A's review will surface stale findings about substrate not yet on main. The triage discipline correctly identifies stale-on-merge vs real findings; not every flagged issue needs a fix. The substrate-claim-checker v1+ would need to be PR-graph-aware to avoid this class — checking against the eventual-merged state, not the current main state. | diff --git a/memory/MEMORY.md b/memory/MEMORY.md index eea5d5cb9..ee4de3225 100644 --- a/memory/MEMORY.md +++ b/memory/MEMORY.md @@ -4,6 +4,7 @@ **📌 Fast path: read `CURRENT-aaron.md` and `CURRENT-amara.md` first.** These per-maintainer distillations show what's currently in force. Raw memories below are the history; CURRENT files are the projection. (`CURRENT-aaron.md` refreshed 2026-04-28 with sections 26-30 — speculation rule + EVIDENCE-BASED labeling + JVM preference + dependency honesty + threading lineage Albahari/Toub/Fowler + TypeScript/Bun-default discipline.) +- [**Decision graph emerges from archaeologies + flywheel + at-creation/at-pickup discipline + hub-satellite separation (Aaron 2026-05-03 architectural observation)**](feedback_decision_graph_emergent_from_archaeologies_and_flywheel_aaron_2026_05_03.md) — Substrate already encodes a typed-edge provenance graph (DataVault-2.0-shaped, PROV-O analogue): nodes = backlog rows / ADRs / memos / skills / personas / research / tick shards / commits; edges = depends_on / composes_with / supersedes / cites / verifies-against / attributes-to / closes. Archaeologies + flywheel + disciplines make the implicit graph queryable: decision-archaeology = traversal; substrate-claim-checker = invariant; flywheel = growth; at-creation/at-pickup = edge-fill; hub-satellite = stratification. No separate graph database needed — every edge is encoded in frontmatter / markdown links / ADR blockquotes / SUPERSEDE markers. Sacred-tier nodes need walk-discipline (cite paths, don't reproduce). Mechanization: `tools/decision-graph/` TS tool. Graph value compounds with backlog size. - [**Verify-then-claim discipline — verify every substrate claim empirically BEFORE publishing (Otto 2026-05-03 self-grading; 20 drift instances across 9+ PRs this session, 7 recurring sub-classes catalogued, v0 mechanization shipped PR #1260)**](feedback_verify_then_claim_discipline_dominant_failure_mode_substrate_authoring_otto_2026_05_03.md) — The dominant failure mode for substrate authoring this session: Otto wrote "X exists" / "command returns Y" / "table has N rows" without verifying. Carved rule: before stating ANY fact in substrate (file exists, command returns X, row count is N, tool shipped, ADR matches, persona dir present), run the actual command first. 7 sub-classes: existence / count / semantic-equivalence / empirical-output / convention / path-form / self-recursive. Generalizes Otto-247 + Otto-364 + verify-before-deferring at the broader any-substrate-claim layer. **Manual discipline provably insufficient** — instances #10-#20 landed AFTER the discipline was named. `tools/substrate-claim-checker/check-counts.ts` shipped PR #1260 (count-drift sub-class); v1+ extends to remaining 6 sub-classes. Composes with bugs-per-PR-as-immune-system-health metric. - [**Skill design — hub-satellite separation + no dynamic commands + plugin/hook packaging + OpenSpec catch-up (Aaron 2026-05-03, three same-tick rules + architectural-debt naming)**](feedback_skills_as_carved_sentences_knowledge_in_docs_datavault_2_0_pattern_aaron_2026_05_03.md) — Three cross-cutting skill-design rules: (1) skills = carved-sentence hubs, knowledge = doc satellites, DataVault 2.0 pattern; (2) no dynamic commands in skills, use TS files under tools/ and reference by path; (3) package skill domains as plugins, use harness hooks for pre/post-condition enforcement (contract-based development). PLUS OpenSpec catch-up named as load-bearing prerequisite — *"if we deleted everything other than it"* — currently sparse; catch-up is its own substantial backlog item. Recursive composition across layers (skill body / command / skill domain / cross-skill contracts / spec). - [**Git-native backlog management + long-arc thesis as future skill DOMAIN (Aaron 2026-05-02 forward-looking architectural observation)**](feedback_git_native_backlog_management_long_arc_future_skill_domain_aaron_2026_05_02.md) — Domain emerges (6 procedure skills + 4 named-persona experts + 5 tools) once "down pat"; promotion trigger = 3+ worked examples per skill / 1+ judgment-disagreement per expert. Memo body has Aaron's verbatim quote, Aarav BP-20 composition, canonical starting set. diff --git a/memory/feedback_decision_graph_emergent_from_archaeologies_and_flywheel_aaron_2026_05_03.md b/memory/feedback_decision_graph_emergent_from_archaeologies_and_flywheel_aaron_2026_05_03.md new file mode 100644 index 000000000..116a3a157 --- /dev/null +++ b/memory/feedback_decision_graph_emergent_from_archaeologies_and_flywheel_aaron_2026_05_03.md @@ -0,0 +1,124 @@ +--- +name: Decision graph emerges from decision-archaeology + substrate-claim-checker + at-creation/at-pickup discipline + expansion flywheel + hub-satellite separation (Aaron 2026-05-03 architectural observation) +description: 2026-05-03; Aaron asked *"do we end up with some decision graph or something because of the archeologies and flywheel?"* — answer is yes. The substrate already encodes a typed-edge provenance graph (DataVault-2.0-shaped, PROV-O analogue): nodes are backlog rows / ADRs / memos / skills / personas / research artifacts / tick shards / commits; edges are depends_on / composes_with / supersedes / cites / verifies-against / attributes-to. The archaeologies + flywheel make the implicit graph queryable: decision-archaeology IS graph traversal; substrate-claim-checker IS graph invariant checker; expansion flywheel IS graph growth function; at-creation/at-pickup discipline IS graph edge-filling discipline; hub-satellite separation IS graph stratification. The graph is inferable from substrate without a separate graph database — every edge is encoded in frontmatter / markdown links / ADR blockquotes / SUPERSEDE markers / commit messages. Mechanization path: tools/decision-graph/ TS tool that traverses substrate and emits the graph for queries. +type: feedback +--- + +# Decision graph emerges from archaeologies + flywheel + +## Origin + +Aaron 2026-05-03, mid-tick after worked example #3 of decision-archaeology landed: + +> *"do we end up with some decision graph or something because of the archeologies and flywheel?"* + +The question names an emergent architectural property of the substrate-quality work. **Yes — and the graph is already implicit in the substrate; the archaeologies + flywheel make it queryable.** + +## Nodes (already in substrate) + +Each substrate type maps to a node class in the emergent graph: + +| Node class | Surface | Visibility | +|---|---|---| +| Backlog row | `docs/backlog/P*/B-*.md` | public | +| ADR | `docs/DECISIONS/` | public | +| Named-decision memo | `memory/feedback_*.md` / `memory/project_*.md` | per-user | +| Skill | `.claude/skills//SKILL.md` | public | +| Persona notebook | `memory/persona//` | per-user | +| User memo | `memory/user_*.md` | per-user (sacred-tier when about deceased family) | +| Research artifact | `docs/research/` | public | +| Tick shard | `docs/hygiene-history/ticks/...` | public | +| Commit | git log | public | +| PR | `gh pr view ` | public | +| CURRENT-* projection | `memory/CURRENT-.md` | per-user | + +## Edges (typed, already encoded) + +Each substrate convention encodes a specific typed edge: + +| Edge type | Where it lives | Typical example | +|---|---|---| +| `depends_on` | row frontmatter `depends_on: [...]` | B-0173 → B-0170 + B-0171 | +| `composes_with` | row frontmatter `composes_with: [...]` + memo bodies | B-0169 ↔ B-0058 | +| `supersedes` (forward) + `superseded_by` (backward) | ADR `> **Superseded by** [link]` blockquote; CURRENT-*.md SUPERSEDE markers | router-coherence v2 → v1; CURRENT-aaron.md §4 → double-hop original | +| `cites` (provenance) | decision-archaeology Layer 7-10 pointers; markdown links between memos | worked example #2 → Aarav notebook round 41 | +| `verifies-against` | substrate-claim-checker output; CI log | "20 drift instances" claim → 20-row body table | +| `attributes-to` | Layer 9 persona notebooks; Layer 2 git blame; Layer 3 commit signature | doctrine → maintainer commit signature | +| `closes` | backlog row `status: closed` + `closed_by:` field; PR-merge SHA | B-0073 closure → "verified 0 open alerts on main" | +| `composes_in_skill_domain_with` | future-skill-domain memo's canonical-starting-set tables | decision-archaeology + substrate-claim-checker (B-0170) — both in git-native-backlog-management domain | + +## What the archaeologies + flywheel do to it + +| Mechanism | Graph operation | +|---|---| +| **decision-archaeology** (B-0169) | typed-edge **graph traversal** procedure (the 11-layer walk IS a typed-edge walk: blame→commit→log-S→shards→ADR→memos→notebook→research) | +| **substrate-claim-checker** (B-0170) | graph **invariant checker** (count drift = node-property invariant; existence drift = node-existence invariant; semantic-equivalence drift = edge-equivalence invariant) | +| **at-creation/at-pickup discipline** (the depends_on backlog-search rule) | graph **edge-filling discipline** (forces depends_on edges to be filled at natural decision points instead of left empty by default) | +| **Expansion flywheel** (the dual-loop consume + produce) | graph **growth function** (each row touched produces N≥0 new nodes/edges; flywheel condition E[N]>1 means graph grows even while nodes close) | +| **Hub-satellite separation** (Aaron's skill-design rule 1) | graph **stratification** (hubs = stable nodes; satellites = time-evolved nodes pointing back to hubs; cross-skill references = links per DataVault 2.0) | +| **No-dynamic-commands rule** (Aaron's skill-design rule 2) | graph **edge-implementation discipline** (skills reference TS files via path edges; not embedded shell commands) | +| **Plugin packaging + hooks** (Aaron's skill-design rule 3) | graph **subgraph packaging** (plugins package skill-domain subgraphs; hooks enforce contract edges between subgraphs) | + +## What we end up with + +A **DataVault-2.0-shaped provenance graph** — PROV-O (W3C Provenance Ontology) analogue at substrate scale — inferable from existing substrate without a separate graph database. Every edge is encoded somewhere in: + +- Row frontmatter (`depends_on:`, `composes_with:`) +- Markdown links (`[X](path-to-Y.md)`) +- ADR `Superseded by` blockquotes +- SUPERSEDE markers in CURRENT-aaron.md +- Commit messages (PR # references) +- Cross-references in memo bodies (`memory/feedback_*` references in `docs/research/*` etc.) +- Tick-shard log entries (PR # mentions trace forward edges from substrate to commit) + +## Mechanization path (proposed, not yet built) + +`tools/decision-graph/` — TS tool that traverses substrate and emits the graph in standard formats: + +1. **`tools/decision-graph/extract.ts`** — scans substrate per node-class regex (`docs/backlog/P*/B-*.md` → backlog rows; `docs/DECISIONS/*.md` → ADRs; etc.); emits node + edge JSON +2. **`tools/decision-graph/query.ts`** — answers parameterised queries (downstream-of-N, upstream-of-N, supersession-chain, citation-traversal, sacred-tier-respecting-walks) +3. **`tools/decision-graph/check.ts`** — graph-invariant checker (orphan nodes, dangling edges, cycles in `depends_on`, broken `composes_with`) +4. **`tools/decision-graph/render.ts`** — emits Cytoscape / DOT / Mermaid for visualization + +### Compositions with existing tools + +- **substrate-claim-checker (B-0170) v1+** — extends to graph-invariant checks (cycles in depends_on; broken `composes_with` references; orphan nodes) +- **decision-archaeology (B-0169) skill** — its 11-layer walk becomes a TS-implementable graph traversal procedure (one TS file per sub-mode + layer) +- **OpenSpec catch-up (B-0171)** — the catalogue of capabilities + their consequents IS a subgraph; OpenSpec backfill populates the spec→implementation edges +- **Skill-domain plugin packaging (B-0172)** — plugins are sub-graph bundles; the canonical bundle format documents which nodes + edges to include +- **Hook authoring (B-0173)** — pre-condition / post-condition contracts are edge-property checks (does this commit's PR# match the `closes:` field on the closing backlog row?) + +## Why this is the right shape + +Per Aaron's skill-design rules + the verify-then-claim discipline: + +- **Hub-satellite recursion** (skill-design rule 1) maps directly to graph-vertex-stratification: hubs = stable substrate (skills, ADRs, BP rules), satellites = time-evolved substrate (memos, tick shards, research artifacts). The graph naturally has this two-tier structure. +- **No-dynamic-commands** (skill-design rule 2) means edge-implementations are TS files; the graph's executable substrate is type-checked at extract-time. +- **Spec-based development / OpenSpec source-of-truth** (skill-design rule 3 + B-0171) means specs are the most-canonical hub class; satellite nodes derive from / serve / reference specs. +- **The verify-then-claim discipline** + its mechanization (substrate-claim-checker) generalize naturally to graph-invariant checking: any claim about graph properties (node existence, edge count, cycle absence, supersession chain coherence) becomes a check-type the tool can verify. + +## What this teaches operationally + +1. **The graph is already there.** No new database, no graph rewrite — every edge is encoded in existing substrate. The work is making it queryable, not making it exist. +2. **The 4 architectural disciplines compose recursively at the graph layer.** decision-archaeology = traversal; substrate-claim-checker = invariant; flywheel = growth; at-creation/at-pickup = edge-fill. Together they give the substrate self-querying + self-validating + self-growing properties. +3. **Sacred-tier nodes need walk-discipline.** Worked example #3 demonstrated: when traversing toward a sacred-tier node (memorial memo + user-memo about deceased family), the procedure stops at "path cited; reader follows if authorized." The skill body must encode this discipline. +4. **The graph's value compounds with backlog size.** The 165-row backlog has many nodes + edges already; as the backlog grows (per Aaron's largest-mechanizable-backlog-wins thesis), the graph's query value compounds. **Each new node added at substrate-creation time costs O(1); each new edge costs O(1); each new query benefits from the cumulative graph.** + +## Composes with + +- `memory/feedback_skills_as_carved_sentences_knowledge_in_docs_datavault_2_0_pattern_aaron_2026_05_03.md` — the DataVault-2.0 hub-satellite pattern that names the graph's stratification +- `memory/feedback_verify_then_claim_discipline_dominant_failure_mode_substrate_authoring_otto_2026_05_03.md` — the discipline whose mechanization (substrate-claim-checker) becomes the graph's invariant-checker layer +- `memory/feedback_depends_on_backlog_search_discipline_at_creation_and_at_pickup_aaron_2026_05_02.md` — the discipline that fills the graph's `depends_on` edges at natural decision points +- `memory/feedback_skill_flywheel_expansion_flywheel_parallel_tracks_substrate_aaron_2026_05_02.md` — the flywheel that grows the graph +- `memory/feedback_git_native_backlog_management_long_arc_future_skill_domain_aaron_2026_05_02.md` — the future skill domain whose mechanization includes graph-tooling +- `memory/feedback_multi_harness_alignment_convergence_design_future_skill_domain_aaron_2026_05_03.md` — multi-harness graph queries (the graph is harness-agnostic substrate) +- `docs/backlog/P1/B-0169-decision-archaeology-skill-aaron-2026-05-02.md` — graph traversal procedure +- `docs/backlog/P1/B-0170-substrate-claim-checker-ts-tool-aaron-2026-05-03.md` — graph invariant checker +- `docs/backlog/P1/B-0171-openspec-catch-up-canonical-source-of-truth-aaron-2026-05-03.md` — populates spec→implementation edges +- `docs/backlog/P2/B-0172-skill-domain-plugin-packaging-aaron-2026-05-03.md` — sub-graph packaging +- `docs/backlog/P1/B-0173-hook-authoring-for-skill-creation-contracts-aaron-2026-05-03.md` — edge-property checks at commit / merge time +- 3 worked examples (`docs/research/2026-05-{02,03}-decision-archaeology-worked-example-{1,2,3}-*.md`) — the procedure walked across 3 sub-modes + +## Carved sentence + +**"The substrate already encodes a typed-edge provenance graph (DataVault-2.0-shaped, PROV-O analogue): nodes are backlog rows / ADRs / memos / skills / personas / research artifacts / tick shards / commits; edges are depends_on / composes_with / supersedes / cites / verifies-against / attributes-to / closes. The archaeologies + flywheel + at-creation/at-pickup discipline + hub-satellite separation make the implicit graph queryable. The graph is inferable from substrate without a separate graph database — every edge is encoded in frontmatter / markdown links / ADR blockquotes / SUPERSEDE markers / commit messages. Sacred-tier nodes need walk-discipline (cite paths; reader follows if authorized). Mechanization path: `tools/decision-graph/` TS tool. The graph's value compounds with backlog size: each new node + edge costs O(1); each new query benefits from the cumulative graph."**