diff --git a/README.md b/README.md index beaa49d..89bfe5b 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,22 @@ The repository is organized as a Markdown-native doctrine graph. Markdown pages This is a living doctrine repo with support tooling. The goal is not to collect loose notes or ship a product. The goal is to maintain a durable, inspectable, and reusable record of how I want technical work to be structured. +## Generated graph views +These visuals are generated by `uv run tea-kb build` and checked by GitHub Actions. + +![How tea-style works](graph/generated/visualizations/repo-system.svg) + +![Research support map](graph/generated/visualizations/research-support.svg) + +![Knowledge base growth](graph/generated/visualizations/timeline-overview.svg) + +Reviewable generated views: +- [visualization index](graph/generated/visualizations/README.md) +- [interactive graph overview](graph/generated/visualizations/overview.html) +- [graph health report](graph/generated/reports/health.md) +- [knowledge timeline report](graph/generated/reports/timeline.md) +- [timeline event feed](graph/generated/timeline.jsonl) + ## Core navigation - [docs/repo-scope.md](docs/repo-scope.md) - [docs/work-operating-model.md](docs/work-operating-model.md) @@ -29,6 +45,7 @@ Common commands: - `uv run tea-kb build` - `uv run tea-kb report` - `uv run tea-kb viz overview` +- `uv run tea-kb viz all` Tea-themed aliases are available for human convenience: - `uv run tea-kb brew` for `build` diff --git a/docs/decisions/0001-adopt-github-native-second-brain-doctrine.md b/docs/decisions/0001-adopt-github-native-second-brain-doctrine.md index 342b879..563c15c 100644 --- a/docs/decisions/0001-adopt-github-native-second-brain-doctrine.md +++ b/docs/decisions/0001-adopt-github-native-second-brain-doctrine.md @@ -4,6 +4,8 @@ title: Adopt GitHub-Native Second-Brain Doctrine type: decision domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Use GitHub-native Markdown as the second-brain substrate for tea-style. concepts: diff --git a/docs/decisions/0002-adopt-markdown-native-doctrine-graph.md b/docs/decisions/0002-adopt-markdown-native-doctrine-graph.md index 04189b0..c909894 100644 --- a/docs/decisions/0002-adopt-markdown-native-doctrine-graph.md +++ b/docs/decisions/0002-adopt-markdown-native-doctrine-graph.md @@ -4,6 +4,8 @@ title: Adopt Markdown-Native Doctrine Graph type: decision domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Markdown notes and frontmatter are the source of truth; graph artifacts are generated from visible source files. concepts: diff --git a/docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md b/docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md index b1a865e..b5d3fe8 100644 --- a/docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md +++ b/docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md @@ -4,6 +4,8 @@ title: Ship TEA KB Lifecycle Tooling type: decision domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Include a bounded Python package and CLI for validating, building, reporting, visualizing, and exporting the Markdown doctrine graph. concepts: diff --git a/docs/doctrines/engineering-control-spine.md b/docs/doctrines/engineering-control-spine.md index a6bd8fe..ada049e 100644 --- a/docs/doctrines/engineering-control-spine.md +++ b/docs/doctrines/engineering-control-spine.md @@ -4,6 +4,8 @@ title: Engineering Control Spine type: doctrine domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Good systems are easy to reason about, easy to change, hard to misuse, and observable when they fail. concepts: diff --git a/docs/doctrines/systems-should-tell-on-themselves.md b/docs/doctrines/systems-should-tell-on-themselves.md index 0572e1c..0b3b8ee 100644 --- a/docs/doctrines/systems-should-tell-on-themselves.md +++ b/docs/doctrines/systems-should-tell-on-themselves.md @@ -4,6 +4,8 @@ title: Systems Should Tell on Themselves type: doctrine domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible. concepts: diff --git a/docs/doctrines/tea-style-doctrine.md b/docs/doctrines/tea-style-doctrine.md index 61665b0..44d79db 100644 --- a/docs/doctrines/tea-style-doctrine.md +++ b/docs/doctrines/tea-style-doctrine.md @@ -4,6 +4,8 @@ title: TEA Style Doctrine type: doctrine domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > tea-style is a Markdown-native engineering doctrine graph with embedded Python lifecycle tooling. concepts: diff --git a/docs/doctrines/typed-encapsulated-architecture-style.md b/docs/doctrines/typed-encapsulated-architecture-style.md index b5a0217..05182cb 100644 --- a/docs/doctrines/typed-encapsulated-architecture-style.md +++ b/docs/doctrines/typed-encapsulated-architecture-style.md @@ -4,6 +4,8 @@ title: Typed Encapsulated Architecture Style type: doctrine domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > TEA is a decision style for explicit, modular, typed, reviewable, and durable systems. concepts: diff --git a/docs/maps/agent-architecture.md b/docs/maps/agent-architecture.md index ecb7c11..463a096 100644 --- a/docs/maps/agent-architecture.md +++ b/docs/maps/agent-architecture.md @@ -4,6 +4,8 @@ title: Agent Architecture Map type: map domain: agent-architecture status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Navigation map for agent architecture doctrine and graph notes. concepts: diff --git a/docs/maps/automation.md b/docs/maps/automation.md index a83aaf6..e468d07 100644 --- a/docs/maps/automation.md +++ b/docs/maps/automation.md @@ -4,6 +4,8 @@ title: Automation Map type: map domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Navigation map for automation doctrine and graph notes. concepts: diff --git a/docs/maps/coding.md b/docs/maps/coding.md index cfd4e47..dabcb1f 100644 --- a/docs/maps/coding.md +++ b/docs/maps/coding.md @@ -4,6 +4,8 @@ title: Coding Map type: map domain: coding status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Navigation map for coding doctrine and graph notes. concepts: diff --git a/docs/maps/engineering-doctrine.md b/docs/maps/engineering-doctrine.md index 3ebdb06..44f5948 100644 --- a/docs/maps/engineering-doctrine.md +++ b/docs/maps/engineering-doctrine.md @@ -4,6 +4,8 @@ title: Engineering Doctrine Map type: map domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Navigation map for the core TEA doctrine graph. concepts: diff --git a/docs/maps/observability.md b/docs/maps/observability.md index 87fd3b4..29f13f8 100644 --- a/docs/maps/observability.md +++ b/docs/maps/observability.md @@ -4,6 +4,8 @@ title: Observability Map type: map domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Navigation map for observability doctrine and graph notes. concepts: diff --git a/docs/standards/agent-kb-editing-standard.md b/docs/standards/agent-kb-editing-standard.md index 7147a43..1d9524e 100644 --- a/docs/standards/agent-kb-editing-standard.md +++ b/docs/standards/agent-kb-editing-standard.md @@ -4,6 +4,8 @@ title: Agent KB Editing Standard type: standard domain: agent-architecture status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Defines how agents may add or change graph knowledge without silently redefining doctrine. concepts: @@ -38,6 +40,7 @@ Agents may propose graph changes. They must not silently promote inferred doctri - Mark inferred edges as proposed unless the user explicitly reviewed them. - Do not silently redefine core doctrine. - Do not rename IDs casually. +- Update the `updated` frontmatter date when durable meaning, graph metadata, or relationships change. - Run validation before finishing. - Update maps only when navigation materially improves. @@ -71,6 +74,7 @@ origin: - IDs are stable and meaningful. - Concepts reuse existing vocabulary. - Edges are justified. +- `created` and `updated` dates are present and accurate enough for timeline generation. - Generated artifacts are updated. - Validation passes. - Reports were reviewed. diff --git a/docs/standards/generated-artifact-standard.md b/docs/standards/generated-artifact-standard.md index 7206a41..784a9ad 100644 --- a/docs/standards/generated-artifact-standard.md +++ b/docs/standards/generated-artifact-standard.md @@ -4,6 +4,8 @@ title: Generated Artifact Standard type: standard domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Defines generated graph artifacts, stale checks, determinism, and review expectations. concepts: @@ -34,12 +36,19 @@ Generated artifacts are derived from Markdown/frontmatter. They are committed wh - `graph/generated/edges.jsonl` - `graph/generated/chunks.jsonl` - `graph/generated/concepts.jsonl` +- `graph/generated/timeline.jsonl` - `graph/generated/reports/health.md` - `graph/generated/reports/orphan-notes.md` - `graph/generated/reports/dense-links.md` - `graph/generated/reports/duplicate-concepts.md` - `graph/generated/reports/proposed-edges.md` +- `graph/generated/reports/timeline.md` - `graph/generated/visualizations/overview.html` +- `graph/generated/visualizations/README.md` +- `graph/generated/visualizations/repo-system.svg` +- `graph/generated/visualizations/research-support.svg` +- `graph/generated/visualizations/timeline-overview.svg` +- `graph/generated/visualizations/concept-timeline-*.svg` ## Rules / standards - Generated artifacts must be deterministic. @@ -48,6 +57,8 @@ Generated artifacts are derived from Markdown/frontmatter. They are committed wh - Reports should be boring, useful, and reviewable. - JSONL exports should be stable-sorted by ID or edge tuple. - Visualization output should avoid avoidable randomness. +- Root README diagrams must be generated artifacts, not hand-maintained images. +- Timeline artifacts must be derived from `created` and `updated` frontmatter dates. ## Related pages - [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md) diff --git a/docs/standards/graph-knowledge-base-standard.md b/docs/standards/graph-knowledge-base-standard.md index 5949806..ea183bb 100644 --- a/docs/standards/graph-knowledge-base-standard.md +++ b/docs/standards/graph-knowledge-base-standard.md @@ -4,6 +4,8 @@ title: Graph Knowledge Base Standard type: standard domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Defines graph source units, node types, edge types, IDs, frontmatter, and generated artifacts. concepts: @@ -91,10 +93,19 @@ title: Example type: note domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 concepts: - evidence ``` +## Timeline metadata +Every authored graph node should carry: +- `created`: the date the note, concept, decision, standard, map, example, or antipattern entered the graph. +- `updated`: the latest meaningful doctrine or metadata update date. + +Use ISO `YYYY-MM-DD` dates. Generated timeline artifacts use these fields rather than Git history so timelines remain portable across forks, exports, and future search systems. + ## Related pages - [graph/schema.md](../../graph/schema.md) - [graph-linking-standard.md](graph-linking-standard.md) diff --git a/docs/standards/graph-linking-standard.md b/docs/standards/graph-linking-standard.md index 7c2ac1e..4cddbe6 100644 --- a/docs/standards/graph-linking-standard.md +++ b/docs/standards/graph-linking-standard.md @@ -4,6 +4,8 @@ title: Graph Linking Standard type: standard domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Defines when to create semantic graph edges and when to rely on Markdown links. concepts: diff --git a/docs/standards/python-type-discipline.md b/docs/standards/python-type-discipline.md index 82b8961..e33df2d 100644 --- a/docs/standards/python-type-discipline.md +++ b/docs/standards/python-type-discipline.md @@ -4,6 +4,8 @@ title: Python Type Discipline type: standard domain: coding status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Defines how tea_kb uses Pydantic, dataclasses, NewType, StrEnum, Protocol, and standard collections. concepts: diff --git a/docs/standards/visualization-standard.md b/docs/standards/visualization-standard.md index fdc6201..7ce47df 100644 --- a/docs/standards/visualization-standard.md +++ b/docs/standards/visualization-standard.md @@ -4,6 +4,8 @@ title: Visualization Standard type: standard domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Defines graph visualizations as diagnostic artifacts, not decorative output. concepts: @@ -34,6 +36,9 @@ Visualizations are diagnostic. They should answer a question. - Show node type, domain, and edge labels. - Link visual nodes back to source Markdown when practical. - Generated visualizations must be deterministic enough for review. +- Root README visuals must be regenerated by `tea-kb build`, not edited as screenshots. +- Timeline views should be split by major concept when a single feed would become noisy. +- SVG is preferred for README-level diagrams because it is GitHub-native, diffable, and deterministic. ## Good visualizations - concept neighborhood @@ -43,6 +48,10 @@ Visualizations are diagnostic. They should answer a question. - orphan note map - dense-link warning map - proposed-edge review map +- repository system map +- research support map +- knowledge base growth timeline +- major concept timeline ## Anti-patterns - huge all-node/all-edge views with no diagnostic purpose diff --git a/graph/generated/chunks.jsonl b/graph/generated/chunks.jsonl index fd5f8c2..7d701e7 100644 --- a/graph/generated/chunks.jsonl +++ b/graph/generated/chunks.jsonl @@ -1,183 +1,184 @@ -{"chunk_id": "chunk:antipattern:hallucinated-operational-state:detection", "concepts": ["observability", "explicit-state", "evidence"], "domain": "observability", "heading": "Detection", "node_id": "antipattern:hallucinated-operational-state", "node_type": "antipattern", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/antipatterns/hallucinated-operational-state.md", "source_hash": "702601bba9b37466ee7ae735d0135d5e5890532080b072648dc6c50274343db2", "text": "Status is asserted without source, timestamp, check result, or confidence boundary."} -{"chunk_id": "chunk:antipattern:hallucinated-operational-state:failure-mode", "concepts": ["observability", "explicit-state", "evidence"], "domain": "observability", "heading": "Failure mode", "node_id": "antipattern:hallucinated-operational-state", "node_type": "antipattern", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/antipatterns/hallucinated-operational-state.md", "source_hash": "702601bba9b37466ee7ae735d0135d5e5890532080b072648dc6c50274343db2", "text": "A human, agent, or tool claims current system state without evidence from authoritative sources."} -{"chunk_id": "chunk:antipattern:hidden-operational-context:detection", "concepts": ["operability", "context-regression"], "domain": "operability", "heading": "Detection", "node_id": "antipattern:hidden-operational-context", "node_type": "antipattern", "outbound_edges": ["note:context:hidden-context-is-operational-risk"], "path": "kb/antipatterns/hidden-operational-context.md", "source_hash": "82d6f17c68de7fc521764b75c80d66ea131b83b94dd6ecd345a483daee13e6cd", "text": "Reviewers cannot determine valid inputs, state, risks, or next actions from the source and generated evidence."} -{"chunk_id": "chunk:antipattern:hidden-operational-context:failure-mode", "concepts": ["operability", "context-regression"], "domain": "operability", "heading": "Failure mode", "node_id": "antipattern:hidden-operational-context", "node_type": "antipattern", "outbound_edges": ["note:context:hidden-context-is-operational-risk"], "path": "kb/antipatterns/hidden-operational-context.md", "source_hash": "82d6f17c68de7fc521764b75c80d66ea131b83b94dd6ecd345a483daee13e6cd", "text": "A system relies on unstated human knowledge to operate, diagnose, or recover safely."} -{"chunk_id": "chunk:antipattern:undocumented-mutation:detection", "concepts": ["mutation", "evidence"], "domain": "automation", "heading": "Detection", "node_id": "antipattern:undocumented-mutation", "node_type": "antipattern", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/antipatterns/undocumented-mutation.md", "source_hash": "f89925da6dae183e1f92811e630198f4271990efe7c9284fb6e995cc0e271aa6", "text": "Mutation is hidden inside read-sounding commands, broad scripts, prose-only output, or implicit side effects."} -{"chunk_id": "chunk:antipattern:undocumented-mutation:failure-mode", "concepts": ["mutation", "evidence"], "domain": "automation", "heading": "Failure mode", "node_id": "antipattern:undocumented-mutation", "node_type": "antipattern", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/antipatterns/undocumented-mutation.md", "source_hash": "f89925da6dae183e1f92811e630198f4271990efe7c9284fb6e995cc0e271aa6", "text": "A tool mutates state without making the mutation visible, reviewable, or recoverable."} -{"chunk_id": "chunk:antipattern:vanity-metrics:detection", "concepts": ["evidence", "metrics"], "domain": "observability", "heading": "Detection", "node_id": "antipattern:vanity-metrics", "node_type": "antipattern", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/antipatterns/vanity-metrics.md", "source_hash": "4aab9cb9f73e4c25b62dc726c867412ac0a654a9fff399dd06d85dce3796d926", "text": "The metric cannot answer what changed, what failed, what risk moved, or what action should happen next."} -{"chunk_id": "chunk:antipattern:vanity-metrics:failure-mode", "concepts": ["evidence", "metrics"], "domain": "observability", "heading": "Failure mode", "node_id": "antipattern:vanity-metrics", "node_type": "antipattern", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/antipatterns/vanity-metrics.md", "source_hash": "4aab9cb9f73e4c25b62dc726c867412ac0a654a9fff399dd06d85dce3796d926", "text": "A metric demonstrates activity but does not improve decision quality or operational clarity."} -{"chunk_id": "chunk:concept:agents:definition", "concepts": ["agents"], "domain": "agent-architecture", "heading": "Definition", "node_id": "concept:agents", "node_type": "concept", "outbound_edges": ["standard:repo:agent-kb-editing-standard"], "path": "kb/concepts/agents.md", "source_hash": "40d28e6001baaa51b9e17027e58ddcb3fd64dc55c41dc35342a1a62c8fece074", "text": "Agents are software actors that use model output, tools, context, and control boundaries to perform work."} -{"chunk_id": "chunk:concept:agents:use", "concepts": ["agents"], "domain": "agent-architecture", "heading": "Use", "node_id": "concept:agents", "node_type": "concept", "outbound_edges": ["standard:repo:agent-kb-editing-standard"], "path": "kb/concepts/agents.md", "source_hash": "40d28e6001baaa51b9e17027e58ddcb3fd64dc55c41dc35342a1a62c8fece074", "text": "Use this concept when discussing agent workflows, tool exposure, and review boundaries."} -{"chunk_id": "chunk:concept:automation:definition", "concepts": ["automation"], "domain": "automation", "heading": "Definition", "node_id": "concept:automation", "node_type": "concept", "outbound_edges": ["map:automation:overview"], "path": "kb/concepts/automation.md", "source_hash": "f7f3dea1f6f5baab020b35f4b75243f32982ad77662fbd9d54a3c59cc4bbf790", "text": "Automation is software-controlled execution of repeatable operational or engineering work."} -{"chunk_id": "chunk:concept:automation:use", "concepts": ["automation"], "domain": "automation", "heading": "Use", "node_id": "concept:automation", "node_type": "concept", "outbound_edges": ["map:automation:overview"], "path": "kb/concepts/automation.md", "source_hash": "f7f3dea1f6f5baab020b35f4b75243f32982ad77662fbd9d54a3c59cc4bbf790", "text": "Use this concept when discussing scripts, workflows, remediation, and platform operations."} -{"chunk_id": "chunk:concept:boundary:definition", "concepts": ["boundary", "encapsulation"], "domain": "coding", "heading": "Definition", "node_id": "concept:boundary", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/boundary.md", "source_hash": "8c7a54893fc1bd77bb2a39a2b07917d51ddd2c7ac5ecf802d9d283e4cdd2f740", "text": "A boundary is a public interface where messy internals, external systems, or side effects are contained."} -{"chunk_id": "chunk:concept:boundary:use", "concepts": ["boundary", "encapsulation"], "domain": "coding", "heading": "Use", "node_id": "concept:boundary", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/boundary.md", "source_hash": "8c7a54893fc1bd77bb2a39a2b07917d51ddd2c7ac5ecf802d9d283e4cdd2f740", "text": "Use boundaries to keep callers dependent on behavior instead of implementation details."} -{"chunk_id": "chunk:concept:change-control:definition", "concepts": ["change-control"], "domain": "automation", "heading": "Definition", "node_id": "concept:change-control", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/change-control.md", "source_hash": "e5a89e0d37b63a05f0a01ad513744634c5fe7aa408e5bf654c7e0046a2d79a26", "text": "Change control is explicit handling of what can change, who approves it, how it is validated, and how it is recovered."} -{"chunk_id": "chunk:concept:change-control:use", "concepts": ["change-control"], "domain": "automation", "heading": "Use", "node_id": "concept:change-control", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/change-control.md", "source_hash": "e5a89e0d37b63a05f0a01ad513744634c5fe7aa408e5bf654c7e0046a2d79a26", "text": "Use this concept when mutation must be bounded, reviewable, and recoverable."} -{"chunk_id": "chunk:concept:context-regression:definition", "concepts": ["context-regression"], "domain": "repo-wide", "heading": "Definition", "node_id": "concept:context-regression", "node_type": "concept", "outbound_edges": ["doctrine:repo:tea-style-doctrine"], "path": "kb/concepts/context-regression.md", "source_hash": "abcbc573894e45e17d6274402cf74fedca397b7ed8c80db3d8dfec800735a102", "text": "Context regression is rediscovery of knowledge that should already exist as durable doctrine."} -{"chunk_id": "chunk:concept:context-regression:use", "concepts": ["context-regression"], "domain": "repo-wide", "heading": "Use", "node_id": "concept:context-regression", "node_type": "concept", "outbound_edges": ["doctrine:repo:tea-style-doctrine"], "path": "kb/concepts/context-regression.md", "source_hash": "abcbc573894e45e17d6274402cf74fedca397b7ed8c80db3d8dfec800735a102", "text": "Use this concept when deciding whether a new learning should become a note, concept, decision, or standard."} -{"chunk_id": "chunk:concept:contract:definition", "concepts": ["contract"], "domain": "coding", "heading": "Definition", "node_id": "concept:contract", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/contract.md", "source_hash": "6768e9fe68126c169c42860dff73a41ffc5c9a02be67c0a9649913aa6ffd7697", "text": "A contract is a promise about inputs, outputs, side effects, errors, compatibility, or behavior."} -{"chunk_id": "chunk:concept:contract:use", "concepts": ["contract"], "domain": "coding", "heading": "Use", "node_id": "concept:contract", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/contract.md", "source_hash": "6768e9fe68126c169c42860dff73a41ffc5c9a02be67c0a9649913aa6ffd7697", "text": "Use contracts when defining protocols, schemas, CLI output, generated artifacts, and validation results."} -{"chunk_id": "chunk:concept:diagnostics:definition", "concepts": ["diagnostics"], "domain": "observability", "heading": "Definition", "node_id": "concept:diagnostics", "node_type": "concept", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/concepts/diagnostics.md", "source_hash": "273bb59c4c9c76ed10711598cb03136051a7710c1b2c240737398be02ee1fe8c", "text": "Diagnostics are evidence and methods used to determine what is happening and why."} -{"chunk_id": "chunk:concept:diagnostics:use", "concepts": ["diagnostics"], "domain": "observability", "heading": "Use", "node_id": "concept:diagnostics", "node_type": "concept", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/concepts/diagnostics.md", "source_hash": "273bb59c4c9c76ed10711598cb03136051a7710c1b2c240737398be02ee1fe8c", "text": "Use this concept when building reports, health checks, triage flows, and graph warnings."} -{"chunk_id": "chunk:concept:evidence:definition", "concepts": ["evidence"], "domain": "repo-wide", "heading": "Definition", "node_id": "concept:evidence", "node_type": "concept", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves"], "path": "kb/concepts/evidence.md", "source_hash": "a298e8046f12cb44b3519844da230acd192ee2da286a1b56bb8c17b678ce5afc", "text": "Evidence is structured proof that supports a claim about state, change, validation, failure, or decision quality."} -{"chunk_id": "chunk:concept:evidence:related-pages", "concepts": ["evidence"], "domain": "repo-wide", "heading": "Related pages", "node_id": "concept:evidence", "node_type": "concept", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves"], "path": "kb/concepts/evidence.md", "source_hash": "a298e8046f12cb44b3519844da230acd192ee2da286a1b56bb8c17b678ce5afc", "text": "- [Systems Should Tell on Themselves](../../docs/doctrines/systems-should-tell-on-themselves.md)"} -{"chunk_id": "chunk:concept:evidence:use", "concepts": ["evidence"], "domain": "repo-wide", "heading": "Use", "node_id": "concept:evidence", "node_type": "concept", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves"], "path": "kb/concepts/evidence.md", "source_hash": "a298e8046f12cb44b3519844da230acd192ee2da286a1b56bb8c17b678ce5afc", "text": "Use evidence when a system needs to justify what it did or what it believes."} -{"chunk_id": "chunk:concept:explicit-state:definition", "concepts": ["explicit-state", "state"], "domain": "repo-wide", "heading": "Definition", "node_id": "concept:explicit-state", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/explicit-state.md", "source_hash": "6d7ba7def17198ef19094552a4d17ed827cbb3b395e6601a848fdc82a0ac778c", "text": "Explicit state is modeled state that humans and tools can inspect without guessing from call order or hidden globals."} -{"chunk_id": "chunk:concept:explicit-state:use", "concepts": ["explicit-state", "state"], "domain": "repo-wide", "heading": "Use", "node_id": "concept:explicit-state", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/explicit-state.md", "source_hash": "6d7ba7def17198ef19094552a4d17ed827cbb3b395e6601a848fdc82a0ac778c", "text": "Use explicit state for workflows, generated artifacts, reports, plans, and validation output."} -{"chunk_id": "chunk:concept:idempotency:definition", "concepts": ["idempotency"], "domain": "automation", "heading": "Definition", "node_id": "concept:idempotency", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/idempotency.md", "source_hash": "fc2a80065e167e1f9d44e1105d1e6eb195e919674b9a0062c190dd2531c16c96", "text": "Idempotency means running an operation repeatedly does not cause unintended additional effects."} -{"chunk_id": "chunk:concept:idempotency:use", "concepts": ["idempotency"], "domain": "automation", "heading": "Use", "node_id": "concept:idempotency", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/idempotency.md", "source_hash": "fc2a80065e167e1f9d44e1105d1e6eb195e919674b9a0062c190dd2531c16c96", "text": "Use idempotency when designing retries, resume behavior, reconciliation, and automation safety."} -{"chunk_id": "chunk:concept:metrics:definition", "concepts": ["metrics"], "domain": "observability", "heading": "Definition", "node_id": "concept:metrics", "node_type": "concept", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/concepts/metrics.md", "source_hash": "29aa83aaa364c799ff8d138785bead4a5c01e3d37c5069ab575ab393923daa3f", "text": "Metrics are numeric measurements that should support diagnosis, decisions, or trend analysis."} -{"chunk_id": "chunk:concept:metrics:use", "concepts": ["metrics"], "domain": "observability", "heading": "Use", "node_id": "concept:metrics", "node_type": "concept", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/concepts/metrics.md", "source_hash": "29aa83aaa364c799ff8d138785bead4a5c01e3d37c5069ab575ab393923daa3f", "text": "Use this concept when distinguishing useful evidence from activity-only counts."} -{"chunk_id": "chunk:concept:mutation:definition", "concepts": ["mutation"], "domain": "automation", "heading": "Definition", "node_id": "concept:mutation", "node_type": "concept", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/concepts/mutation.md", "source_hash": "0cf185f663aad760f22bf3641f5c0caaded00782bb7917bd17d35d3b32547af9", "text": "Mutation is an operation that changes system, repository, workflow, or external state."} -{"chunk_id": "chunk:concept:mutation:use", "concepts": ["mutation"], "domain": "automation", "heading": "Use", "node_id": "concept:mutation", "node_type": "concept", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/concepts/mutation.md", "source_hash": "0cf185f663aad760f22bf3641f5c0caaded00782bb7917bd17d35d3b32547af9", "text": "Use this concept when separating reads from writes and planning validation gates."} -{"chunk_id": "chunk:concept:observability:definition", "concepts": ["observability"], "domain": "observability", "heading": "Definition", "node_id": "concept:observability", "node_type": "concept", "outbound_edges": ["map:observability:overview"], "path": "kb/concepts/observability.md", "source_hash": "e5b7583118a968cf5870eaf2d754a9e7ffca579eb6605467b825b5a1a1942942", "text": "Observability is the ability to understand system behavior from emitted evidence."} -{"chunk_id": "chunk:concept:observability:use", "concepts": ["observability"], "domain": "observability", "heading": "Use", "node_id": "concept:observability", "node_type": "concept", "outbound_edges": ["map:observability:overview"], "path": "kb/concepts/observability.md", "source_hash": "e5b7583118a968cf5870eaf2d754a9e7ffca579eb6605467b825b5a1a1942942", "text": "Use this concept when discussing signals, health, diagnostics, reports, and operational review."} -{"chunk_id": "chunk:concept:operability:definition", "concepts": ["operability"], "domain": "repo-wide", "heading": "Definition", "node_id": "concept:operability", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/operability.md", "source_hash": "d1a6cff035ffac1b1b2b871b513efb1de98da7284c491d70b30285624a39d627", "text": "Operability is the ability to run, diagnose, recover, audit, and safely evolve a system."} -{"chunk_id": "chunk:concept:operability:use", "concepts": ["operability"], "domain": "repo-wide", "heading": "Use", "node_id": "concept:operability", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/operability.md", "source_hash": "d1a6cff035ffac1b1b2b871b513efb1de98da7284c491d70b30285624a39d627", "text": "Use operability as a review lens for automation, observability, agent tools, and lifecycle tooling."} -{"chunk_id": "chunk:concept:provenance:definition", "concepts": ["provenance"], "domain": "repo-wide", "heading": "Definition", "node_id": "concept:provenance", "node_type": "concept", "outbound_edges": ["note:operability:future-operators-need-context"], "path": "kb/concepts/provenance.md", "source_hash": "eaf6b2b7877743cba9e712a20bdd37089c0f2e33c3d93f44897ff8bae31373d6", "text": "Provenance is information about where a claim, node, edge, artifact, or decision came from."} -{"chunk_id": "chunk:concept:provenance:use", "concepts": ["provenance"], "domain": "repo-wide", "heading": "Use", "node_id": "concept:provenance", "node_type": "concept", "outbound_edges": ["note:operability:future-operators-need-context"], "path": "kb/concepts/provenance.md", "source_hash": "eaf6b2b7877743cba9e712a20bdd37089c0f2e33c3d93f44897ff8bae31373d6", "text": "Use this concept when reviewing generated artifacts, agent-authored notes, and evidence trails."} -{"chunk_id": "chunk:concept:validation:definition", "concepts": ["validation"], "domain": "repo-wide", "heading": "Definition", "node_id": "concept:validation", "node_type": "concept", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "kb/concepts/validation.md", "source_hash": "8040c1fa6c29caf548c949909d6d95e30ac6032439f6e30b7fb944ad1235cb36", "text": "Validation is explicit checking that rejects invalid source, state, plans, edges, or generated artifacts."} -{"chunk_id": "chunk:concept:validation:use", "concepts": ["validation"], "domain": "repo-wide", "heading": "Use", "node_id": "concept:validation", "node_type": "concept", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "kb/concepts/validation.md", "source_hash": "8040c1fa6c29caf548c949909d6d95e30ac6032439f6e30b7fb944ad1235cb36", "text": "Use this concept when defining lifecycle gates and agent-safe workflows."} -{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:consequences", "concepts": ["second brain", "markdown", "maps of content", "related links"], "domain": "repo-wide", "heading": "Consequences", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d18ffabf1fb08913897ed3e8c6b6147b9817d2758659513bf72893638c6dac92", "text": "- New substantial doctrine pages should include knowledge hooks.\n- README and index pages should act as maps of content.\n- Wiki-link syntax and plugin-specific metadata should be avoided.\n- Cross-domain concepts should be linked rather than duplicated."} -{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:context", "concepts": ["second brain", "markdown", "maps of content", "related links"], "domain": "repo-wide", "heading": "Context", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d18ffabf1fb08913897ed3e8c6b6147b9817d2758659513bf72893638c6dac92", "text": "`tea-style` is a doctrine/reference repository for humans and agents. It needs second-brain retrieval behavior without depending on non-GitHub tools or private note-system syntax."} -{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:decision", "concepts": ["second brain", "markdown", "maps of content", "related links"], "domain": "repo-wide", "heading": "Decision", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d18ffabf1fb08913897ed3e8c6b6147b9817d2758659513bf72893638c6dac92", "text": "Use GitHub-native Markdown as the second-brain substrate.\n\nPages should use:\n- atomic concepts\n- map-of-content README/index pages\n- compact knowledge hooks\n- relative Markdown links\n- related pages sections\n- decision records for durable why"} -{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:rationale", "concepts": ["second brain", "markdown", "maps of content", "related links"], "domain": "repo-wide", "heading": "Rationale", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d18ffabf1fb08913897ed3e8c6b6147b9817d2758659513bf72893638c6dac92", "text": "This keeps the repository readable in GitHub, easy to clone, easy for agents to parse, and independent of local note-taking applications."} -{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:related-pages-decisions", "concepts": ["second brain", "markdown", "maps of content", "related links"], "domain": "repo-wide", "heading": "Related pages/decisions", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d18ffabf1fb08913897ed3e8c6b6147b9817d2758659513bf72893638c6dac92", "text": "- [docs/second-brain-markdown-standard.md](../second-brain-markdown-standard.md)\n- [docs/page-template-standard.md](../page-template-standard.md)\n- [docs/doctrines/engineering-control-spine.md](../doctrines/engineering-control-spine.md)"} -{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:status", "concepts": ["second brain", "markdown", "maps of content", "related links"], "domain": "repo-wide", "heading": "Status", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d18ffabf1fb08913897ed3e8c6b6147b9817d2758659513bf72893638c6dac92", "text": "accepted"} -{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:consequences", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "domain": "repo-wide", "heading": "Consequences", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "e43fc41db82612a521990ce608a024d5838da2797c751d7a90cbdd0f02a856c9", "text": "- Authored graph nodes must use stable IDs.\n- Generated artifacts can be rebuilt from source.\n- Markdown links remain for human navigation.\n- Frontmatter edges carry semantic graph relationships."} -{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:context", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "domain": "repo-wide", "heading": "Context", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "e43fc41db82612a521990ce608a024d5838da2797c751d7a90cbdd0f02a856c9", "text": "`tea-style` needs second-brain behavior that is inspectable in GitHub, useful to humans, and consumable by future autonomous systems."} -{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:decision", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "domain": "repo-wide", "heading": "Decision", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "e43fc41db82612a521990ce608a024d5838da2797c751d7a90cbdd0f02a856c9", "text": "Use Markdown notes and YAML frontmatter as the canonical source of the doctrine graph.\n\nGenerated artifacts such as JSONL files, reports, chunks, and visualizations are derived from source Markdown. They are useful for review and consumption, but they are not canonical."} -{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:rationale", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "domain": "repo-wide", "heading": "Rationale", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "e43fc41db82612a521990ce608a024d5838da2797c751d7a90cbdd0f02a856c9", "text": "Markdown keeps authorship visible. Frontmatter gives the graph enough structure to validate and export. This avoids pushing the repository into a database-first or product-runtime shape."} -{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:related-pages-decisions", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "domain": "repo-wide", "heading": "Related pages/decisions", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "e43fc41db82612a521990ce608a024d5838da2797c751d7a90cbdd0f02a856c9", "text": "- [docs/standards/graph-knowledge-base-standard.md](../standards/graph-knowledge-base-standard.md)\n- [docs/standards/generated-artifact-standard.md](../standards/generated-artifact-standard.md)\n- [docs/doctrines/tea-style-doctrine.md](../doctrines/tea-style-doctrine.md)"} -{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:status", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "domain": "repo-wide", "heading": "Status", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "e43fc41db82612a521990ce608a024d5838da2797c751d7a90cbdd0f02a856c9", "text": "accepted"} -{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:consequences", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "domain": "repo-wide", "heading": "Consequences", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a2d5b0dd7942b32ff6d408f2c7540d8155fdfd3be501b8e15a111a048fd4e8e0", "text": "- Python implementation code belongs under `src/tea_kb/`.\n- Tests belong under `tests/`.\n- Generated artifacts should be deterministic.\n- CI should run validation and stale-artifact checks."} -{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:context", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "domain": "repo-wide", "heading": "Context", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a2d5b0dd7942b32ff6d408f2c7540d8155fdfd3be501b8e15a111a048fd4e8e0", "text": "The repository is becoming a doctrine graph. Manual review alone will not reliably catch duplicate IDs, invalid edges, stale generated artifacts, broken links, orphan notes, or concept drift."} -{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:decision", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "domain": "repo-wide", "heading": "Decision", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a2d5b0dd7942b32ff6d408f2c7540d8155fdfd3be501b8e15a111a048fd4e8e0", "text": "Add a Python package named `tea_kb` and a CLI named `tea-kb`.\n\nThe tool may:\n- read Markdown\n- parse frontmatter\n- validate schema and graph consistency\n- extract sections and chunks\n- build graph artifacts\n- generate reports\n- generate diagnostic visualizations\n- support agent-safe iteration\n\nThe tool must not become a hosted service, production API, full RAG runtime, chat interface, or permanent background process."} -{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:rationale", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "domain": "repo-wide", "heading": "Rationale", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a2d5b0dd7942b32ff6d408f2c7540d8155fdfd3be501b8e15a111a048fd4e8e0", "text": "Bounded lifecycle tooling makes the knowledge base durable and inspectable while staying inside the repository's doctrine/reference scope."} -{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:related-pages-decisions", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "domain": "repo-wide", "heading": "Related pages/decisions", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a2d5b0dd7942b32ff6d408f2c7540d8155fdfd3be501b8e15a111a048fd4e8e0", "text": "- [docs/standards/python-type-discipline.md](../standards/python-type-discipline.md)\n- [docs/standards/generated-artifact-standard.md](../standards/generated-artifact-standard.md)\n- [docs/repo-scope.md](../repo-scope.md)"} -{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:status", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "domain": "repo-wide", "heading": "Status", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a2d5b0dd7942b32ff6d408f2c7540d8155fdfd3be501b8e15a111a048fd4e8e0", "text": "accepted"} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:anti-patterns", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "- hidden mutation inside read-sounding functions\n- global state that controls behavior implicitly\n- raw dictionaries flowing through core logic\n- giant procedural scripts that mix config, validation, transport, logging, and mutation\n- retries without idempotency or reconciliation\n- docs that describe safety without code enforcing it\n- LLM-generated plans that bypass deterministic validation"} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:architecture-mechanics", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "Use these six control surfaces when evaluating design:\n\n1. **Boundaries**\n - Encapsulation, ports/adapters, dependency injection, protocols, anti-corruption layers.\n - Goal: callers depend on behavior, not implementation details.\n\n2. **State**\n - Typed domain models, invariants, immutable plans, state machines, checkpoints, resume rules.\n - Goal: valid states are explicit and invalid states are difficult to construct.\n\n3. **Contracts**\n - Command/query separation, result objects, error taxonomy, schema validation, versioning, backward compatibility.\n - Goal: readers know what a component promises and what can fail.\n\n4. **Change control**\n - Planning before execution, dry-run, validation gates, progressive delivery, blast-radius limits, feature flags, kill switches, human approval.\n - Goal: mutation is deliberate, reviewable, and bounded.\n\n5. **Feedback loops**\n - Idempotency, reconciliation, polling with deadlines, retries with discipline, circuit breakers, backpressure, rate limiting.\n - Goal: the system converges safely instead of assuming a command worked.\n\n6. **Operability**\n - Structured logs, metrics, traces, correlation IDs, evidence, reports, runbooks, data lineage, reproducibility.\n - Goal: operators can answer what ran, why it ran, what changed, what failed, and what evidence proves it."} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:core-claim", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "Good systems are easy to reason about, easy to change, hard to misuse, and observable when they fail."} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:definitions", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "- **Change control**: explicit handling of what can change, who approves it, how it is validated, and how it is recovered.\n- **Boundary**: a public interface where messy internals, external systems, or side effects are contained.\n- **State**: the modeled condition of a system, workflow, object, or external dependency.\n- **Contract**: a promise about inputs, outputs, side effects, errors, compatibility, or behavior.\n- **Feedback loop**: a sense-decide-act-verify cycle that compares desired state with actual state.\n- **Operability**: the ability to run, diagnose, recover, audit, and safely evolve a system."} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:knowledge-hooks", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Knowledge hooks", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "- **Type**: cross-domain doctrine\n- **Domain**: repository-wide\n- **Concepts**: change control, boundaries, state, contracts, feedback loops, operability\n- **Use when**: designing, reviewing, or refactoring systems that must survive real change and failure"} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:priority-patterns", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Priority patterns", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "- typed domain models\n- dependency injection and protocols\n- functional core with imperative shell\n- planning separate from execution\n- state machines for long workflows\n- validation gates before risky work\n- idempotent commands and reconciliation loops\n- explicit error/result/evidence models\n- ports and adapters for external systems\n- contract tests for external APIs\n- observability-driven development"} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:purpose", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "Define the cross-domain engineering model behind TEA beyond any single pattern such as AOP."} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:related-pages", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "- [typed-encapsulated-architecture-style.md](typed-encapsulated-architecture-style.md)\n- [docs/second-brain-markdown-standard.md](../second-brain-markdown-standard.md)\n- [domains/coding/architecture-boundaries.md](../../domains/coding/architecture-boundaries.md)\n- [domains/automation/safe-workflow-design.md](../../domains/automation/safe-workflow-design.md)\n- [domains/agent_arch/control/deterministic-tool-boundaries.md](../../domains/agent_arch/control/deterministic-tool-boundaries.md)"} -{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:review-questions", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "heading": "Review questions", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "text": "Ask these before adding or changing a system:\n\n1. What domain concept is being modeled?\n2. What is the clean input and output?\n3. What state can this be in?\n4. What invariants must always hold?\n5. What can fail?\n6. Is this read-only or mutating?\n7. Is it idempotent?\n8. Can it dry-run?\n9. Can it validate before and after?\n10. What evidence proves it worked?\n11. Can the logic be tested without touching real systems?\n12. Can the external system be swapped later?\n13. Will a teammate or agent understand the boundary?"} -{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:anti-patterns", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "text": "- hidden operational context\n- vanity metrics without decision value\n- scripts only the original author can explain\n- agents hallucinating operational state\n- prose-only reports that cannot be inspected mechanically"} -{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:architecture-mechanics", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "text": "Use this doctrine when reviewing any system that can mutate, diagnose, report, or influence operational decisions.\n\nThe system should answer:\n- what happened\n- why it happened\n- what state it observed\n- what it changed\n- what evidence supports the outcome\n- what a future operator should do next"} -{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:core-claim", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "text": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible."} -{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:definitions", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "text": "- **Tell on themselves**: expose enough state, context, and evidence that future operators do not need hidden author knowledge.\n- **Evidence**: structured proof that a claim, change, validation, or failure actually happened.\n- **Hidden context**: operational knowledge that exists only in a person's memory or an unstated workflow."} -{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:patterns", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "heading": "Patterns", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "text": "- expose state directly\n- capture evidence as data\n- keep mutation visible\n- make boundaries obvious\n- record provenance\n- write reports from structured results"} -{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:purpose", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "text": "Define the root operating philosophy behind the doctrine graph."} -{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:related-pages", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "text": "- [engineering-control-spine.md](engineering-control-spine.md)\n- [docs/standards/graph-knowledge-base-standard.md](../standards/graph-knowledge-base-standard.md)\n- [kb/notes/evidence/systems-should-tell-on-themselves.md](../../kb/notes/evidence/systems-should-tell-on-themselves.md)"} -{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:anti-patterns", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "text": "- treating generated artifacts as canonical\n- turning the repository into a hosted product\n- adding cute tea-themed names to schema or code\n- letting agents create reviewed doctrine silently"} -{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:architecture-mechanics", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "text": "The repository has three layers:\n\n```text\nauthored Markdown/frontmatter\n -> generated graph artifacts and reports\n -> future consumers such as agents, search, and review workflows\n```\n\nThe Python tool supports the knowledge base. It does not define doctrine by itself."} -{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:core-claim", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "text": "`tea-style` is a Markdown-native engineering doctrine graph with embedded Python lifecycle tooling."} -{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:definitions", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "text": "- **Markdown-native**: authored Markdown and frontmatter are the source of truth.\n- **Doctrine graph**: notes, concepts, decisions, standards, examples, and antipatterns connected by explicit semantic edges.\n- **Lifecycle tooling**: local Python code that validates, builds, reports, visualizes, and exports the graph.\n- **Context regression**: repeated rediscovery of knowledge that should have been captured as durable doctrine."} -{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:patterns", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "heading": "Patterns", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "text": "- Capture durable learning as small graph notes.\n- Use concepts to prevent vocabulary drift.\n- Use frontmatter edges for semantic graph relationships.\n- Use Markdown links for human navigation.\n- Commit deterministic generated artifacts when they improve review."} -{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:purpose", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "text": "Define the repository's current identity as both doctrine graph and bounded lifecycle tool."} -{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:related-pages", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "text": "- [systems-should-tell-on-themselves.md](systems-should-tell-on-themselves.md)\n- [engineering-control-spine.md](engineering-control-spine.md)\n- [docs/standards/graph-knowledge-base-standard.md](../standards/graph-knowledge-base-standard.md)\n- [docs/standards/agent-kb-editing-standard.md](../standards/agent-kb-editing-standard.md)"} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:architecture-mechanics", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "TEA is not a framework. It is a decision style.\n\nIt pushes work toward:\n- validated inputs\n- constrained side effects\n- explicit contracts\n- explicit state\n- observable execution\n- modular extension paths\n- predictable review\n\nThe standard structure is:\n\n```text\nuntrusted input\n -> validation and normalization\n -> typed domain objects\n -> pure planning or decision logic\n -> explicit side-effect boundary\n -> result, evidence, and feedback\n```"} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:core-claim", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "Typed Encapsulated Architecture Style is a doctrine for building systems that are explicit, modular, reviewable, and durable."} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:core-ideas", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Core ideas", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "- Prefer strong typing where it clarifies behavior.\n- Keep modules black-boxed with narrow public interfaces.\n- Separate configuration from execution.\n- Prefer maintainable object-oriented structure where it improves consistency.\n- Use protocols, factories, and interface-driven design when they reduce drift across implementations.\n- Keep state and side effects explicit.\n- Model contracts, errors, and results as first-class design concerns.\n- Prefer feedback loops over one-way command assumptions.\n- Keep dependencies lean.\n- Prefer understandable code over clever code."} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:definitions", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "- **Typed**: important data, commands, config, results, and states have explicit structure.\n- **Encapsulated**: internals are hidden behind narrow interfaces that make misuse harder.\n- **Architecture**: dependencies, boundaries, state, and side effects are arranged deliberately.\n- **Style**: a preference system for decisions, not a framework or runtime."} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:knowledge-hooks", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Knowledge hooks", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "- **Type**: cross-domain doctrine\n- **Domain**: repository-wide\n- **Concepts**: typing, encapsulation, architecture, contracts, operability\n- **Use when**: evaluating whether a design fits the repository's core engineering taste"} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:purpose", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "Define the core TEA doctrine for designing systems that are explicit, modular, reviewable, and durable."} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:related-pages", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "- [docs/doctrines/README.md](README.md)\n- [engineering-control-spine.md](engineering-control-spine.md)\n- [docs/second-brain-markdown-standard.md](../second-brain-markdown-standard.md)"} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:standard-question", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "Standard question", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "When evaluating a design, the basic question is:\n\nDoes this make the system easier to understand, safer to extend, and easier to review?\n\nIf not, the complexity likely does not belong."} -{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:what-tea-rejects", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "heading": "What TEA rejects", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "text": "- architecture by novelty\n- hidden global behavior\n- configuration embedded deep inside logic\n- abstractions without a real pressure behind them\n- dependency growth without clear value\n- state that readers must infer from call order\n- mutation that cannot be dry-run, audited, or explained"} -{"chunk_id": "chunk:example:agents:agent-tool-boundary:example", "concepts": ["agents", "boundary", "validation"], "domain": "agent-architecture", "heading": "Example", "node_id": "example:agents:agent-tool-boundary", "node_type": "example", "outbound_edges": ["note:boundaries:tools-should-make-boundaries-obvious", "standard:repo:agent-kb-editing-standard"], "path": "kb/examples/agent-tool-boundary.md", "source_hash": "c87bfb36608e5970b3807017bf958ec3f17e82dc5cc22f4b199ef86048d9f673", "text": "```text\nread_graph()\nvalidate_plan(plan)\nrender_dry_run(plan)\nexecute_approved_plan(plan)\n```"} -{"chunk_id": "chunk:example:agents:agent-tool-boundary:point", "concepts": ["agents", "boundary", "validation"], "domain": "agent-architecture", "heading": "Point", "node_id": "example:agents:agent-tool-boundary", "node_type": "example", "outbound_edges": ["note:boundaries:tools-should-make-boundaries-obvious", "standard:repo:agent-kb-editing-standard"], "path": "kb/examples/agent-tool-boundary.md", "source_hash": "c87bfb36608e5970b3807017bf958ec3f17e82dc5cc22f4b199ef86048d9f673", "text": "The agent proposes. Deterministic tools validate and execute within explicit boundaries."} -{"chunk_id": "chunk:example:automation:safe-automation-script:example", "concepts": ["automation", "evidence", "mutation"], "domain": "automation", "heading": "Example", "node_id": "example:automation:safe-automation-script", "node_type": "example", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "kb/examples/safe-automation-script.md", "source_hash": "e50bcbb2e856b5482ad02b01a6459965a80f14318c095c56290705c92a19d37b", "text": "```text\nload request\nvalidate context\nbuild plan\nrender dry-run\nexecute approved plan\ncollect evidence\nwrite report\n```"} -{"chunk_id": "chunk:example:automation:safe-automation-script:point", "concepts": ["automation", "evidence", "mutation"], "domain": "automation", "heading": "Point", "node_id": "example:automation:safe-automation-script", "node_type": "example", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "kb/examples/safe-automation-script.md", "source_hash": "e50bcbb2e856b5482ad02b01a6459965a80f14318c095c56290705c92a19d37b", "text": "The script is safe because mutation is downstream from validation and planning."} -{"chunk_id": "chunk:example:observability:splunk-health-state:example", "concepts": ["observability", "evidence", "explicit-state"], "domain": "observability", "heading": "Example", "node_id": "example:observability:splunk-health-state", "node_type": "example", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/examples/splunk-health-state.md", "source_hash": "22778c51903c28a91c5f54c78c85f86246f596036bc3c8fe2f6677978b7a5040", "text": "```text\nprocess: splunkd running\napi: REST endpoint responds\ncluster: peer is searchable\nworkflow: host can safely receive work\n```"} -{"chunk_id": "chunk:example:observability:splunk-health-state:point", "concepts": ["observability", "evidence", "explicit-state"], "domain": "observability", "heading": "Point", "node_id": "example:observability:splunk-health-state", "node_type": "example", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/examples/splunk-health-state.md", "source_hash": "22778c51903c28a91c5f54c78c85f86246f596036bc3c8fe2f6677978b7a5040", "text": "Health is layered. A live process is not the same as a ready system."} -{"chunk_id": "chunk:map:agent-architecture:overview:core-pages", "concepts": ["agents", "tool boundaries", "validation", "provenance"], "domain": "agent-architecture", "heading": "Core pages", "node_id": "map:agent-architecture:overview", "node_type": "map", "outbound_edges": ["standard:repo:agent-kb-editing-standard", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/agent-architecture.md", "source_hash": "635c4a912e4ccca15d6ea2cda1f6075b11c8a383ad69f2a027c63eed0a8b25fa", "text": "- [Agent Architecture Principles](../../domains/agent_arch/principles.md)\n- [Deterministic Tool Boundaries](../../domains/agent_arch/control/deterministic-tool-boundaries.md)\n- [Agent KB Editing Standard](../standards/agent-kb-editing-standard.md)"} -{"chunk_id": "chunk:map:agent-architecture:overview:graph-notes", "concepts": ["agents", "tool boundaries", "validation", "provenance"], "domain": "agent-architecture", "heading": "Graph notes", "node_id": "map:agent-architecture:overview", "node_type": "map", "outbound_edges": ["standard:repo:agent-kb-editing-standard", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/agent-architecture.md", "source_hash": "635c4a912e4ccca15d6ea2cda1f6075b11c8a383ad69f2a027c63eed0a8b25fa", "text": "- [Tools Should Make Boundaries Obvious](../../kb/notes/boundaries/tools-should-make-boundaries-obvious.md)\n- [Hidden Context Is Operational Risk](../../kb/notes/context/hidden-context-is-operational-risk.md)"} -{"chunk_id": "chunk:map:automation:overview:core-pages", "concepts": ["idempotency", "mutation", "evidence", "operability"], "domain": "automation", "heading": "Core pages", "node_id": "map:automation:overview", "node_type": "map", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "docs/maps/automation.md", "source_hash": "355f6e8e8028d5cd7918e5029a0c5fa5406f05be2ccac88d819b2859788e0bbf", "text": "- [Automation Principles](../../domains/automation/principles.md)\n- [Safe Workflow Design](../../domains/automation/safe-workflow-design.md)\n- [Engineering Control Spine](../doctrines/engineering-control-spine.md)"} -{"chunk_id": "chunk:map:automation:overview:graph-notes", "concepts": ["idempotency", "mutation", "evidence", "operability"], "domain": "automation", "heading": "Graph notes", "node_id": "map:automation:overview", "node_type": "map", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "docs/maps/automation.md", "source_hash": "355f6e8e8028d5cd7918e5029a0c5fa5406f05be2ccac88d819b2859788e0bbf", "text": "- [Systems Should Tell on Themselves](../../kb/notes/evidence/systems-should-tell-on-themselves.md)\n- [Mutation Should Be Atomic Visible and Hard to Misunderstand](../../kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md)\n- [Future Operators Need Context](../../kb/notes/operability/future-operators-need-context.md)"} -{"chunk_id": "chunk:map:coding:overview:core-pages", "concepts": ["boundaries", "typing", "contracts"], "domain": "coding", "heading": "Core pages", "node_id": "map:coding:overview", "node_type": "map", "outbound_edges": ["standard:repo:python-type-discipline", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/coding.md", "source_hash": "1fd777c4adfb4bb204c94d86935739f8c8af53919c4af0c86ba53ca3a9be1343", "text": "- [Coding Principles](../../domains/coding/principles.md)\n- [Architecture Boundaries](../../domains/coding/architecture-boundaries.md)\n- [Python Type Discipline](../standards/python-type-discipline.md)"} -{"chunk_id": "chunk:map:coding:overview:graph-notes", "concepts": ["boundaries", "typing", "contracts"], "domain": "coding", "heading": "Graph notes", "node_id": "map:coding:overview", "node_type": "map", "outbound_edges": ["standard:repo:python-type-discipline", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/coding.md", "source_hash": "1fd777c4adfb4bb204c94d86935739f8c8af53919c4af0c86ba53ca3a9be1343", "text": "- [Tools Should Make Boundaries Obvious](../../kb/notes/boundaries/tools-should-make-boundaries-obvious.md)\n- [Mutation Should Be Atomic Visible and Hard to Misunderstand](../../kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md)"} -{"chunk_id": "chunk:map:observability:overview:core-pages", "concepts": ["observability", "evidence", "system state"], "domain": "observability", "heading": "Core pages", "node_id": "map:observability:overview", "node_type": "map", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state", "concept:evidence"], "path": "docs/maps/observability.md", "source_hash": "4a9819a06f9ee2982d7dcd2609419c1c173ff456ae9450965f7f907599d09de7", "text": "- [Observability Principles](../../domains/observability/principles.md)\n- [Diagnostic Workflows](../../domains/observability/diagnostic-workflows.md)\n- [Platform Thinking](../../domains/observability/platform-thinking.md)"} -{"chunk_id": "chunk:map:observability:overview:graph-notes", "concepts": ["observability", "evidence", "system state"], "domain": "observability", "heading": "Graph notes", "node_id": "map:observability:overview", "node_type": "map", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state", "concept:evidence"], "path": "docs/maps/observability.md", "source_hash": "4a9819a06f9ee2982d7dcd2609419c1c173ff456ae9450965f7f907599d09de7", "text": "- [Operators Should Not Hallucinate System State](../../kb/notes/observability/operators-should-not-hallucinate-system-state.md)\n- [Systems Should Tell on Themselves](../../kb/notes/evidence/systems-should-tell-on-themselves.md)"} -{"chunk_id": "chunk:map:repo:engineering-doctrine:core-path", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "domain": "repo-wide", "heading": "Core path", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "b1e5f8880d5b7d3ad5d65a9c4df280064bdcebd8f99a47bc0225fa884338439a", "text": "1. [TEA Style Doctrine](../doctrines/tea-style-doctrine.md)\n2. [Systems Should Tell on Themselves](../doctrines/systems-should-tell-on-themselves.md)\n3. [Typed Encapsulated Architecture Style](../doctrines/typed-encapsulated-architecture-style.md)\n4. [Engineering Control Spine](../doctrines/engineering-control-spine.md)"} -{"chunk_id": "chunk:map:repo:engineering-doctrine:domain-maps", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "domain": "repo-wide", "heading": "Domain maps", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "b1e5f8880d5b7d3ad5d65a9c4df280064bdcebd8f99a47bc0225fa884338439a", "text": "- [Coding](coding.md)\n- [Automation](automation.md)\n- [Observability](observability.md)\n- [Agent Architecture](agent-architecture.md)"} -{"chunk_id": "chunk:map:repo:engineering-doctrine:purpose", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "domain": "repo-wide", "heading": "Purpose", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "b1e5f8880d5b7d3ad5d65a9c4df280064bdcebd8f99a47bc0225fa884338439a", "text": "Provide a human navigation entry point for the repo-wide doctrine graph."} -{"chunk_id": "chunk:map:repo:engineering-doctrine:standards-path", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "domain": "repo-wide", "heading": "Standards path", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "b1e5f8880d5b7d3ad5d65a9c4df280064bdcebd8f99a47bc0225fa884338439a", "text": "1. [Graph Knowledge Base Standard](../standards/graph-knowledge-base-standard.md)\n2. [Graph Linking Standard](../standards/graph-linking-standard.md)\n3. [Generated Artifact Standard](../standards/generated-artifact-standard.md)\n4. [Agent KB Editing Standard](../standards/agent-kb-editing-standard.md)"} -{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:core-claim", "concepts": ["boundary", "contract", "mutation", "validation"], "domain": "coding", "heading": "Core claim", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "67e4542285231e248bd08882102d4f91ff7206acdac24d42d5f91518137bd1ec", "text": "A tool should make its boundaries obvious: what it reads, what it writes, what it validates, and what it refuses to do."} -{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:failure-smell", "concepts": ["boundary", "contract", "mutation", "validation"], "domain": "coding", "heading": "Failure smell", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "67e4542285231e248bd08882102d4f91ff7206acdac24d42d5f91518137bd1ec", "text": "A command sounds like a read but performs mutation, or a validator quietly fixes source files."} -{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:related-doctrine", "concepts": ["boundary", "contract", "mutation", "validation"], "domain": "coding", "heading": "Related doctrine", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "67e4542285231e248bd08882102d4f91ff7206acdac24d42d5f91518137bd1ec", "text": "- [Architecture Boundaries](../../../domains/coding/architecture-boundaries.md)\n- [Deterministic Tool Boundaries](../../../domains/agent_arch/control/deterministic-tool-boundaries.md)"} -{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:use-this-when", "concepts": ["boundary", "contract", "mutation", "validation"], "domain": "coding", "heading": "Use this when", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "67e4542285231e248bd08882102d4f91ff7206acdac24d42d5f91518137bd1ec", "text": "Use this when designing CLIs, automation clients, validators, exporters, or agent tools."} -{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:why-it-matters", "concepts": ["boundary", "contract", "mutation", "validation"], "domain": "coding", "heading": "Why it matters", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "67e4542285231e248bd08882102d4f91ff7206acdac24d42d5f91518137bd1ec", "text": "Ambiguous boundaries force humans and agents to infer safety from naming or prose. That is not enough for risky systems."} -{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:core-claim", "concepts": ["operability", "context-regression", "provenance"], "domain": "operability", "heading": "Core claim", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "2eae072416ab707a0a784717ac9ef40e1714fc8c0de7d1fb76d478fa5a9f9f17", "text": "Hidden context is operational risk, even when the code appears simple."} -{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:failure-smell", "concepts": ["operability", "context-regression", "provenance"], "domain": "operability", "heading": "Failure smell", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "2eae072416ab707a0a784717ac9ef40e1714fc8c0de7d1fb76d478fa5a9f9f17", "text": "The workflow works only when someone remembers which machine, token, order, flag, or undocumented exception matters."} -{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:related-doctrine", "concepts": ["operability", "context-regression", "provenance"], "domain": "operability", "heading": "Related doctrine", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "2eae072416ab707a0a784717ac9ef40e1714fc8c0de7d1fb76d478fa5a9f9f17", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)"} -{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:use-this-when", "concepts": ["operability", "context-regression", "provenance"], "domain": "operability", "heading": "Use this when", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "2eae072416ab707a0a784717ac9ef40e1714fc8c0de7d1fb76d478fa5a9f9f17", "text": "Use this when reviewing scripts, docs, runbooks, dashboards, or generated outputs that require unstated assumptions."} -{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:why-it-matters", "concepts": ["operability", "context-regression", "provenance"], "domain": "operability", "heading": "Why it matters", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "2eae072416ab707a0a784717ac9ef40e1714fc8c0de7d1fb76d478fa5a9f9f17", "text": "A workflow that only the original author can explain creates recovery risk, review risk, and agent-editing risk."} -{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:core-claim", "concepts": ["evidence", "observability", "metrics"], "domain": "observability", "heading": "Core claim", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "03464366d74704df3fe70b59b539c8879ebddfa7648ed3621361dde764e8801c", "text": "Evidence beats vanity metrics."} -{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:failure-smell", "concepts": ["evidence", "observability", "metrics"], "domain": "observability", "heading": "Failure smell", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "03464366d74704df3fe70b59b539c8879ebddfa7648ed3621361dde764e8801c", "text": "A report celebrates activity but cannot answer what changed, what failed, or what decision should be made."} -{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:related-doctrine", "concepts": ["evidence", "observability", "metrics"], "domain": "observability", "heading": "Related doctrine", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "03464366d74704df3fe70b59b539c8879ebddfa7648ed3621361dde764e8801c", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)\n- [Observability Principles](../../../domains/observability/principles.md)"} -{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:use-this-when", "concepts": ["evidence", "observability", "metrics"], "domain": "observability", "heading": "Use this when", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "03464366d74704df3fe70b59b539c8879ebddfa7648ed3621361dde764e8801c", "text": "Use this when selecting metrics, evaluating automation, reviewing agent output, or deciding whether a report is useful."} -{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:why-it-matters", "concepts": ["evidence", "observability", "metrics"], "domain": "observability", "heading": "Why it matters", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "03464366d74704df3fe70b59b539c8879ebddfa7648ed3621361dde764e8801c", "text": "Counting PRs, tokens, reports, runs, or dashboards does not prove the system became safer, clearer, or easier to operate."} -{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:core-claim", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "domain": "repo-wide", "heading": "Core claim", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "431dc9c90e89a3bbcd8007259dfc5d390143579b2e3d20aae8f4e6dc2d8110c2", "text": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible."} -{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:failure-smell", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "domain": "repo-wide", "heading": "Failure smell", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "431dc9c90e89a3bbcd8007259dfc5d390143579b2e3d20aae8f4e6dc2d8110c2", "text": "If future operators must ask the original author what happened, the system failed to tell on itself."} -{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:related-doctrine", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "domain": "repo-wide", "heading": "Related doctrine", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "431dc9c90e89a3bbcd8007259dfc5d390143579b2e3d20aae8f4e6dc2d8110c2", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)\n- [Engineering Control Spine](../../../docs/doctrines/engineering-control-spine.md)"} -{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:use-this-when", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "domain": "repo-wide", "heading": "Use this when", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "431dc9c90e89a3bbcd8007259dfc5d390143579b2e3d20aae8f4e6dc2d8110c2", "text": "Use this when reviewing scripts, automation, observability systems, compliance knowledge, or agent workflows that mutate or describe real systems."} -{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:why-it-matters", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "domain": "repo-wide", "heading": "Why it matters", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "431dc9c90e89a3bbcd8007259dfc5d390143579b2e3d20aae8f4e6dc2d8110c2", "text": "Systems that only work because people carry hidden context are not simple. They are undocumented risk."} -{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:core-claim", "concepts": ["mutation", "evidence", "change-control", "validation"], "domain": "automation", "heading": "Core claim", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "d73c7358c6f44cfd23cc50cadaf111d74654d6cc9c34288ce41b8fc2c7b97cc1", "text": "If a mutation happens, it should be atomic, visible, and hard to misunderstand."} -{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:failure-smell", "concepts": ["mutation", "evidence", "change-control", "validation"], "domain": "automation", "heading": "Failure smell", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "d73c7358c6f44cfd23cc50cadaf111d74654d6cc9c34288ce41b8fc2c7b97cc1", "text": "A tool changes production state without a plan, dry-run, validation gate, change context, or structured result."} -{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:related-doctrine", "concepts": ["mutation", "evidence", "change-control", "validation"], "domain": "automation", "heading": "Related doctrine", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "d73c7358c6f44cfd23cc50cadaf111d74654d6cc9c34288ce41b8fc2c7b97cc1", "text": "- [Safe Workflow Design](../../../domains/automation/safe-workflow-design.md)\n- [Engineering Control Spine](../../../docs/doctrines/engineering-control-spine.md)"} -{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:use-this-when", "concepts": ["mutation", "evidence", "change-control", "validation"], "domain": "automation", "heading": "Use this when", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "d73c7358c6f44cfd23cc50cadaf111d74654d6cc9c34288ce41b8fc2c7b97cc1", "text": "Use this when reviewing automation, generated plans, CLIs, remediation scripts, or agent tools that can change state."} -{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:why-it-matters", "concepts": ["mutation", "evidence", "change-control", "validation"], "domain": "automation", "heading": "Why it matters", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "d73c7358c6f44cfd23cc50cadaf111d74654d6cc9c34288ce41b8fc2c7b97cc1", "text": "Invisible or ambiguous mutation is how automation creates incidents while appearing convenient."} -{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:core-claim", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "domain": "observability", "heading": "Core claim", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d117bf010b09488ad271a2105ef3ad5f66492c44b2696232546a39faeaae39b9", "text": "Operators and agents should not hallucinate system state. They should inspect evidence."} -{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:failure-smell", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "domain": "observability", "heading": "Failure smell", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d117bf010b09488ad271a2105ef3ad5f66492c44b2696232546a39faeaae39b9", "text": "A system declares health or failure without exposing the checks, timestamps, sources, or confidence behind the claim."} -{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:related-doctrine", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "domain": "observability", "heading": "Related doctrine", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d117bf010b09488ad271a2105ef3ad5f66492c44b2696232546a39faeaae39b9", "text": "- [Observability Principles](../../../domains/observability/principles.md)\n- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)"} -{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:use-this-when", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "domain": "observability", "heading": "Use this when", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d117bf010b09488ad271a2105ef3ad5f66492c44b2696232546a39faeaae39b9", "text": "Use this when designing dashboards, health checks, agent workflows, triage reports, or status pages."} -{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:why-it-matters", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "domain": "observability", "heading": "Why it matters", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d117bf010b09488ad271a2105ef3ad5f66492c44b2696232546a39faeaae39b9", "text": "Operational guesses can trigger wrong remediations, false confidence, and wasted incident time."} -{"chunk_id": "chunk:note:operability:future-operators-need-context:core-claim", "concepts": ["operability", "provenance", "context-regression", "evidence"], "domain": "operability", "heading": "Core claim", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "0f45a679d6e41d377b94a1b9d3c380fb8cfa0cbd260688ee6828f791d7e81fcf", "text": "Future operators need context at the point of use, not in the original author's memory."} -{"chunk_id": "chunk:note:operability:future-operators-need-context:failure-smell", "concepts": ["operability", "provenance", "context-regression", "evidence"], "domain": "operability", "heading": "Failure smell", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "0f45a679d6e41d377b94a1b9d3c380fb8cfa0cbd260688ee6828f791d7e81fcf", "text": "The output says a step failed, but does not say what was checked, what state was observed, or what action is safe next."} -{"chunk_id": "chunk:note:operability:future-operators-need-context:related-doctrine", "concepts": ["operability", "provenance", "context-regression", "evidence"], "domain": "operability", "heading": "Related doctrine", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "0f45a679d6e41d377b94a1b9d3c380fb8cfa0cbd260688ee6828f791d7e81fcf", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)"} -{"chunk_id": "chunk:note:operability:future-operators-need-context:use-this-when", "concepts": ["operability", "provenance", "context-regression", "evidence"], "domain": "operability", "heading": "Use this when", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "0f45a679d6e41d377b94a1b9d3c380fb8cfa0cbd260688ee6828f791d7e81fcf", "text": "Use this when writing reports, runbooks, generated artifacts, validation output, or workflow status records."} -{"chunk_id": "chunk:note:operability:future-operators-need-context:why-it-matters", "concepts": ["operability", "provenance", "context-regression", "evidence"], "domain": "operability", "heading": "Why it matters", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "0f45a679d6e41d377b94a1b9d3c380fb8cfa0cbd260688ee6828f791d7e81fcf", "text": "The operational cost of a tool is paid during failure, handoff, and modification. Missing context compounds that cost."} -{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:agent-pr-checklist", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "domain": "agent-architecture", "heading": "Agent PR checklist", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "0fa9832f6491e93e1a071cb7a781202334f0a873baf803e93d92117d4326be65", "text": "- New notes are small and focused.\n- IDs are stable and meaningful.\n- Concepts reuse existing vocabulary.\n- Edges are justified.\n- Generated artifacts are updated.\n- Validation passes.\n- Reports were reviewed.\n- No unrelated restructuring was introduced."} -{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:core-claim", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "domain": "agent-architecture", "heading": "Core claim", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "0fa9832f6491e93e1a071cb7a781202334f0a873baf803e93d92117d4326be65", "text": "Agents may propose graph changes. They must not silently promote inferred doctrine to reviewed doctrine."} -{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:frontmatter-policy", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "domain": "agent-architecture", "heading": "Frontmatter policy", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "0fa9832f6491e93e1a071cb7a781202334f0a873baf803e93d92117d4326be65", "text": "Agent-created note:\n\n```yaml\norigin:\n author: agent\n review: proposed\n```\n\nHuman-reviewed agent note:\n\n```yaml\norigin:\n author: agent\n review: reviewed\n```\n\nManual note:\n\n```yaml\norigin:\n author: human\n review: manual\n```"} -{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:purpose", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "domain": "agent-architecture", "heading": "Purpose", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "0fa9832f6491e93e1a071cb7a781202334f0a873baf803e93d92117d4326be65", "text": "Define how autonomous or assisted editing should change the doctrine graph safely."} -{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:related-pages", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "domain": "agent-architecture", "heading": "Related pages", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "0fa9832f6491e93e1a071cb7a781202334f0a873baf803e93d92117d4326be65", "text": "- [graph-linking-standard.md](graph-linking-standard.md)\n- [domains/agent_arch/control/deterministic-tool-boundaries.md](../../domains/agent_arch/control/deterministic-tool-boundaries.md)"} -{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:rules-standards", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "domain": "agent-architecture", "heading": "Rules / standards", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "0fa9832f6491e93e1a071cb7a781202334f0a873baf803e93d92117d4326be65", "text": "- Prefer small notes over bloated pages.\n- Reuse existing concepts before inventing new ones.\n- Create concept notes when a concept becomes important.\n- Do not create edges just because words are similar.\n- Mark inferred edges as proposed unless the user explicitly reviewed them.\n- Do not silently redefine core doctrine.\n- Do not rename IDs casually.\n- Run validation before finishing.\n- Update maps only when navigation materially improves."} -{"chunk_id": "chunk:standard:repo:generated-artifact-standard:core-claim", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "f6c03341ae01906532e8f3557cae5c7cce4d29f12c5c86d6b1f7bdfd57795192", "text": "Generated artifacts are derived from Markdown/frontmatter. They are committed when they are stable and useful for review."} -{"chunk_id": "chunk:standard:repo:generated-artifact-standard:generated-artifacts", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "domain": "repo-wide", "heading": "Generated artifacts", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "f6c03341ae01906532e8f3557cae5c7cce4d29f12c5c86d6b1f7bdfd57795192", "text": "- `graph/generated/nodes.jsonl`\n- `graph/generated/edges.jsonl`\n- `graph/generated/chunks.jsonl`\n- `graph/generated/concepts.jsonl`\n- `graph/generated/reports/health.md`\n- `graph/generated/reports/orphan-notes.md`\n- `graph/generated/reports/dense-links.md`\n- `graph/generated/reports/duplicate-concepts.md`\n- `graph/generated/reports/proposed-edges.md`\n- `graph/generated/visualizations/overview.html`"} -{"chunk_id": "chunk:standard:repo:generated-artifact-standard:purpose", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "f6c03341ae01906532e8f3557cae5c7cce4d29f12c5c86d6b1f7bdfd57795192", "text": "Define which generated files exist and how they are reviewed."} -{"chunk_id": "chunk:standard:repo:generated-artifact-standard:related-pages", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "f6c03341ae01906532e8f3557cae5c7cce4d29f12c5c86d6b1f7bdfd57795192", "text": "- [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md)\n- [visualization-standard.md](visualization-standard.md)"} -{"chunk_id": "chunk:standard:repo:generated-artifact-standard:rules-standards", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "f6c03341ae01906532e8f3557cae5c7cce4d29f12c5c86d6b1f7bdfd57795192", "text": "- Generated artifacts must be deterministic.\n- `tea-kb build --check` fails when generated artifacts are stale.\n- Generated files are not canonical.\n- Reports should be boring, useful, and reviewable.\n- JSONL exports should be stable-sorted by ID or edge tuple.\n- Visualization output should avoid avoidable randomness."} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:core-claim", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "Markdown notes and frontmatter are the authored source of truth. Graph artifacts are generated from that source."} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:definitions", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Definitions", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "- **Note**: primary authored graph node.\n- **Chunk**: generated search unit derived from a node section.\n- **Concept**: controlled vocabulary entry.\n- **Frontmatter edge**: semantic relationship between graph nodes.\n- **Generated artifact**: derived JSONL, report, or visualization."} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:edge-types", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Edge types", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "Use only:\n- `supports`\n- `refines`\n- `depends_on`\n- `contradicts`\n- `applies_to`\n- `exemplifies`\n- `supersedes`\n- `related_to`"} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:id-rules", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "ID rules", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "IDs are lowercase, kebab-case, type-prefixed, and stable after creation.\n\nPreferred form:\n\n```text\n::\n```\n\nConcept and antipattern IDs may use:\n\n```text\nconcept:\nantipattern:\n```"} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:node-types", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Node types", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "Use only:\n- `note`\n- `doctrine`\n- `concept`\n- `antipattern`\n- `decision`\n- `example`\n- `standard`\n- `map`"} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:purpose", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "Define the canonical Markdown graph model for `tea-style`."} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:related-pages", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "- [graph/schema.md](../../graph/schema.md)\n- [graph-linking-standard.md](graph-linking-standard.md)\n- [generated-artifact-standard.md](generated-artifact-standard.md)"} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:required-frontmatter", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Required frontmatter", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "```yaml\nid: note:evidence:example\ntitle: Example\ntype: note\ndomain: repo-wide\nstatus: active\nconcepts:\n - evidence\n```"} -{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:rules-standards", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "text": "- Use industry terms in schema, code, exports, and validators.\n- Use tea-themed language only in prose, aliases, section flavor, and report titles.\n- Use readable IDs instead of UUIDs.\n- Keep authored notes smaller than broad doctrine pages.\n- Do not make every Markdown link a graph edge.\n- Do not make every Markdown section a graph node.\n- Do not treat generated artifacts as canonical."} -{"chunk_id": "chunk:standard:repo:graph-linking-standard:anti-patterns", "concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "text": "- creating edges because two pages share a keyword\n- overusing `related_to`\n- using frontmatter edges for ordinary navigation\n- creating edges to missing or planned nodes"} -{"chunk_id": "chunk:standard:repo:graph-linking-standard:core-claim", "concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "text": "Markdown links are for human navigation. Frontmatter edges are for semantic graph relationships."} -{"chunk_id": "chunk:standard:repo:graph-linking-standard:definitions", "concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "heading": "Definitions", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "text": "- **Semantic edge**: a typed relationship that changes how the graph should be interpreted.\n- **Loose relation**: a weak association that may not deserve an edge.\n- **Link explosion**: too many low-value edges on a node."} -{"chunk_id": "chunk:standard:repo:graph-linking-standard:edge-semantics", "concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "heading": "Edge semantics", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "text": "- `supports`: source strengthens target.\n- `refines`: source makes target more specific.\n- `depends_on`: source requires target to make sense.\n- `contradicts`: source explicitly rejects target.\n- `applies_to`: source is relevant to target.\n- `exemplifies`: source demonstrates target.\n- `supersedes`: source replaces target.\n- `related_to`: source is loosely connected to target."} -{"chunk_id": "chunk:standard:repo:graph-linking-standard:purpose", "concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "text": "Control graph edge quality so the doctrine graph remains useful instead of becoming a link hairball."} -{"chunk_id": "chunk:standard:repo:graph-linking-standard:related-pages", "concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "text": "- [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md)\n- [agent-kb-editing-standard.md](agent-kb-editing-standard.md)"} -{"chunk_id": "chunk:standard:repo:graph-linking-standard:rules-standards", "concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "text": "- Create an edge only when the relationship is meaningful and reviewable.\n- Prefer `supports`, `refines`, `depends_on`, `contradicts`, `applies_to`, `exemplifies`, or `supersedes` over `related_to`.\n- Use `related_to` sparingly.\n- `depends_on` and `supersedes` should be acyclic.\n- Do not infer edges from shared words alone.\n- Mark agent-inferred edges as proposed until reviewed.\n- Every edge target must resolve to an authored node."} -{"chunk_id": "chunk:standard:repo:python-type-discipline:core-claim", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "domain": "coding", "heading": "Core claim", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "dcb9705cd7bd226579c4c84c974307c0dffe1baaabe5df9c29de4a6595c58dff", "text": "Use the lowest type layer that solves the problem."} -{"chunk_id": "chunk:standard:repo:python-type-discipline:definitions", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "domain": "coding", "heading": "Definitions", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "dcb9705cd7bd226579c4c84c974307c0dffe1baaabe5df9c29de4a6595c58dff", "text": "- **Boundary model**: Pydantic model used to validate untrusted Markdown/frontmatter/config input.\n- **Domain model**: frozen dataclass used inside trusted core logic.\n- **Semantic ID**: `NewType` wrapper for IDs that should not be casually mixed.\n- **Protocol**: small behavior contract used at module boundaries."} -{"chunk_id": "chunk:standard:repo:python-type-discipline:purpose", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "domain": "coding", "heading": "Purpose", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "dcb9705cd7bd226579c4c84c974307c0dffe1baaabe5df9c29de4a6595c58dff", "text": "Define the type discipline for the `tea_kb` lifecycle tool."} -{"chunk_id": "chunk:standard:repo:python-type-discipline:related-pages", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "domain": "coding", "heading": "Related pages", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "dcb9705cd7bd226579c4c84c974307c0dffe1baaabe5df9c29de4a6595c58dff", "text": "- [domains/coding/architecture-boundaries.md](../../domains/coding/architecture-boundaries.md)\n- [docs/doctrines/typed-encapsulated-architecture-style.md](../doctrines/typed-encapsulated-architecture-style.md)"} -{"chunk_id": "chunk:standard:repo:python-type-discipline:rules-standards", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "domain": "coding", "heading": "Rules / standards", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "dcb9705cd7bd226579c4c84c974307c0dffe1baaabe5df9c29de4a6595c58dff", "text": "- Use Pydantic at file/config boundaries.\n- Use frozen slots dataclasses for internal graph objects.\n- Use `NewType` for node, edge, chunk, and concept IDs.\n- Use `StrEnum` for node and edge categories.\n- Use `Protocol` for reader, exporter, and validator behavior.\n- Use `collections.abc` for function input typing.\n- Use `defaultdict`, `Counter`, and `deque` for graph support where appropriate.\n- Keep domain code independent of Typer, Rich, PyVis, and filesystem details."} -{"chunk_id": "chunk:standard:repo:python-type-discipline:tool-mapping", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "domain": "coding", "heading": "Tool mapping", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "dcb9705cd7bd226579c4c84c974307c0dffe1baaabe5df9c29de4a6595c58dff", "text": "| Problem | Tool |\n|---|---|\n| Frontmatter validation | Pydantic |\n| Config validation | Pydantic |\n| Internal graph objects | frozen slots dataclasses |\n| Semantic IDs | `NewType` |\n| Node/edge categories | `StrEnum` |\n| Plugin-like behavior | `Protocol` |\n| Function input typing | `collections.abc` |\n| Concept frequency | `Counter` |\n| Graph traversal | `deque` |"} -{"chunk_id": "chunk:standard:repo:visualization-standard:anti-patterns", "concepts": ["visualization", "diagnostics", "graph", "source links"], "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "f62e6f03edc7caea1e40ac89849b4de55adeb0ad2392efaef911bdfcb2fb2d59", "text": "- huge all-node/all-edge views with no diagnostic purpose\n- decorative diagrams that do not affect review\n- visuals with no source path or provenance"} -{"chunk_id": "chunk:standard:repo:visualization-standard:core-claim", "concepts": ["visualization", "diagnostics", "graph", "source links"], "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "f62e6f03edc7caea1e40ac89849b4de55adeb0ad2392efaef911bdfcb2fb2d59", "text": "Visualizations are diagnostic. They should answer a question."} -{"chunk_id": "chunk:standard:repo:visualization-standard:good-visualizations", "concepts": ["visualization", "diagnostics", "graph", "source links"], "domain": "repo-wide", "heading": "Good visualizations", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "f62e6f03edc7caea1e40ac89849b4de55adeb0ad2392efaef911bdfcb2fb2d59", "text": "- concept neighborhood\n- domain cluster\n- doctrine path\n- contradiction map\n- orphan note map\n- dense-link warning map\n- proposed-edge review map"} -{"chunk_id": "chunk:standard:repo:visualization-standard:purpose", "concepts": ["visualization", "diagnostics", "graph", "source links"], "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "f62e6f03edc7caea1e40ac89849b4de55adeb0ad2392efaef911bdfcb2fb2d59", "text": "Define how graph visualizations should be generated and reviewed."} -{"chunk_id": "chunk:standard:repo:visualization-standard:related-pages", "concepts": ["visualization", "diagnostics", "graph", "source links"], "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "f62e6f03edc7caea1e40ac89849b4de55adeb0ad2392efaef911bdfcb2fb2d59", "text": "- [generated-artifact-standard.md](generated-artifact-standard.md)\n- [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md)"} -{"chunk_id": "chunk:standard:repo:visualization-standard:rules-standards", "concepts": ["visualization", "diagnostics", "graph", "source links"], "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "f62e6f03edc7caea1e40ac89849b4de55adeb0ad2392efaef911bdfcb2fb2d59", "text": "- Do not default to a full graph hairball.\n- Prefer filtered views such as concept neighborhoods, domain clusters, paths, contradictions, or orphans.\n- Limit default depth to one or two hops.\n- Show node type, domain, and edge labels.\n- Link visual nodes back to source Markdown when practical.\n- Generated visualizations must be deterministic enough for review."} +{"chunk_id": "chunk:antipattern:hallucinated-operational-state:detection", "concepts": ["observability", "explicit-state", "evidence"], "created": "2026-06-07", "domain": "observability", "heading": "Detection", "node_id": "antipattern:hallucinated-operational-state", "node_type": "antipattern", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/antipatterns/hallucinated-operational-state.md", "source_hash": "012874934322f6dd181146d8d9a1aa114fb287f78f488fa55bdce1dc5ec0e12e", "text": "Status is asserted without source, timestamp, check result, or confidence boundary.", "updated": "2026-06-07"} +{"chunk_id": "chunk:antipattern:hallucinated-operational-state:failure-mode", "concepts": ["observability", "explicit-state", "evidence"], "created": "2026-06-07", "domain": "observability", "heading": "Failure mode", "node_id": "antipattern:hallucinated-operational-state", "node_type": "antipattern", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/antipatterns/hallucinated-operational-state.md", "source_hash": "012874934322f6dd181146d8d9a1aa114fb287f78f488fa55bdce1dc5ec0e12e", "text": "A human, agent, or tool claims current system state without evidence from authoritative sources.", "updated": "2026-06-07"} +{"chunk_id": "chunk:antipattern:hidden-operational-context:detection", "concepts": ["operability", "context-regression"], "created": "2026-06-07", "domain": "operability", "heading": "Detection", "node_id": "antipattern:hidden-operational-context", "node_type": "antipattern", "outbound_edges": ["note:context:hidden-context-is-operational-risk"], "path": "kb/antipatterns/hidden-operational-context.md", "source_hash": "025ffd2524030434edbe42f0b38e65adad73df6afa43fd5747762324f7274972", "text": "Reviewers cannot determine valid inputs, state, risks, or next actions from the source and generated evidence.", "updated": "2026-06-07"} +{"chunk_id": "chunk:antipattern:hidden-operational-context:failure-mode", "concepts": ["operability", "context-regression"], "created": "2026-06-07", "domain": "operability", "heading": "Failure mode", "node_id": "antipattern:hidden-operational-context", "node_type": "antipattern", "outbound_edges": ["note:context:hidden-context-is-operational-risk"], "path": "kb/antipatterns/hidden-operational-context.md", "source_hash": "025ffd2524030434edbe42f0b38e65adad73df6afa43fd5747762324f7274972", "text": "A system relies on unstated human knowledge to operate, diagnose, or recover safely.", "updated": "2026-06-07"} +{"chunk_id": "chunk:antipattern:undocumented-mutation:detection", "concepts": ["mutation", "evidence"], "created": "2026-06-07", "domain": "automation", "heading": "Detection", "node_id": "antipattern:undocumented-mutation", "node_type": "antipattern", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/antipatterns/undocumented-mutation.md", "source_hash": "7705be70f5f6cd16e8d4c1d1834a2cef4fecf4f83825f39bb5ec5e1ebd5356bf", "text": "Mutation is hidden inside read-sounding commands, broad scripts, prose-only output, or implicit side effects.", "updated": "2026-06-07"} +{"chunk_id": "chunk:antipattern:undocumented-mutation:failure-mode", "concepts": ["mutation", "evidence"], "created": "2026-06-07", "domain": "automation", "heading": "Failure mode", "node_id": "antipattern:undocumented-mutation", "node_type": "antipattern", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/antipatterns/undocumented-mutation.md", "source_hash": "7705be70f5f6cd16e8d4c1d1834a2cef4fecf4f83825f39bb5ec5e1ebd5356bf", "text": "A tool mutates state without making the mutation visible, reviewable, or recoverable.", "updated": "2026-06-07"} +{"chunk_id": "chunk:antipattern:vanity-metrics:detection", "concepts": ["evidence", "metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Detection", "node_id": "antipattern:vanity-metrics", "node_type": "antipattern", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/antipatterns/vanity-metrics.md", "source_hash": "8e0f0d24d2a6ad4f57fa54d88f7a31cd3090ac84f9e10e9853243ff4b27722d3", "text": "The metric cannot answer what changed, what failed, what risk moved, or what action should happen next.", "updated": "2026-06-07"} +{"chunk_id": "chunk:antipattern:vanity-metrics:failure-mode", "concepts": ["evidence", "metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Failure mode", "node_id": "antipattern:vanity-metrics", "node_type": "antipattern", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/antipatterns/vanity-metrics.md", "source_hash": "8e0f0d24d2a6ad4f57fa54d88f7a31cd3090ac84f9e10e9853243ff4b27722d3", "text": "A metric demonstrates activity but does not improve decision quality or operational clarity.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:agents:definition", "concepts": ["agents"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Definition", "node_id": "concept:agents", "node_type": "concept", "outbound_edges": ["standard:repo:agent-kb-editing-standard"], "path": "kb/concepts/agents.md", "source_hash": "24ccfa334bd56a999170a2b88da59c6ac25bf9254d55e04e19ea06311c7a39b5", "text": "Agents are software actors that use model output, tools, context, and control boundaries to perform work.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:agents:use", "concepts": ["agents"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Use", "node_id": "concept:agents", "node_type": "concept", "outbound_edges": ["standard:repo:agent-kb-editing-standard"], "path": "kb/concepts/agents.md", "source_hash": "24ccfa334bd56a999170a2b88da59c6ac25bf9254d55e04e19ea06311c7a39b5", "text": "Use this concept when discussing agent workflows, tool exposure, and review boundaries.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:automation:definition", "concepts": ["automation"], "created": "2026-06-07", "domain": "automation", "heading": "Definition", "node_id": "concept:automation", "node_type": "concept", "outbound_edges": ["map:automation:overview"], "path": "kb/concepts/automation.md", "source_hash": "e6b3c224f21044e9d590fea68f460de4bb081e7762eeba8636431912ba5e92f6", "text": "Automation is software-controlled execution of repeatable operational or engineering work.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:automation:use", "concepts": ["automation"], "created": "2026-06-07", "domain": "automation", "heading": "Use", "node_id": "concept:automation", "node_type": "concept", "outbound_edges": ["map:automation:overview"], "path": "kb/concepts/automation.md", "source_hash": "e6b3c224f21044e9d590fea68f460de4bb081e7762eeba8636431912ba5e92f6", "text": "Use this concept when discussing scripts, workflows, remediation, and platform operations.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:boundary:definition", "concepts": ["boundary", "encapsulation"], "created": "2026-06-07", "domain": "coding", "heading": "Definition", "node_id": "concept:boundary", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/boundary.md", "source_hash": "a1192857b4b2b2739e768c0870306fcc2e44b45619e40dee2c4a79e9ee2b5210", "text": "A boundary is a public interface where messy internals, external systems, or side effects are contained.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:boundary:use", "concepts": ["boundary", "encapsulation"], "created": "2026-06-07", "domain": "coding", "heading": "Use", "node_id": "concept:boundary", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/boundary.md", "source_hash": "a1192857b4b2b2739e768c0870306fcc2e44b45619e40dee2c4a79e9ee2b5210", "text": "Use boundaries to keep callers dependent on behavior instead of implementation details.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:change-control:definition", "concepts": ["change-control"], "created": "2026-06-07", "domain": "automation", "heading": "Definition", "node_id": "concept:change-control", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/change-control.md", "source_hash": "90fbf59d42d8b22421336f3306e5bceec51770ecf91f85c250f0549dc1038856", "text": "Change control is explicit handling of what can change, who approves it, how it is validated, and how it is recovered.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:change-control:use", "concepts": ["change-control"], "created": "2026-06-07", "domain": "automation", "heading": "Use", "node_id": "concept:change-control", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/change-control.md", "source_hash": "90fbf59d42d8b22421336f3306e5bceec51770ecf91f85c250f0549dc1038856", "text": "Use this concept when mutation must be bounded, reviewable, and recoverable.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:context-regression:definition", "concepts": ["context-regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definition", "node_id": "concept:context-regression", "node_type": "concept", "outbound_edges": ["doctrine:repo:tea-style-doctrine"], "path": "kb/concepts/context-regression.md", "source_hash": "935e7a95105c734fc883e4468bdfa4e79dfc1b70155dfe825aa1cc75c667deb4", "text": "Context regression is rediscovery of knowledge that should already exist as durable doctrine.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:context-regression:use", "concepts": ["context-regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Use", "node_id": "concept:context-regression", "node_type": "concept", "outbound_edges": ["doctrine:repo:tea-style-doctrine"], "path": "kb/concepts/context-regression.md", "source_hash": "935e7a95105c734fc883e4468bdfa4e79dfc1b70155dfe825aa1cc75c667deb4", "text": "Use this concept when deciding whether a new learning should become a note, concept, decision, or standard.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:contract:definition", "concepts": ["contract"], "created": "2026-06-07", "domain": "coding", "heading": "Definition", "node_id": "concept:contract", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/contract.md", "source_hash": "351cc302acbafbe1a4a15734fb1dabe24980c5cdf43f52046ba31a4d58011a72", "text": "A contract is a promise about inputs, outputs, side effects, errors, compatibility, or behavior.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:contract:use", "concepts": ["contract"], "created": "2026-06-07", "domain": "coding", "heading": "Use", "node_id": "concept:contract", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/contract.md", "source_hash": "351cc302acbafbe1a4a15734fb1dabe24980c5cdf43f52046ba31a4d58011a72", "text": "Use contracts when defining protocols, schemas, CLI output, generated artifacts, and validation results.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:diagnostics:definition", "concepts": ["diagnostics"], "created": "2026-06-07", "domain": "observability", "heading": "Definition", "node_id": "concept:diagnostics", "node_type": "concept", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/concepts/diagnostics.md", "source_hash": "825cb8afeebd7b3d97cd57a6331f5878dde574a3c7f93a85e891a355b67f1d8c", "text": "Diagnostics are evidence and methods used to determine what is happening and why.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:diagnostics:use", "concepts": ["diagnostics"], "created": "2026-06-07", "domain": "observability", "heading": "Use", "node_id": "concept:diagnostics", "node_type": "concept", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/concepts/diagnostics.md", "source_hash": "825cb8afeebd7b3d97cd57a6331f5878dde574a3c7f93a85e891a355b67f1d8c", "text": "Use this concept when building reports, health checks, triage flows, and graph warnings.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:evidence:definition", "concepts": ["evidence"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definition", "node_id": "concept:evidence", "node_type": "concept", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves"], "path": "kb/concepts/evidence.md", "source_hash": "84178afd04bd0c967b09a08f5af7f00d4462635f028ed5dfb15891c8bce00016", "text": "Evidence is structured proof that supports a claim about state, change, validation, failure, or decision quality.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:evidence:related-pages", "concepts": ["evidence"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "concept:evidence", "node_type": "concept", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves"], "path": "kb/concepts/evidence.md", "source_hash": "84178afd04bd0c967b09a08f5af7f00d4462635f028ed5dfb15891c8bce00016", "text": "- [Systems Should Tell on Themselves](../../docs/doctrines/systems-should-tell-on-themselves.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:evidence:use", "concepts": ["evidence"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Use", "node_id": "concept:evidence", "node_type": "concept", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves"], "path": "kb/concepts/evidence.md", "source_hash": "84178afd04bd0c967b09a08f5af7f00d4462635f028ed5dfb15891c8bce00016", "text": "Use evidence when a system needs to justify what it did or what it believes.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:explicit-state:definition", "concepts": ["explicit-state", "state"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definition", "node_id": "concept:explicit-state", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/explicit-state.md", "source_hash": "9db8575d1ef4e79bc01627a5e0d9bd7ad8dee93851e6ead43912130f252878d8", "text": "Explicit state is modeled state that humans and tools can inspect without guessing from call order or hidden globals.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:explicit-state:use", "concepts": ["explicit-state", "state"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Use", "node_id": "concept:explicit-state", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/explicit-state.md", "source_hash": "9db8575d1ef4e79bc01627a5e0d9bd7ad8dee93851e6ead43912130f252878d8", "text": "Use explicit state for workflows, generated artifacts, reports, plans, and validation output.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:idempotency:definition", "concepts": ["idempotency"], "created": "2026-06-07", "domain": "automation", "heading": "Definition", "node_id": "concept:idempotency", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/idempotency.md", "source_hash": "e4637e2dae4d3a6bd1bc13b8bac6f898bd140f2829f2d3c71644f1ec4435a8ad", "text": "Idempotency means running an operation repeatedly does not cause unintended additional effects.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:idempotency:use", "concepts": ["idempotency"], "created": "2026-06-07", "domain": "automation", "heading": "Use", "node_id": "concept:idempotency", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/idempotency.md", "source_hash": "e4637e2dae4d3a6bd1bc13b8bac6f898bd140f2829f2d3c71644f1ec4435a8ad", "text": "Use idempotency when designing retries, resume behavior, reconciliation, and automation safety.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:metrics:definition", "concepts": ["metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Definition", "node_id": "concept:metrics", "node_type": "concept", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/concepts/metrics.md", "source_hash": "a645635646fea74b513f570e840159801e7f7d1e8c05ef428c952edfe3a5c079", "text": "Metrics are numeric measurements that should support diagnosis, decisions, or trend analysis.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:metrics:use", "concepts": ["metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Use", "node_id": "concept:metrics", "node_type": "concept", "outbound_edges": ["note:evidence:evidence-over-vanity-metrics"], "path": "kb/concepts/metrics.md", "source_hash": "a645635646fea74b513f570e840159801e7f7d1e8c05ef428c952edfe3a5c079", "text": "Use this concept when distinguishing useful evidence from activity-only counts.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:mutation:definition", "concepts": ["mutation"], "created": "2026-06-07", "domain": "automation", "heading": "Definition", "node_id": "concept:mutation", "node_type": "concept", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/concepts/mutation.md", "source_hash": "e413905351925ca5b2a535ec0ebe882c9d8bc7a8118586e59403140e58c1fb29", "text": "Mutation is an operation that changes system, repository, workflow, or external state.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:mutation:use", "concepts": ["mutation"], "created": "2026-06-07", "domain": "automation", "heading": "Use", "node_id": "concept:mutation", "node_type": "concept", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand"], "path": "kb/concepts/mutation.md", "source_hash": "e413905351925ca5b2a535ec0ebe882c9d8bc7a8118586e59403140e58c1fb29", "text": "Use this concept when separating reads from writes and planning validation gates.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:observability:definition", "concepts": ["observability"], "created": "2026-06-07", "domain": "observability", "heading": "Definition", "node_id": "concept:observability", "node_type": "concept", "outbound_edges": ["map:observability:overview"], "path": "kb/concepts/observability.md", "source_hash": "8f5405fefec5d5614e4ecd7af09cd65a484a331eef2c02b33ab2d11ef9932dcb", "text": "Observability is the ability to understand system behavior from emitted evidence.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:observability:use", "concepts": ["observability"], "created": "2026-06-07", "domain": "observability", "heading": "Use", "node_id": "concept:observability", "node_type": "concept", "outbound_edges": ["map:observability:overview"], "path": "kb/concepts/observability.md", "source_hash": "8f5405fefec5d5614e4ecd7af09cd65a484a331eef2c02b33ab2d11ef9932dcb", "text": "Use this concept when discussing signals, health, diagnostics, reports, and operational review.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:operability:definition", "concepts": ["operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definition", "node_id": "concept:operability", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/operability.md", "source_hash": "996fecfaaf870c1416128ed6f7fa6286d4672a98a6b6bef52a86d25d5a1fb8bc", "text": "Operability is the ability to run, diagnose, recover, audit, and safely evolve a system.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:operability:use", "concepts": ["operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Use", "node_id": "concept:operability", "node_type": "concept", "outbound_edges": ["doctrine:repo:engineering-control-spine"], "path": "kb/concepts/operability.md", "source_hash": "996fecfaaf870c1416128ed6f7fa6286d4672a98a6b6bef52a86d25d5a1fb8bc", "text": "Use operability as a review lens for automation, observability, agent tools, and lifecycle tooling.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:provenance:definition", "concepts": ["provenance"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definition", "node_id": "concept:provenance", "node_type": "concept", "outbound_edges": ["note:operability:future-operators-need-context"], "path": "kb/concepts/provenance.md", "source_hash": "1aee746d8ec7bd253ee3c5a0aa714cbb285cb3549ed5615013d8e403f5a7f0f9", "text": "Provenance is information about where a claim, node, edge, artifact, or decision came from.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:provenance:use", "concepts": ["provenance"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Use", "node_id": "concept:provenance", "node_type": "concept", "outbound_edges": ["note:operability:future-operators-need-context"], "path": "kb/concepts/provenance.md", "source_hash": "1aee746d8ec7bd253ee3c5a0aa714cbb285cb3549ed5615013d8e403f5a7f0f9", "text": "Use this concept when reviewing generated artifacts, agent-authored notes, and evidence trails.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:validation:definition", "concepts": ["validation"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definition", "node_id": "concept:validation", "node_type": "concept", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "kb/concepts/validation.md", "source_hash": "e587799ad11cbe5c65c892bf9c957c7c6d4708a12d6091bf0e90e0336322df33", "text": "Validation is explicit checking that rejects invalid source, state, plans, edges, or generated artifacts.", "updated": "2026-06-07"} +{"chunk_id": "chunk:concept:validation:use", "concepts": ["validation"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Use", "node_id": "concept:validation", "node_type": "concept", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "kb/concepts/validation.md", "source_hash": "e587799ad11cbe5c65c892bf9c957c7c6d4708a12d6091bf0e90e0336322df33", "text": "Use this concept when defining lifecycle gates and agent-safe workflows.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:consequences", "concepts": ["second brain", "markdown", "maps of content", "related links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Consequences", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d048d9503d48828173764f0f71aafa6f3e6cda1fa328261ebb82207415620120", "text": "- New substantial doctrine pages should include knowledge hooks.\n- README and index pages should act as maps of content.\n- Wiki-link syntax and plugin-specific metadata should be avoided.\n- Cross-domain concepts should be linked rather than duplicated.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:context", "concepts": ["second brain", "markdown", "maps of content", "related links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Context", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d048d9503d48828173764f0f71aafa6f3e6cda1fa328261ebb82207415620120", "text": "`tea-style` is a doctrine/reference repository for humans and agents. It needs second-brain retrieval behavior without depending on non-GitHub tools or private note-system syntax.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:decision", "concepts": ["second brain", "markdown", "maps of content", "related links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Decision", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d048d9503d48828173764f0f71aafa6f3e6cda1fa328261ebb82207415620120", "text": "Use GitHub-native Markdown as the second-brain substrate.\n\nPages should use:\n- atomic concepts\n- map-of-content README/index pages\n- compact knowledge hooks\n- relative Markdown links\n- related pages sections\n- decision records for durable why", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:rationale", "concepts": ["second brain", "markdown", "maps of content", "related links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Rationale", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d048d9503d48828173764f0f71aafa6f3e6cda1fa328261ebb82207415620120", "text": "This keeps the repository readable in GitHub, easy to clone, easy for agents to parse, and independent of local note-taking applications.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:related-pages-decisions", "concepts": ["second brain", "markdown", "maps of content", "related links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages/decisions", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d048d9503d48828173764f0f71aafa6f3e6cda1fa328261ebb82207415620120", "text": "- [docs/second-brain-markdown-standard.md](../second-brain-markdown-standard.md)\n- [docs/page-template-standard.md](../page-template-standard.md)\n- [docs/doctrines/engineering-control-spine.md](../doctrines/engineering-control-spine.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0001-adopt-github-native-second-brain-doctrine:status", "concepts": ["second brain", "markdown", "maps of content", "related links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Status", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "outbound_edges": ["standard:repo:graph-knowledge-base-standard", "doctrine:repo:tea-style-doctrine"], "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d048d9503d48828173764f0f71aafa6f3e6cda1fa328261ebb82207415620120", "text": "accepted", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:consequences", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Consequences", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "0aec41614c3e4a8a54b43e615c03b072e5bb08d8a2a3c2acadda4e58915f8f22", "text": "- Authored graph nodes must use stable IDs.\n- Generated artifacts can be rebuilt from source.\n- Markdown links remain for human navigation.\n- Frontmatter edges carry semantic graph relationships.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:context", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Context", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "0aec41614c3e4a8a54b43e615c03b072e5bb08d8a2a3c2acadda4e58915f8f22", "text": "`tea-style` needs second-brain behavior that is inspectable in GitHub, useful to humans, and consumable by future autonomous systems.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:decision", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Decision", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "0aec41614c3e4a8a54b43e615c03b072e5bb08d8a2a3c2acadda4e58915f8f22", "text": "Use Markdown notes and YAML frontmatter as the canonical source of the doctrine graph.\n\nGenerated artifacts such as JSONL files, reports, chunks, and visualizations are derived from source Markdown. They are useful for review and consumption, but they are not canonical.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:rationale", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Rationale", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "0aec41614c3e4a8a54b43e615c03b072e5bb08d8a2a3c2acadda4e58915f8f22", "text": "Markdown keeps authorship visible. Frontmatter gives the graph enough structure to validate and export. This avoids pushing the repository into a database-first or product-runtime shape.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:related-pages-decisions", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages/decisions", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "0aec41614c3e4a8a54b43e615c03b072e5bb08d8a2a3c2acadda4e58915f8f22", "text": "- [docs/standards/graph-knowledge-base-standard.md](../standards/graph-knowledge-base-standard.md)\n- [docs/standards/generated-artifact-standard.md](../standards/generated-artifact-standard.md)\n- [docs/doctrines/tea-style-doctrine.md](../doctrines/tea-style-doctrine.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0002-adopt-markdown-native-doctrine-graph:status", "concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Status", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-knowledge-base-standard", "decision:repo:0001-adopt-github-native-second-brain-doctrine"], "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "0aec41614c3e4a8a54b43e615c03b072e5bb08d8a2a3c2acadda4e58915f8f22", "text": "accepted", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:consequences", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Consequences", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a77b9597e084651017b1b13d6c5b02ec42d984af3b315ef979c30e7a91809fef", "text": "- Python implementation code belongs under `src/tea_kb/`.\n- Tests belong under `tests/`.\n- Generated artifacts should be deterministic.\n- CI should run validation and stale-artifact checks.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:context", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Context", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a77b9597e084651017b1b13d6c5b02ec42d984af3b315ef979c30e7a91809fef", "text": "The repository is becoming a doctrine graph. Manual review alone will not reliably catch duplicate IDs, invalid edges, stale generated artifacts, broken links, orphan notes, or concept drift.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:decision", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Decision", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a77b9597e084651017b1b13d6c5b02ec42d984af3b315ef979c30e7a91809fef", "text": "Add a Python package named `tea_kb` and a CLI named `tea-kb`.\n\nThe tool may:\n- read Markdown\n- parse frontmatter\n- validate schema and graph consistency\n- extract sections and chunks\n- build graph artifacts\n- generate reports\n- generate diagnostic visualizations\n- support agent-safe iteration\n\nThe tool must not become a hosted service, production API, full RAG runtime, chat interface, or permanent background process.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:rationale", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Rationale", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a77b9597e084651017b1b13d6c5b02ec42d984af3b315ef979c30e7a91809fef", "text": "Bounded lifecycle tooling makes the knowledge base durable and inspectable while staying inside the repository's doctrine/reference scope.", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:related-pages-decisions", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages/decisions", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a77b9597e084651017b1b13d6c5b02ec42d984af3b315ef979c30e7a91809fef", "text": "- [docs/standards/python-type-discipline.md](../standards/python-type-discipline.md)\n- [docs/standards/generated-artifact-standard.md](../standards/generated-artifact-standard.md)\n- [docs/repo-scope.md](../repo-scope.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:decision:repo:0003-ship-tea-kb-lifecycle-tooling:status", "concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Status", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:generated-artifact-standard", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a77b9597e084651017b1b13d6c5b02ec42d984af3b315ef979c30e7a91809fef", "text": "accepted", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:anti-patterns", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "- hidden mutation inside read-sounding functions\n- global state that controls behavior implicitly\n- raw dictionaries flowing through core logic\n- giant procedural scripts that mix config, validation, transport, logging, and mutation\n- retries without idempotency or reconciliation\n- docs that describe safety without code enforcing it\n- LLM-generated plans that bypass deterministic validation", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:architecture-mechanics", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "Use these six control surfaces when evaluating design:\n\n1. **Boundaries**\n - Encapsulation, ports/adapters, dependency injection, protocols, anti-corruption layers.\n - Goal: callers depend on behavior, not implementation details.\n\n2. **State**\n - Typed domain models, invariants, immutable plans, state machines, checkpoints, resume rules.\n - Goal: valid states are explicit and invalid states are difficult to construct.\n\n3. **Contracts**\n - Command/query separation, result objects, error taxonomy, schema validation, versioning, backward compatibility.\n - Goal: readers know what a component promises and what can fail.\n\n4. **Change control**\n - Planning before execution, dry-run, validation gates, progressive delivery, blast-radius limits, feature flags, kill switches, human approval.\n - Goal: mutation is deliberate, reviewable, and bounded.\n\n5. **Feedback loops**\n - Idempotency, reconciliation, polling with deadlines, retries with discipline, circuit breakers, backpressure, rate limiting.\n - Goal: the system converges safely instead of assuming a command worked.\n\n6. **Operability**\n - Structured logs, metrics, traces, correlation IDs, evidence, reports, runbooks, data lineage, reproducibility.\n - Goal: operators can answer what ran, why it ran, what changed, what failed, and what evidence proves it.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:core-claim", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "Good systems are easy to reason about, easy to change, hard to misuse, and observable when they fail.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:definitions", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "- **Change control**: explicit handling of what can change, who approves it, how it is validated, and how it is recovered.\n- **Boundary**: a public interface where messy internals, external systems, or side effects are contained.\n- **State**: the modeled condition of a system, workflow, object, or external dependency.\n- **Contract**: a promise about inputs, outputs, side effects, errors, compatibility, or behavior.\n- **Feedback loop**: a sense-decide-act-verify cycle that compares desired state with actual state.\n- **Operability**: the ability to run, diagnose, recover, audit, and safely evolve a system.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:knowledge-hooks", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Knowledge hooks", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "- **Type**: cross-domain doctrine\n- **Domain**: repository-wide\n- **Concepts**: change control, boundaries, state, contracts, feedback loops, operability\n- **Use when**: designing, reviewing, or refactoring systems that must survive real change and failure", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:priority-patterns", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Priority patterns", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "- typed domain models\n- dependency injection and protocols\n- functional core with imperative shell\n- planning separate from execution\n- state machines for long workflows\n- validation gates before risky work\n- idempotent commands and reconciliation loops\n- explicit error/result/evidence models\n- ports and adapters for external systems\n- contract tests for external APIs\n- observability-driven development", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:purpose", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "Define the cross-domain engineering model behind TEA beyond any single pattern such as AOP.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:related-pages", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "- [typed-encapsulated-architecture-style.md](typed-encapsulated-architecture-style.md)\n- [docs/second-brain-markdown-standard.md](../second-brain-markdown-standard.md)\n- [domains/coding/architecture-boundaries.md](../../domains/coding/architecture-boundaries.md)\n- [domains/automation/safe-workflow-design.md](../../domains/automation/safe-workflow-design.md)\n- [domains/agent_arch/control/deterministic-tool-boundaries.md](../../domains/agent_arch/control/deterministic-tool-boundaries.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:engineering-control-spine:review-questions", "concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Review questions", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "doctrine:repo:systems-should-tell-on-themselves", "map:repo:engineering-doctrine"], "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "text": "Ask these before adding or changing a system:\n\n1. What domain concept is being modeled?\n2. What is the clean input and output?\n3. What state can this be in?\n4. What invariants must always hold?\n5. What can fail?\n6. Is this read-only or mutating?\n7. Is it idempotent?\n8. Can it dry-run?\n9. Can it validate before and after?\n10. What evidence proves it worked?\n11. Can the logic be tested without touching real systems?\n12. Can the external system be swapped later?\n13. Will a teammate or agent understand the boundary?", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:anti-patterns", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "text": "- hidden operational context\n- vanity metrics without decision value\n- scripts only the original author can explain\n- agents hallucinating operational state\n- prose-only reports that cannot be inspected mechanically", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:architecture-mechanics", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "text": "Use this doctrine when reviewing any system that can mutate, diagnose, report, or influence operational decisions.\n\nThe system should answer:\n- what happened\n- why it happened\n- what state it observed\n- what it changed\n- what evidence supports the outcome\n- what a future operator should do next", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:core-claim", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "text": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:definitions", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "text": "- **Tell on themselves**: expose enough state, context, and evidence that future operators do not need hidden author knowledge.\n- **Evidence**: structured proof that a claim, change, validation, or failure actually happened.\n- **Hidden context**: operational knowledge that exists only in a person's memory or an unstated workflow.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:patterns", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Patterns", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "text": "- expose state directly\n- capture evidence as data\n- keep mutation visible\n- make boundaries obvious\n- record provenance\n- write reports from structured results", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:purpose", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "text": "Define the root operating philosophy behind the doctrine graph.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:systems-should-tell-on-themselves:related-pages", "concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:engineering-control-spine", "doctrine:repo:tea-style-doctrine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "text": "- [engineering-control-spine.md](engineering-control-spine.md)\n- [docs/standards/graph-knowledge-base-standard.md](../standards/graph-knowledge-base-standard.md)\n- [kb/notes/evidence/systems-should-tell-on-themselves.md](../../kb/notes/evidence/systems-should-tell-on-themselves.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:anti-patterns", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "text": "- treating generated artifacts as canonical\n- turning the repository into a hosted product\n- adding cute tea-themed names to schema or code\n- letting agents create reviewed doctrine silently", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:architecture-mechanics", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "text": "The repository has three layers:\n\n```text\nauthored Markdown/frontmatter\n -> generated graph artifacts and reports\n -> future consumers such as agents, search, and review workflows\n```\n\nThe Python tool supports the knowledge base. It does not define doctrine by itself.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:core-claim", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "text": "`tea-style` is a Markdown-native engineering doctrine graph with embedded Python lifecycle tooling.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:definitions", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "text": "- **Markdown-native**: authored Markdown and frontmatter are the source of truth.\n- **Doctrine graph**: notes, concepts, decisions, standards, examples, and antipatterns connected by explicit semantic edges.\n- **Lifecycle tooling**: local Python code that validates, builds, reports, visualizes, and exports the graph.\n- **Context regression**: repeated rediscovery of knowledge that should have been captured as durable doctrine.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:patterns", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Patterns", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "text": "- Capture durable learning as small graph notes.\n- Use concepts to prevent vocabulary drift.\n- Use frontmatter edges for semantic graph relationships.\n- Use Markdown links for human navigation.\n- Commit deterministic generated artifacts when they improve review.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:purpose", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "text": "Define the repository's current identity as both doctrine graph and bounded lifecycle tool.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:tea-style-doctrine:related-pages", "concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "decision:repo:0002-adopt-markdown-native-doctrine-graph", "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "doctrine:repo:typed-encapsulated-architecture-style"], "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "text": "- [systems-should-tell-on-themselves.md](systems-should-tell-on-themselves.md)\n- [engineering-control-spine.md](engineering-control-spine.md)\n- [docs/standards/graph-knowledge-base-standard.md](../standards/graph-knowledge-base-standard.md)\n- [docs/standards/agent-kb-editing-standard.md](../standards/agent-kb-editing-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:architecture-mechanics", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Architecture / Mechanics", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "TEA is not a framework. It is a decision style.\n\nIt pushes work toward:\n- validated inputs\n- constrained side effects\n- explicit contracts\n- explicit state\n- observable execution\n- modular extension paths\n- predictable review\n\nThe standard structure is:\n\n```text\nuntrusted input\n -> validation and normalization\n -> typed domain objects\n -> pure planning or decision logic\n -> explicit side-effect boundary\n -> result, evidence, and feedback\n```", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:core-claim", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "Typed Encapsulated Architecture Style is a doctrine for building systems that are explicit, modular, reviewable, and durable.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:core-ideas", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core ideas", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "- Prefer strong typing where it clarifies behavior.\n- Keep modules black-boxed with narrow public interfaces.\n- Separate configuration from execution.\n- Prefer maintainable object-oriented structure where it improves consistency.\n- Use protocols, factories, and interface-driven design when they reduce drift across implementations.\n- Keep state and side effects explicit.\n- Model contracts, errors, and results as first-class design concerns.\n- Prefer feedback loops over one-way command assumptions.\n- Keep dependencies lean.\n- Prefer understandable code over clever code.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:definitions", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definitions", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "- **Typed**: important data, commands, config, results, and states have explicit structure.\n- **Encapsulated**: internals are hidden behind narrow interfaces that make misuse harder.\n- **Architecture**: dependencies, boundaries, state, and side effects are arranged deliberately.\n- **Style**: a preference system for decisions, not a framework or runtime.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:knowledge-hooks", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Knowledge hooks", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "- **Type**: cross-domain doctrine\n- **Domain**: repository-wide\n- **Concepts**: typing, encapsulation, architecture, contracts, operability\n- **Use when**: evaluating whether a design fits the repository's core engineering taste", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:purpose", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "Define the core TEA doctrine for designing systems that are explicit, modular, reviewable, and durable.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:related-pages", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "- [docs/doctrines/README.md](README.md)\n- [engineering-control-spine.md](engineering-control-spine.md)\n- [docs/second-brain-markdown-standard.md](../second-brain-markdown-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:standard-question", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Standard question", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "When evaluating a design, the basic question is:\n\nDoes this make the system easier to understand, safer to extend, and easier to review?\n\nIf not, the complexity likely does not belong.", "updated": "2026-06-07"} +{"chunk_id": "chunk:doctrine:repo:typed-encapsulated-architecture-style:what-tea-rejects", "concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "heading": "What TEA rejects", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "text": "- architecture by novelty\n- hidden global behavior\n- configuration embedded deep inside logic\n- abstractions without a real pressure behind them\n- dependency growth without clear value\n- state that readers must infer from call order\n- mutation that cannot be dry-run, audited, or explained", "updated": "2026-06-07"} +{"chunk_id": "chunk:example:agents:agent-tool-boundary:example", "concepts": ["agents", "boundary", "validation"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Example", "node_id": "example:agents:agent-tool-boundary", "node_type": "example", "outbound_edges": ["note:boundaries:tools-should-make-boundaries-obvious", "standard:repo:agent-kb-editing-standard"], "path": "kb/examples/agent-tool-boundary.md", "source_hash": "4583817ae677e5cffd7b27eae2ca92c469f05ef765993830f23803aa61bc6795", "text": "```text\nread_graph()\nvalidate_plan(plan)\nrender_dry_run(plan)\nexecute_approved_plan(plan)\n```", "updated": "2026-06-07"} +{"chunk_id": "chunk:example:agents:agent-tool-boundary:point", "concepts": ["agents", "boundary", "validation"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Point", "node_id": "example:agents:agent-tool-boundary", "node_type": "example", "outbound_edges": ["note:boundaries:tools-should-make-boundaries-obvious", "standard:repo:agent-kb-editing-standard"], "path": "kb/examples/agent-tool-boundary.md", "source_hash": "4583817ae677e5cffd7b27eae2ca92c469f05ef765993830f23803aa61bc6795", "text": "The agent proposes. Deterministic tools validate and execute within explicit boundaries.", "updated": "2026-06-07"} +{"chunk_id": "chunk:example:automation:safe-automation-script:example", "concepts": ["automation", "evidence", "mutation"], "created": "2026-06-07", "domain": "automation", "heading": "Example", "node_id": "example:automation:safe-automation-script", "node_type": "example", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "kb/examples/safe-automation-script.md", "source_hash": "d1b8dc96ae035b65d09fdcf7138a38f914179a6a98a2579022b9d5acc6a8dce1", "text": "```text\nload request\nvalidate context\nbuild plan\nrender dry-run\nexecute approved plan\ncollect evidence\nwrite report\n```", "updated": "2026-06-07"} +{"chunk_id": "chunk:example:automation:safe-automation-script:point", "concepts": ["automation", "evidence", "mutation"], "created": "2026-06-07", "domain": "automation", "heading": "Point", "node_id": "example:automation:safe-automation-script", "node_type": "example", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "kb/examples/safe-automation-script.md", "source_hash": "d1b8dc96ae035b65d09fdcf7138a38f914179a6a98a2579022b9d5acc6a8dce1", "text": "The script is safe because mutation is downstream from validation and planning.", "updated": "2026-06-07"} +{"chunk_id": "chunk:example:observability:splunk-health-state:example", "concepts": ["observability", "evidence", "explicit-state"], "created": "2026-06-07", "domain": "observability", "heading": "Example", "node_id": "example:observability:splunk-health-state", "node_type": "example", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/examples/splunk-health-state.md", "source_hash": "b4278288b5548c1d6aa6aa2f11544249e3a9bf6ac14cc1640bed2492d172c74a", "text": "```text\nprocess: splunkd running\napi: REST endpoint responds\ncluster: peer is searchable\nworkflow: host can safely receive work\n```", "updated": "2026-06-07"} +{"chunk_id": "chunk:example:observability:splunk-health-state:point", "concepts": ["observability", "evidence", "explicit-state"], "created": "2026-06-07", "domain": "observability", "heading": "Point", "node_id": "example:observability:splunk-health-state", "node_type": "example", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state"], "path": "kb/examples/splunk-health-state.md", "source_hash": "b4278288b5548c1d6aa6aa2f11544249e3a9bf6ac14cc1640bed2492d172c74a", "text": "Health is layered. A live process is not the same as a ready system.", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:agent-architecture:overview:core-pages", "concepts": ["agents", "tool boundaries", "validation", "provenance"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Core pages", "node_id": "map:agent-architecture:overview", "node_type": "map", "outbound_edges": ["standard:repo:agent-kb-editing-standard", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/agent-architecture.md", "source_hash": "738f14686e60cd9a0a4cc2045f3abf01fecf4c9a50249fd00265bce2cab9d63a", "text": "- [Agent Architecture Principles](../../domains/agent_arch/principles.md)\n- [Deterministic Tool Boundaries](../../domains/agent_arch/control/deterministic-tool-boundaries.md)\n- [Agent KB Editing Standard](../standards/agent-kb-editing-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:agent-architecture:overview:graph-notes", "concepts": ["agents", "tool boundaries", "validation", "provenance"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Graph notes", "node_id": "map:agent-architecture:overview", "node_type": "map", "outbound_edges": ["standard:repo:agent-kb-editing-standard", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/agent-architecture.md", "source_hash": "738f14686e60cd9a0a4cc2045f3abf01fecf4c9a50249fd00265bce2cab9d63a", "text": "- [Tools Should Make Boundaries Obvious](../../kb/notes/boundaries/tools-should-make-boundaries-obvious.md)\n- [Hidden Context Is Operational Risk](../../kb/notes/context/hidden-context-is-operational-risk.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:automation:overview:core-pages", "concepts": ["idempotency", "mutation", "evidence", "operability"], "created": "2026-06-07", "domain": "automation", "heading": "Core pages", "node_id": "map:automation:overview", "node_type": "map", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "docs/maps/automation.md", "source_hash": "aa445870ed5d0b17f9a14c91abdb8aa28cd4c83133508d6f31914bcff50902cf", "text": "- [Automation Principles](../../domains/automation/principles.md)\n- [Safe Workflow Design](../../domains/automation/safe-workflow-design.md)\n- [Engineering Control Spine](../doctrines/engineering-control-spine.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:automation:overview:graph-notes", "concepts": ["idempotency", "mutation", "evidence", "operability"], "created": "2026-06-07", "domain": "automation", "heading": "Graph notes", "node_id": "map:automation:overview", "node_type": "map", "outbound_edges": ["note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "note:evidence:systems-should-tell-on-themselves"], "path": "docs/maps/automation.md", "source_hash": "aa445870ed5d0b17f9a14c91abdb8aa28cd4c83133508d6f31914bcff50902cf", "text": "- [Systems Should Tell on Themselves](../../kb/notes/evidence/systems-should-tell-on-themselves.md)\n- [Mutation Should Be Atomic Visible and Hard to Misunderstand](../../kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md)\n- [Future Operators Need Context](../../kb/notes/operability/future-operators-need-context.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:coding:overview:core-pages", "concepts": ["boundaries", "typing", "contracts"], "created": "2026-06-07", "domain": "coding", "heading": "Core pages", "node_id": "map:coding:overview", "node_type": "map", "outbound_edges": ["standard:repo:python-type-discipline", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/coding.md", "source_hash": "9b8e30f5c8bad631008e310ee45fac2fff4682ce1c82967e1cd6b498a6e26ba0", "text": "- [Coding Principles](../../domains/coding/principles.md)\n- [Architecture Boundaries](../../domains/coding/architecture-boundaries.md)\n- [Python Type Discipline](../standards/python-type-discipline.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:coding:overview:graph-notes", "concepts": ["boundaries", "typing", "contracts"], "created": "2026-06-07", "domain": "coding", "heading": "Graph notes", "node_id": "map:coding:overview", "node_type": "map", "outbound_edges": ["standard:repo:python-type-discipline", "note:boundaries:tools-should-make-boundaries-obvious"], "path": "docs/maps/coding.md", "source_hash": "9b8e30f5c8bad631008e310ee45fac2fff4682ce1c82967e1cd6b498a6e26ba0", "text": "- [Tools Should Make Boundaries Obvious](../../kb/notes/boundaries/tools-should-make-boundaries-obvious.md)\n- [Mutation Should Be Atomic Visible and Hard to Misunderstand](../../kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:observability:overview:core-pages", "concepts": ["observability", "evidence", "system state"], "created": "2026-06-07", "domain": "observability", "heading": "Core pages", "node_id": "map:observability:overview", "node_type": "map", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state", "concept:evidence"], "path": "docs/maps/observability.md", "source_hash": "92e038c56f4ea63c6a6b4615c97b51be8a3aa1ac62fe7816e6f3757daa34dad8", "text": "- [Observability Principles](../../domains/observability/principles.md)\n- [Diagnostic Workflows](../../domains/observability/diagnostic-workflows.md)\n- [Platform Thinking](../../domains/observability/platform-thinking.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:observability:overview:graph-notes", "concepts": ["observability", "evidence", "system state"], "created": "2026-06-07", "domain": "observability", "heading": "Graph notes", "node_id": "map:observability:overview", "node_type": "map", "outbound_edges": ["note:observability:operators-should-not-hallucinate-system-state", "concept:evidence"], "path": "docs/maps/observability.md", "source_hash": "92e038c56f4ea63c6a6b4615c97b51be8a3aa1ac62fe7816e6f3757daa34dad8", "text": "- [Operators Should Not Hallucinate System State](../../kb/notes/observability/operators-should-not-hallucinate-system-state.md)\n- [Systems Should Tell on Themselves](../../kb/notes/evidence/systems-should-tell-on-themselves.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:repo:engineering-doctrine:core-path", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core path", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "83dd02914fdf1e26126e0245f3c2b53f9ecc3f4a81fb90471afaffe3110eb458", "text": "1. [TEA Style Doctrine](../doctrines/tea-style-doctrine.md)\n2. [Systems Should Tell on Themselves](../doctrines/systems-should-tell-on-themselves.md)\n3. [Typed Encapsulated Architecture Style](../doctrines/typed-encapsulated-architecture-style.md)\n4. [Engineering Control Spine](../doctrines/engineering-control-spine.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:repo:engineering-doctrine:domain-maps", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Domain maps", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "83dd02914fdf1e26126e0245f3c2b53f9ecc3f4a81fb90471afaffe3110eb458", "text": "- [Coding](coding.md)\n- [Automation](automation.md)\n- [Observability](observability.md)\n- [Agent Architecture](agent-architecture.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:repo:engineering-doctrine:purpose", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "83dd02914fdf1e26126e0245f3c2b53f9ecc3f4a81fb90471afaffe3110eb458", "text": "Provide a human navigation entry point for the repo-wide doctrine graph.", "updated": "2026-06-07"} +{"chunk_id": "chunk:map:repo:engineering-doctrine:standards-path", "concepts": ["doctrine graph", "engineering doctrine", "navigation"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Standards path", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "doctrine:repo:engineering-control-spine"], "path": "docs/maps/engineering-doctrine.md", "source_hash": "83dd02914fdf1e26126e0245f3c2b53f9ecc3f4a81fb90471afaffe3110eb458", "text": "1. [Graph Knowledge Base Standard](../standards/graph-knowledge-base-standard.md)\n2. [Graph Linking Standard](../standards/graph-linking-standard.md)\n3. [Generated Artifact Standard](../standards/generated-artifact-standard.md)\n4. [Agent KB Editing Standard](../standards/agent-kb-editing-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:core-claim", "concepts": ["boundary", "contract", "mutation", "validation"], "created": "2026-06-07", "domain": "coding", "heading": "Core claim", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "91450a08b1fac2371d00db076f6827563ff5fb067bffd4fe893f785f63454c29", "text": "A tool should make its boundaries obvious: what it reads, what it writes, what it validates, and what it refuses to do.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:failure-smell", "concepts": ["boundary", "contract", "mutation", "validation"], "created": "2026-06-07", "domain": "coding", "heading": "Failure smell", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "91450a08b1fac2371d00db076f6827563ff5fb067bffd4fe893f785f63454c29", "text": "A command sounds like a read but performs mutation, or a validator quietly fixes source files.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:related-doctrine", "concepts": ["boundary", "contract", "mutation", "validation"], "created": "2026-06-07", "domain": "coding", "heading": "Related doctrine", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "91450a08b1fac2371d00db076f6827563ff5fb067bffd4fe893f785f63454c29", "text": "- [Architecture Boundaries](../../../domains/coding/architecture-boundaries.md)\n- [Deterministic Tool Boundaries](../../../domains/agent_arch/control/deterministic-tool-boundaries.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:use-this-when", "concepts": ["boundary", "contract", "mutation", "validation"], "created": "2026-06-07", "domain": "coding", "heading": "Use this when", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "91450a08b1fac2371d00db076f6827563ff5fb067bffd4fe893f785f63454c29", "text": "Use this when designing CLIs, automation clients, validators, exporters, or agent tools.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:boundaries:tools-should-make-boundaries-obvious:why-it-matters", "concepts": ["boundary", "contract", "mutation", "validation"], "created": "2026-06-07", "domain": "coding", "heading": "Why it matters", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "outbound_edges": ["doctrine:repo:engineering-control-spine", "standard:repo:agent-kb-editing-standard", "map:coding:overview", "map:agent-architecture:overview"], "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "91450a08b1fac2371d00db076f6827563ff5fb067bffd4fe893f785f63454c29", "text": "Ambiguous boundaries force humans and agents to infer safety from naming or prose. That is not enough for risky systems.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:core-claim", "concepts": ["operability", "context-regression", "provenance"], "created": "2026-06-07", "domain": "operability", "heading": "Core claim", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "c0fa5a5fd6a82301a9e28494533a2d1d2b2f5b0f51d2f056e8556ef19bfddc8c", "text": "Hidden context is operational risk, even when the code appears simple.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:failure-smell", "concepts": ["operability", "context-regression", "provenance"], "created": "2026-06-07", "domain": "operability", "heading": "Failure smell", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "c0fa5a5fd6a82301a9e28494533a2d1d2b2f5b0f51d2f056e8556ef19bfddc8c", "text": "The workflow works only when someone remembers which machine, token, order, flag, or undocumented exception matters.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:related-doctrine", "concepts": ["operability", "context-regression", "provenance"], "created": "2026-06-07", "domain": "operability", "heading": "Related doctrine", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "c0fa5a5fd6a82301a9e28494533a2d1d2b2f5b0f51d2f056e8556ef19bfddc8c", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:use-this-when", "concepts": ["operability", "context-regression", "provenance"], "created": "2026-06-07", "domain": "operability", "heading": "Use this when", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "c0fa5a5fd6a82301a9e28494533a2d1d2b2f5b0f51d2f056e8556ef19bfddc8c", "text": "Use this when reviewing scripts, docs, runbooks, dashboards, or generated outputs that require unstated assumptions.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:context:hidden-context-is-operational-risk:why-it-matters", "concepts": ["operability", "context-regression", "provenance"], "created": "2026-06-07", "domain": "operability", "heading": "Why it matters", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hidden-operational-context"], "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "c0fa5a5fd6a82301a9e28494533a2d1d2b2f5b0f51d2f056e8556ef19bfddc8c", "text": "A workflow that only the original author can explain creates recovery risk, review risk, and agent-editing risk.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:core-claim", "concepts": ["evidence", "observability", "metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Core claim", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "cce30d96f7e60662829e1226e1b37c11bb20137dd0625b6223262b2a00dc0c12", "text": "Evidence beats vanity metrics.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:failure-smell", "concepts": ["evidence", "observability", "metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Failure smell", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "cce30d96f7e60662829e1226e1b37c11bb20137dd0625b6223262b2a00dc0c12", "text": "A report celebrates activity but cannot answer what changed, what failed, or what decision should be made.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:related-doctrine", "concepts": ["evidence", "observability", "metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Related doctrine", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "cce30d96f7e60662829e1226e1b37c11bb20137dd0625b6223262b2a00dc0c12", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)\n- [Observability Principles](../../../domains/observability/principles.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:use-this-when", "concepts": ["evidence", "observability", "metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Use this when", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "cce30d96f7e60662829e1226e1b37c11bb20137dd0625b6223262b2a00dc0c12", "text": "Use this when selecting metrics, evaluating automation, reviewing agent output, or deciding whether a report is useful.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:evidence-over-vanity-metrics:why-it-matters", "concepts": ["evidence", "observability", "metrics"], "created": "2026-06-07", "domain": "observability", "heading": "Why it matters", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "cce30d96f7e60662829e1226e1b37c11bb20137dd0625b6223262b2a00dc0c12", "text": "Counting PRs, tokens, reports, runs, or dashboards does not prove the system became safer, clearer, or easier to operate.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:core-claim", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "02f064d1370a0ed7113295c2590aa4cd6fd77bc0d3a74b81f26d2c74fd707f69", "text": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:failure-smell", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Failure smell", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "02f064d1370a0ed7113295c2590aa4cd6fd77bc0d3a74b81f26d2c74fd707f69", "text": "If future operators must ask the original author what happened, the system failed to tell on itself.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:related-doctrine", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related doctrine", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "02f064d1370a0ed7113295c2590aa4cd6fd77bc0d3a74b81f26d2c74fd707f69", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)\n- [Engineering Control Spine](../../../docs/doctrines/engineering-control-spine.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:use-this-when", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Use this when", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "02f064d1370a0ed7113295c2590aa4cd6fd77bc0d3a74b81f26d2c74fd707f69", "text": "Use this when reviewing scripts, automation, observability systems, compliance knowledge, or agent workflows that mutate or describe real systems.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:evidence:systems-should-tell-on-themselves:why-it-matters", "concepts": ["evidence", "operability", "explicit-state", "context-regression"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Why it matters", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "note:operability:future-operators-need-context", "doctrine:repo:engineering-control-spine", "antipattern:hidden-operational-context", "antipattern:vanity-metrics"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "02f064d1370a0ed7113295c2590aa4cd6fd77bc0d3a74b81f26d2c74fd707f69", "text": "Systems that only work because people carry hidden context are not simple. They are undocumented risk.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:core-claim", "concepts": ["mutation", "evidence", "change-control", "validation"], "created": "2026-06-07", "domain": "automation", "heading": "Core claim", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "fcc7c88d0ae91640c1373faffe771611ca334738bf063491def32f867233366f", "text": "If a mutation happens, it should be atomic, visible, and hard to misunderstand.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:failure-smell", "concepts": ["mutation", "evidence", "change-control", "validation"], "created": "2026-06-07", "domain": "automation", "heading": "Failure smell", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "fcc7c88d0ae91640c1373faffe771611ca334738bf063491def32f867233366f", "text": "A tool changes production state without a plan, dry-run, validation gate, change context, or structured result.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:related-doctrine", "concepts": ["mutation", "evidence", "change-control", "validation"], "created": "2026-06-07", "domain": "automation", "heading": "Related doctrine", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "fcc7c88d0ae91640c1373faffe771611ca334738bf063491def32f867233366f", "text": "- [Safe Workflow Design](../../../domains/automation/safe-workflow-design.md)\n- [Engineering Control Spine](../../../docs/doctrines/engineering-control-spine.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:use-this-when", "concepts": ["mutation", "evidence", "change-control", "validation"], "created": "2026-06-07", "domain": "automation", "heading": "Use this when", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "fcc7c88d0ae91640c1373faffe771611ca334738bf063491def32f867233366f", "text": "Use this when reviewing automation, generated plans, CLIs, remediation scripts, or agent tools that can change state.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand:why-it-matters", "concepts": ["mutation", "evidence", "change-control", "validation"], "created": "2026-06-07", "domain": "automation", "heading": "Why it matters", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "doctrine:repo:engineering-control-spine", "antipattern:undocumented-mutation"], "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "fcc7c88d0ae91640c1373faffe771611ca334738bf063491def32f867233366f", "text": "Invisible or ambiguous mutation is how automation creates incidents while appearing convenient.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:core-claim", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "created": "2026-06-07", "domain": "observability", "heading": "Core claim", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d5ddeb8f538135967e0d89eb4eebed044dbee2a71b1585e7fd5b3d6b81844bd9", "text": "Operators and agents should not hallucinate system state. They should inspect evidence.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:failure-smell", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "created": "2026-06-07", "domain": "observability", "heading": "Failure smell", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d5ddeb8f538135967e0d89eb4eebed044dbee2a71b1585e7fd5b3d6b81844bd9", "text": "A system declares health or failure without exposing the checks, timestamps, sources, or confidence behind the claim.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:related-doctrine", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "created": "2026-06-07", "domain": "observability", "heading": "Related doctrine", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d5ddeb8f538135967e0d89eb4eebed044dbee2a71b1585e7fd5b3d6b81844bd9", "text": "- [Observability Principles](../../../domains/observability/principles.md)\n- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:use-this-when", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "created": "2026-06-07", "domain": "observability", "heading": "Use this when", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d5ddeb8f538135967e0d89eb4eebed044dbee2a71b1585e7fd5b3d6b81844bd9", "text": "Use this when designing dashboards, health checks, agent workflows, triage reports, or status pages.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:observability:operators-should-not-hallucinate-system-state:why-it-matters", "concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "created": "2026-06-07", "domain": "observability", "heading": "Why it matters", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "outbound_edges": ["note:evidence:systems-should-tell-on-themselves", "antipattern:hallucinated-operational-state"], "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d5ddeb8f538135967e0d89eb4eebed044dbee2a71b1585e7fd5b3d6b81844bd9", "text": "Operational guesses can trigger wrong remediations, false confidence, and wasted incident time.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:operability:future-operators-need-context:core-claim", "concepts": ["operability", "provenance", "context-regression", "evidence"], "created": "2026-06-07", "domain": "operability", "heading": "Core claim", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "1a4f0988863882a838676d5c0999e891f00aa38179e70d1546d11a0ce91d246b", "text": "Future operators need context at the point of use, not in the original author's memory.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:operability:future-operators-need-context:failure-smell", "concepts": ["operability", "provenance", "context-regression", "evidence"], "created": "2026-06-07", "domain": "operability", "heading": "Failure smell", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "1a4f0988863882a838676d5c0999e891f00aa38179e70d1546d11a0ce91d246b", "text": "The output says a step failed, but does not say what was checked, what state was observed, or what action is safe next.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:operability:future-operators-need-context:related-doctrine", "concepts": ["operability", "provenance", "context-regression", "evidence"], "created": "2026-06-07", "domain": "operability", "heading": "Related doctrine", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "1a4f0988863882a838676d5c0999e891f00aa38179e70d1546d11a0ce91d246b", "text": "- [Systems Should Tell on Themselves](../../../docs/doctrines/systems-should-tell-on-themselves.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:operability:future-operators-need-context:use-this-when", "concepts": ["operability", "provenance", "context-regression", "evidence"], "created": "2026-06-07", "domain": "operability", "heading": "Use this when", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "1a4f0988863882a838676d5c0999e891f00aa38179e70d1546d11a0ce91d246b", "text": "Use this when writing reports, runbooks, generated artifacts, validation output, or workflow status records.", "updated": "2026-06-07"} +{"chunk_id": "chunk:note:operability:future-operators-need-context:why-it-matters", "concepts": ["operability", "provenance", "context-regression", "evidence"], "created": "2026-06-07", "domain": "operability", "heading": "Why it matters", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves", "concept:operability"], "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "1a4f0988863882a838676d5c0999e891f00aa38179e70d1546d11a0ce91d246b", "text": "The operational cost of a tool is paid during failure, handoff, and modification. Missing context compounds that cost.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:agent-pr-checklist", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Agent PR checklist", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "86d55999a54d4bcb965c10ce868a19b7c52932f1febdfe3a048e851b80e1b80c", "text": "- New notes are small and focused.\n- IDs are stable and meaningful.\n- Concepts reuse existing vocabulary.\n- Edges are justified.\n- `created` and `updated` dates are present and accurate enough for timeline generation.\n- Generated artifacts are updated.\n- Validation passes.\n- Reports were reviewed.\n- No unrelated restructuring was introduced.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:core-claim", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Core claim", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "86d55999a54d4bcb965c10ce868a19b7c52932f1febdfe3a048e851b80e1b80c", "text": "Agents may propose graph changes. They must not silently promote inferred doctrine to reviewed doctrine.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:frontmatter-policy", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Frontmatter policy", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "86d55999a54d4bcb965c10ce868a19b7c52932f1febdfe3a048e851b80e1b80c", "text": "Agent-created note:\n\n```yaml\norigin:\n author: agent\n review: proposed\n```\n\nHuman-reviewed agent note:\n\n```yaml\norigin:\n author: agent\n review: reviewed\n```\n\nManual note:\n\n```yaml\norigin:\n author: human\n review: manual\n```", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:purpose", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Purpose", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "86d55999a54d4bcb965c10ce868a19b7c52932f1febdfe3a048e851b80e1b80c", "text": "Define how autonomous or assisted editing should change the doctrine graph safely.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:related-pages", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Related pages", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "86d55999a54d4bcb965c10ce868a19b7c52932f1febdfe3a048e851b80e1b80c", "text": "- [graph-linking-standard.md](graph-linking-standard.md)\n- [domains/agent_arch/control/deterministic-tool-boundaries.md](../../domains/agent_arch/control/deterministic-tool-boundaries.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:agent-kb-editing-standard:rules-standards", "concepts": ["agent editing", "review", "provenance", "proposed edges"], "created": "2026-06-07", "domain": "agent-architecture", "heading": "Rules / standards", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "standard:repo:graph-linking-standard", "doctrine:repo:systems-should-tell-on-themselves"], "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "86d55999a54d4bcb965c10ce868a19b7c52932f1febdfe3a048e851b80e1b80c", "text": "- Prefer small notes over bloated pages.\n- Reuse existing concepts before inventing new ones.\n- Create concept notes when a concept becomes important.\n- Do not create edges just because words are similar.\n- Mark inferred edges as proposed unless the user explicitly reviewed them.\n- Do not silently redefine core doctrine.\n- Do not rename IDs casually.\n- Update the `updated` frontmatter date when durable meaning, graph metadata, or relationships change.\n- Run validation before finishing.\n- Update maps only when navigation materially improves.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:generated-artifact-standard:core-claim", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "c2e29f55490e67eebd26ecd07897b9b382fc1403aaa262f8ab235c326490915d", "text": "Generated artifacts are derived from Markdown/frontmatter. They are committed when they are stable and useful for review.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:generated-artifact-standard:generated-artifacts", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Generated artifacts", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "c2e29f55490e67eebd26ecd07897b9b382fc1403aaa262f8ab235c326490915d", "text": "- `graph/generated/nodes.jsonl`\n- `graph/generated/edges.jsonl`\n- `graph/generated/chunks.jsonl`\n- `graph/generated/concepts.jsonl`\n- `graph/generated/timeline.jsonl`\n- `graph/generated/reports/health.md`\n- `graph/generated/reports/orphan-notes.md`\n- `graph/generated/reports/dense-links.md`\n- `graph/generated/reports/duplicate-concepts.md`\n- `graph/generated/reports/proposed-edges.md`\n- `graph/generated/reports/timeline.md`\n- `graph/generated/visualizations/overview.html`\n- `graph/generated/visualizations/README.md`\n- `graph/generated/visualizations/repo-system.svg`\n- `graph/generated/visualizations/research-support.svg`\n- `graph/generated/visualizations/timeline-overview.svg`\n- `graph/generated/visualizations/concept-timeline-*.svg`", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:generated-artifact-standard:purpose", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "c2e29f55490e67eebd26ecd07897b9b382fc1403aaa262f8ab235c326490915d", "text": "Define which generated files exist and how they are reviewed.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:generated-artifact-standard:related-pages", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "c2e29f55490e67eebd26ecd07897b9b382fc1403aaa262f8ab235c326490915d", "text": "- [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md)\n- [visualization-standard.md](visualization-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:generated-artifact-standard:rules-standards", "concepts": ["generated artifacts", "determinism", "reports", "exports"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "outbound_edges": ["decision:repo:0003-ship-tea-kb-lifecycle-tooling", "standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/generated-artifact-standard.md", "source_hash": "c2e29f55490e67eebd26ecd07897b9b382fc1403aaa262f8ab235c326490915d", "text": "- Generated artifacts must be deterministic.\n- `tea-kb build --check` fails when generated artifacts are stale.\n- Generated files are not canonical.\n- Reports should be boring, useful, and reviewable.\n- JSONL exports should be stable-sorted by ID or edge tuple.\n- Visualization output should avoid avoidable randomness.\n- Root README diagrams must be generated artifacts, not hand-maintained images.\n- Timeline artifacts must be derived from `created` and `updated` frontmatter dates.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:core-claim", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "Markdown notes and frontmatter are the authored source of truth. Graph artifacts are generated from that source.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:definitions", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definitions", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "- **Note**: primary authored graph node.\n- **Chunk**: generated search unit derived from a node section.\n- **Concept**: controlled vocabulary entry.\n- **Frontmatter edge**: semantic relationship between graph nodes.\n- **Generated artifact**: derived JSONL, report, or visualization.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:edge-types", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Edge types", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "Use only:\n- `supports`\n- `refines`\n- `depends_on`\n- `contradicts`\n- `applies_to`\n- `exemplifies`\n- `supersedes`\n- `related_to`", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:id-rules", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "ID rules", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "IDs are lowercase, kebab-case, type-prefixed, and stable after creation.\n\nPreferred form:\n\n```text\n::\n```\n\nConcept and antipattern IDs may use:\n\n```text\nconcept:\nantipattern:\n```", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:node-types", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Node types", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "Use only:\n- `note`\n- `doctrine`\n- `concept`\n- `antipattern`\n- `decision`\n- `example`\n- `standard`\n- `map`", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:purpose", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "Define the canonical Markdown graph model for `tea-style`.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:related-pages", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "- [graph/schema.md](../../graph/schema.md)\n- [graph-linking-standard.md](graph-linking-standard.md)\n- [generated-artifact-standard.md](generated-artifact-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:required-frontmatter", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Required frontmatter", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "```yaml\nid: note:evidence:example\ntitle: Example\ntype: note\ndomain: repo-wide\nstatus: active\ncreated: 2026-06-07\nupdated: 2026-06-07\nconcepts:\n - evidence\n```", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:rules-standards", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "- Use industry terms in schema, code, exports, and validators.\n- Use tea-themed language only in prose, aliases, section flavor, and report titles.\n- Use readable IDs instead of UUIDs.\n- Keep authored notes smaller than broad doctrine pages.\n- Do not make every Markdown link a graph edge.\n- Do not make every Markdown section a graph node.\n- Do not treat generated artifacts as canonical.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-knowledge-base-standard:timeline-metadata", "concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Timeline metadata", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "outbound_edges": ["doctrine:repo:tea-style-doctrine", "decision:repo:0002-adopt-markdown-native-doctrine-graph"], "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "text": "Every authored graph node should carry:\n- `created`: the date the note, concept, decision, standard, map, example, or antipattern entered the graph.\n- `updated`: the latest meaningful doctrine or metadata update date.\n\nUse ISO `YYYY-MM-DD` dates. Generated timeline artifacts use these fields rather than Git history so timelines remain portable across forks, exports, and future search systems.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-linking-standard:anti-patterns", "concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "text": "- creating edges because two pages share a keyword\n- overusing `related_to`\n- using frontmatter edges for ordinary navigation\n- creating edges to missing or planned nodes", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-linking-standard:core-claim", "concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "text": "Markdown links are for human navigation. Frontmatter edges are for semantic graph relationships.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-linking-standard:definitions", "concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Definitions", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "text": "- **Semantic edge**: a typed relationship that changes how the graph should be interpreted.\n- **Loose relation**: a weak association that may not deserve an edge.\n- **Link explosion**: too many low-value edges on a node.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-linking-standard:edge-semantics", "concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Edge semantics", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "text": "- `supports`: source strengthens target.\n- `refines`: source makes target more specific.\n- `depends_on`: source requires target to make sense.\n- `contradicts`: source explicitly rejects target.\n- `applies_to`: source is relevant to target.\n- `exemplifies`: source demonstrates target.\n- `supersedes`: source replaces target.\n- `related_to`: source is loosely connected to target.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-linking-standard:purpose", "concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "text": "Control graph edge quality so the doctrine graph remains useful instead of becoming a link hairball.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-linking-standard:related-pages", "concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "text": "- [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md)\n- [agent-kb-editing-standard.md](agent-kb-editing-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:graph-linking-standard:rules-standards", "concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "outbound_edges": ["standard:repo:graph-knowledge-base-standard"], "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "text": "- Create an edge only when the relationship is meaningful and reviewable.\n- Prefer `supports`, `refines`, `depends_on`, `contradicts`, `applies_to`, `exemplifies`, or `supersedes` over `related_to`.\n- Use `related_to` sparingly.\n- `depends_on` and `supersedes` should be acyclic.\n- Do not infer edges from shared words alone.\n- Mark agent-inferred edges as proposed until reviewed.\n- Every edge target must resolve to an authored node.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:python-type-discipline:core-claim", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "created": "2026-06-07", "domain": "coding", "heading": "Core claim", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "3539b200ff521ed3db066e1acaa5798b35e54f65c84cc8a9a0dfdefee99231f8", "text": "Use the lowest type layer that solves the problem.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:python-type-discipline:definitions", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "created": "2026-06-07", "domain": "coding", "heading": "Definitions", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "3539b200ff521ed3db066e1acaa5798b35e54f65c84cc8a9a0dfdefee99231f8", "text": "- **Boundary model**: Pydantic model used to validate untrusted Markdown/frontmatter/config input.\n- **Domain model**: frozen dataclass used inside trusted core logic.\n- **Semantic ID**: `NewType` wrapper for IDs that should not be casually mixed.\n- **Protocol**: small behavior contract used at module boundaries.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:python-type-discipline:purpose", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "created": "2026-06-07", "domain": "coding", "heading": "Purpose", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "3539b200ff521ed3db066e1acaa5798b35e54f65c84cc8a9a0dfdefee99231f8", "text": "Define the type discipline for the `tea_kb` lifecycle tool.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:python-type-discipline:related-pages", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "created": "2026-06-07", "domain": "coding", "heading": "Related pages", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "3539b200ff521ed3db066e1acaa5798b35e54f65c84cc8a9a0dfdefee99231f8", "text": "- [domains/coding/architecture-boundaries.md](../../domains/coding/architecture-boundaries.md)\n- [docs/doctrines/typed-encapsulated-architecture-style.md](../doctrines/typed-encapsulated-architecture-style.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:python-type-discipline:rules-standards", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "created": "2026-06-07", "domain": "coding", "heading": "Rules / standards", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "3539b200ff521ed3db066e1acaa5798b35e54f65c84cc8a9a0dfdefee99231f8", "text": "- Use Pydantic at file/config boundaries.\n- Use frozen slots dataclasses for internal graph objects.\n- Use `NewType` for node, edge, chunk, and concept IDs.\n- Use `StrEnum` for node and edge categories.\n- Use `Protocol` for reader, exporter, and validator behavior.\n- Use `collections.abc` for function input typing.\n- Use `defaultdict`, `Counter`, and `deque` for graph support where appropriate.\n- Keep domain code independent of Typer, Rich, PyVis, and filesystem details.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:python-type-discipline:tool-mapping", "concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "created": "2026-06-07", "domain": "coding", "heading": "Tool mapping", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "outbound_edges": ["doctrine:repo:typed-encapsulated-architecture-style", "standard:repo:generated-artifact-standard"], "path": "docs/standards/python-type-discipline.md", "source_hash": "3539b200ff521ed3db066e1acaa5798b35e54f65c84cc8a9a0dfdefee99231f8", "text": "| Problem | Tool |\n|---|---|\n| Frontmatter validation | Pydantic |\n| Config validation | Pydantic |\n| Internal graph objects | frozen slots dataclasses |\n| Semantic IDs | `NewType` |\n| Node/edge categories | `StrEnum` |\n| Plugin-like behavior | `Protocol` |\n| Function input typing | `collections.abc` |\n| Concept frequency | `Counter` |\n| Graph traversal | `deque` |", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:visualization-standard:anti-patterns", "concepts": ["visualization", "diagnostics", "graph", "source links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Anti-patterns", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "16dd790ed00bcb20431770c466fc5d93a9fcc91da19e9c3a930541434a49a5d7", "text": "- huge all-node/all-edge views with no diagnostic purpose\n- decorative diagrams that do not affect review\n- visuals with no source path or provenance", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:visualization-standard:core-claim", "concepts": ["visualization", "diagnostics", "graph", "source links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Core claim", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "16dd790ed00bcb20431770c466fc5d93a9fcc91da19e9c3a930541434a49a5d7", "text": "Visualizations are diagnostic. They should answer a question.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:visualization-standard:good-visualizations", "concepts": ["visualization", "diagnostics", "graph", "source links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Good visualizations", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "16dd790ed00bcb20431770c466fc5d93a9fcc91da19e9c3a930541434a49a5d7", "text": "- concept neighborhood\n- domain cluster\n- doctrine path\n- contradiction map\n- orphan note map\n- dense-link warning map\n- proposed-edge review map\n- repository system map\n- research support map\n- knowledge base growth timeline\n- major concept timeline", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:visualization-standard:purpose", "concepts": ["visualization", "diagnostics", "graph", "source links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Purpose", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "16dd790ed00bcb20431770c466fc5d93a9fcc91da19e9c3a930541434a49a5d7", "text": "Define how graph visualizations should be generated and reviewed.", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:visualization-standard:related-pages", "concepts": ["visualization", "diagnostics", "graph", "source links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Related pages", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "16dd790ed00bcb20431770c466fc5d93a9fcc91da19e9c3a930541434a49a5d7", "text": "- [generated-artifact-standard.md](generated-artifact-standard.md)\n- [graph-knowledge-base-standard.md](graph-knowledge-base-standard.md)", "updated": "2026-06-07"} +{"chunk_id": "chunk:standard:repo:visualization-standard:rules-standards", "concepts": ["visualization", "diagnostics", "graph", "source links"], "created": "2026-06-07", "domain": "repo-wide", "heading": "Rules / standards", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "outbound_edges": ["standard:repo:generated-artifact-standard"], "path": "docs/standards/visualization-standard.md", "source_hash": "16dd790ed00bcb20431770c466fc5d93a9fcc91da19e9c3a930541434a49a5d7", "text": "- Do not default to a full graph hairball.\n- Prefer filtered views such as concept neighborhoods, domain clusters, paths, contradictions, or orphans.\n- Limit default depth to one or two hops.\n- Show node type, domain, and edge labels.\n- Link visual nodes back to source Markdown when practical.\n- Generated visualizations must be deterministic enough for review.\n- Root README visuals must be regenerated by `tea-kb build`, not edited as screenshots.\n- Timeline views should be split by major concept when a single feed would become noisy.\n- SVG is preferred for README-level diagrams because it is GitHub-native, diffable, and deterministic.", "updated": "2026-06-07"} diff --git a/graph/generated/concepts.jsonl b/graph/generated/concepts.jsonl index 3aa4124..4cdb8df 100644 --- a/graph/generated/concepts.jsonl +++ b/graph/generated/concepts.jsonl @@ -1,16 +1,16 @@ -{"aliases": [], "id": "concept:agents", "name": "Agents", "path": "kb/concepts/agents.md", "status": "active"} -{"aliases": [], "id": "concept:automation", "name": "Automation", "path": "kb/concepts/automation.md", "status": "active"} -{"aliases": [], "id": "concept:boundary", "name": "Boundary", "path": "kb/concepts/boundary.md", "status": "active"} -{"aliases": [], "id": "concept:change-control", "name": "Change Control", "path": "kb/concepts/change-control.md", "status": "active"} -{"aliases": [], "id": "concept:context-regression", "name": "Context Regression", "path": "kb/concepts/context-regression.md", "status": "active"} -{"aliases": [], "id": "concept:contract", "name": "Contract", "path": "kb/concepts/contract.md", "status": "active"} -{"aliases": [], "id": "concept:diagnostics", "name": "Diagnostics", "path": "kb/concepts/diagnostics.md", "status": "active"} -{"aliases": ["proof", "validation record", "audit artifact"], "id": "concept:evidence", "name": "Evidence", "path": "kb/concepts/evidence.md", "status": "active"} -{"aliases": [], "id": "concept:explicit-state", "name": "Explicit State", "path": "kb/concepts/explicit-state.md", "status": "active"} -{"aliases": [], "id": "concept:idempotency", "name": "Idempotency", "path": "kb/concepts/idempotency.md", "status": "active"} -{"aliases": [], "id": "concept:metrics", "name": "Metrics", "path": "kb/concepts/metrics.md", "status": "active"} -{"aliases": [], "id": "concept:mutation", "name": "Mutation", "path": "kb/concepts/mutation.md", "status": "active"} -{"aliases": [], "id": "concept:observability", "name": "Observability", "path": "kb/concepts/observability.md", "status": "active"} -{"aliases": ["operational usability"], "id": "concept:operability", "name": "Operability", "path": "kb/concepts/operability.md", "status": "active"} -{"aliases": [], "id": "concept:provenance", "name": "Provenance", "path": "kb/concepts/provenance.md", "status": "active"} -{"aliases": [], "id": "concept:validation", "name": "Validation", "path": "kb/concepts/validation.md", "status": "active"} +{"aliases": [], "created": "2026-06-07", "id": "concept:agents", "name": "Agents", "path": "kb/concepts/agents.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:automation", "name": "Automation", "path": "kb/concepts/automation.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:boundary", "name": "Boundary", "path": "kb/concepts/boundary.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:change-control", "name": "Change Control", "path": "kb/concepts/change-control.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:context-regression", "name": "Context Regression", "path": "kb/concepts/context-regression.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:contract", "name": "Contract", "path": "kb/concepts/contract.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:diagnostics", "name": "Diagnostics", "path": "kb/concepts/diagnostics.md", "status": "active", "updated": "2026-06-07"} +{"aliases": ["proof", "validation record", "audit artifact"], "created": "2026-06-07", "id": "concept:evidence", "name": "Evidence", "path": "kb/concepts/evidence.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:explicit-state", "name": "Explicit State", "path": "kb/concepts/explicit-state.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:idempotency", "name": "Idempotency", "path": "kb/concepts/idempotency.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:metrics", "name": "Metrics", "path": "kb/concepts/metrics.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:mutation", "name": "Mutation", "path": "kb/concepts/mutation.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:observability", "name": "Observability", "path": "kb/concepts/observability.md", "status": "active", "updated": "2026-06-07"} +{"aliases": ["operational usability"], "created": "2026-06-07", "id": "concept:operability", "name": "Operability", "path": "kb/concepts/operability.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:provenance", "name": "Provenance", "path": "kb/concepts/provenance.md", "status": "active", "updated": "2026-06-07"} +{"aliases": [], "created": "2026-06-07", "id": "concept:validation", "name": "Validation", "path": "kb/concepts/validation.md", "status": "active", "updated": "2026-06-07"} diff --git a/graph/generated/nodes.jsonl b/graph/generated/nodes.jsonl index b39b312..e0ce3a1 100644 --- a/graph/generated/nodes.jsonl +++ b/graph/generated/nodes.jsonl @@ -1,48 +1,48 @@ -{"concepts": ["observability", "explicit-state", "evidence"], "domain": "observability", "id": "antipattern:hallucinated-operational-state", "path": "kb/antipatterns/hallucinated-operational-state.md", "source_hash": "702601bba9b37466ee7ae735d0135d5e5890532080b072648dc6c50274343db2", "status": "active", "summary": "A human, agent, or tool claims system state without evidence from authoritative sources.\n", "title": "Hallucinated Operational State", "type": "antipattern"} -{"concepts": ["operability", "context-regression"], "domain": "operability", "id": "antipattern:hidden-operational-context", "path": "kb/antipatterns/hidden-operational-context.md", "source_hash": "82d6f17c68de7fc521764b75c80d66ea131b83b94dd6ecd345a483daee13e6cd", "status": "active", "summary": "A system relies on unstated human knowledge to operate or diagnose safely.\n", "title": "Hidden Operational Context", "type": "antipattern"} -{"concepts": ["mutation", "evidence"], "domain": "automation", "id": "antipattern:undocumented-mutation", "path": "kb/antipatterns/undocumented-mutation.md", "source_hash": "f89925da6dae183e1f92811e630198f4271990efe7c9284fb6e995cc0e271aa6", "status": "active", "summary": "A tool mutates state without clear plan, boundary, evidence, or recovery path.\n", "title": "Undocumented Mutation", "type": "antipattern"} -{"concepts": ["evidence", "metrics"], "domain": "observability", "id": "antipattern:vanity-metrics", "path": "kb/antipatterns/vanity-metrics.md", "source_hash": "4aab9cb9f73e4c25b62dc726c867412ac0a654a9fff399dd06d85dce3796d926", "status": "active", "summary": "Metrics that show activity without improving decisions, diagnosis, or safety.\n", "title": "Vanity Metrics", "type": "antipattern"} -{"concepts": ["agents"], "domain": "agent-architecture", "id": "concept:agents", "path": "kb/concepts/agents.md", "source_hash": "40d28e6001baaa51b9e17027e58ddcb3fd64dc55c41dc35342a1a62c8fece074", "status": "active", "summary": "Software actors that use model output, tools, context, and control boundaries to perform work.\n", "title": "Agents", "type": "concept"} -{"concepts": ["automation"], "domain": "automation", "id": "concept:automation", "path": "kb/concepts/automation.md", "source_hash": "f7f3dea1f6f5baab020b35f4b75243f32982ad77662fbd9d54a3c59cc4bbf790", "status": "active", "summary": "Software-controlled execution of repeatable operational or engineering work.\n", "title": "Automation", "type": "concept"} -{"concepts": ["boundary", "encapsulation"], "domain": "coding", "id": "concept:boundary", "path": "kb/concepts/boundary.md", "source_hash": "8c7a54893fc1bd77bb2a39a2b07917d51ddd2c7ac5ecf802d9d283e4cdd2f740", "status": "active", "summary": "A public interface where messy internals, external systems, or side effects are contained.\n", "title": "Boundary", "type": "concept"} -{"concepts": ["change-control"], "domain": "automation", "id": "concept:change-control", "path": "kb/concepts/change-control.md", "source_hash": "e5a89e0d37b63a05f0a01ad513744634c5fe7aa408e5bf654c7e0046a2d79a26", "status": "active", "summary": "Explicit handling of what can change, who approves it, how it is validated, and how it is recovered.\n", "title": "Change Control", "type": "concept"} -{"concepts": ["context-regression"], "domain": "repo-wide", "id": "concept:context-regression", "path": "kb/concepts/context-regression.md", "source_hash": "abcbc573894e45e17d6274402cf74fedca397b7ed8c80db3d8dfec800735a102", "status": "active", "summary": "Rediscovery of knowledge that should already exist as durable doctrine.\n", "title": "Context Regression", "type": "concept"} -{"concepts": ["contract"], "domain": "coding", "id": "concept:contract", "path": "kb/concepts/contract.md", "source_hash": "6768e9fe68126c169c42860dff73a41ffc5c9a02be67c0a9649913aa6ffd7697", "status": "active", "summary": "A promise about inputs, outputs, side effects, errors, compatibility, or behavior.\n", "title": "Contract", "type": "concept"} -{"concepts": ["diagnostics"], "domain": "observability", "id": "concept:diagnostics", "path": "kb/concepts/diagnostics.md", "source_hash": "273bb59c4c9c76ed10711598cb03136051a7710c1b2c240737398be02ee1fe8c", "status": "active", "summary": "Evidence and methods used to determine what is happening and why.\n", "title": "Diagnostics", "type": "concept"} -{"concepts": ["evidence"], "domain": "repo-wide", "id": "concept:evidence", "path": "kb/concepts/evidence.md", "source_hash": "a298e8046f12cb44b3519844da230acd192ee2da286a1b56bb8c17b678ce5afc", "status": "active", "summary": "Structured proof that supports an operational, architectural, or review claim.\n", "title": "Evidence", "type": "concept"} -{"concepts": ["explicit-state", "state"], "domain": "repo-wide", "id": "concept:explicit-state", "path": "kb/concepts/explicit-state.md", "source_hash": "6d7ba7def17198ef19094552a4d17ed827cbb3b395e6601a848fdc82a0ac778c", "status": "active", "summary": "State modeled clearly enough for humans and tools to inspect and reason about it.\n", "title": "Explicit State", "type": "concept"} -{"concepts": ["idempotency"], "domain": "automation", "id": "concept:idempotency", "path": "kb/concepts/idempotency.md", "source_hash": "fc2a80065e167e1f9d44e1105d1e6eb195e919674b9a0062c190dd2531c16c96", "status": "active", "summary": "Repeating an operation does not cause unintended additional effects.\n", "title": "Idempotency", "type": "concept"} -{"concepts": ["metrics"], "domain": "observability", "id": "concept:metrics", "path": "kb/concepts/metrics.md", "source_hash": "29aa83aaa364c799ff8d138785bead4a5c01e3d37c5069ab575ab393923daa3f", "status": "active", "summary": "Numeric measurements that should support diagnosis, decisions, or trend analysis.\n", "title": "Metrics", "type": "concept"} -{"concepts": ["mutation"], "domain": "automation", "id": "concept:mutation", "path": "kb/concepts/mutation.md", "source_hash": "0cf185f663aad760f22bf3641f5c0caaded00782bb7917bd17d35d3b32547af9", "status": "active", "summary": "An operation that changes system, repository, workflow, or external state.\n", "title": "Mutation", "type": "concept"} -{"concepts": ["observability"], "domain": "observability", "id": "concept:observability", "path": "kb/concepts/observability.md", "source_hash": "e5b7583118a968cf5870eaf2d754a9e7ffca579eb6605467b825b5a1a1942942", "status": "active", "summary": "The ability to understand system behavior from emitted evidence.\n", "title": "Observability", "type": "concept"} -{"concepts": ["operability"], "domain": "repo-wide", "id": "concept:operability", "path": "kb/concepts/operability.md", "source_hash": "d1a6cff035ffac1b1b2b871b513efb1de98da7284c491d70b30285624a39d627", "status": "active", "summary": "The ability to run, diagnose, recover, audit, and safely evolve a system.\n", "title": "Operability", "type": "concept"} -{"concepts": ["provenance"], "domain": "repo-wide", "id": "concept:provenance", "path": "kb/concepts/provenance.md", "source_hash": "eaf6b2b7877743cba9e712a20bdd37089c0f2e33c3d93f44897ff8bae31373d6", "status": "active", "summary": "Information about where a claim, node, edge, artifact, or decision came from.\n", "title": "Provenance", "type": "concept"} -{"concepts": ["validation"], "domain": "repo-wide", "id": "concept:validation", "path": "kb/concepts/validation.md", "source_hash": "8040c1fa6c29caf548c949909d6d95e30ac6032439f6e30b7fb944ad1235cb36", "status": "active", "summary": "Explicit checks that reject invalid source, state, plans, edges, or generated artifacts.\n", "title": "Validation", "type": "concept"} -{"concepts": ["second brain", "markdown", "maps of content", "related links"], "domain": "repo-wide", "id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d18ffabf1fb08913897ed3e8c6b6147b9817d2758659513bf72893638c6dac92", "status": "active", "summary": "Use GitHub-native Markdown as the second-brain substrate for tea-style.\n", "title": "Adopt GitHub-Native Second-Brain Doctrine", "type": "decision"} -{"concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "domain": "repo-wide", "id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "e43fc41db82612a521990ce608a024d5838da2797c751d7a90cbdd0f02a856c9", "status": "active", "summary": "Markdown notes and frontmatter are the source of truth; graph artifacts are generated from visible source files.\n", "title": "Adopt Markdown-Native Doctrine Graph", "type": "decision"} -{"concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "domain": "repo-wide", "id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a2d5b0dd7942b32ff6d408f2c7540d8155fdfd3be501b8e15a111a048fd4e8e0", "status": "active", "summary": "Include a bounded Python package and CLI for validating, building, reporting, visualizing, and exporting the Markdown doctrine graph.\n", "title": "Ship TEA KB Lifecycle Tooling", "type": "decision"} -{"concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "domain": "repo-wide", "id": "doctrine:repo:engineering-control-spine", "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "d80435f79f453ebb09e66ac3306c84a5aebf8885f97158b6962eb2f4a01cd704", "status": "active", "summary": "Good systems are easy to reason about, easy to change, hard to misuse, and observable when they fail.\n", "title": "Engineering Control Spine", "type": "doctrine"} -{"concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "domain": "repo-wide", "id": "doctrine:repo:systems-should-tell-on-themselves", "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "b7a5aa6e670bb4e734312889137df22edcb7789d5b8c1f4d57db47bd2319161e", "status": "active", "summary": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible.\n", "title": "Systems Should Tell on Themselves", "type": "doctrine"} -{"concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "domain": "repo-wide", "id": "doctrine:repo:tea-style-doctrine", "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "dfe763a4d937684175847ab573ff00d6dc8b1fa51ec13723124dfda53e49c237", "status": "active", "summary": "tea-style is a Markdown-native engineering doctrine graph with embedded Python lifecycle tooling.\n", "title": "TEA Style Doctrine", "type": "doctrine"} -{"concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "domain": "repo-wide", "id": "doctrine:repo:typed-encapsulated-architecture-style", "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "f573bcc4fa57a14acd54fbb896d7b083c1d7a956f2d961fb0065cda0b67d77a8", "status": "active", "summary": "TEA is a decision style for explicit, modular, typed, reviewable, and durable systems.\n", "title": "Typed Encapsulated Architecture Style", "type": "doctrine"} -{"concepts": ["agents", "boundary", "validation"], "domain": "agent-architecture", "id": "example:agents:agent-tool-boundary", "path": "kb/examples/agent-tool-boundary.md", "source_hash": "c87bfb36608e5970b3807017bf958ec3f17e82dc5cc22f4b199ef86048d9f673", "status": "active", "summary": "Agent tools should expose deterministic read, validation, dry-run, and mutation boundaries.\n", "title": "Agent Tool Boundary", "type": "example"} -{"concepts": ["automation", "evidence", "mutation"], "domain": "automation", "id": "example:automation:safe-automation-script", "path": "kb/examples/safe-automation-script.md", "source_hash": "e50bcbb2e856b5482ad02b01a6459965a80f14318c095c56290705c92a19d37b", "status": "active", "summary": "A safe automation script separates planning, validation, execution, and evidence.\n", "title": "Safe Automation Script", "type": "example"} -{"concepts": ["observability", "evidence", "explicit-state"], "domain": "observability", "id": "example:observability:splunk-health-state", "path": "kb/examples/splunk-health-state.md", "source_hash": "22778c51903c28a91c5f54c78c85f86246f596036bc3c8fe2f6677978b7a5040", "status": "active", "summary": "Health should be reported as layered evidence, not a single unsupported label.\n", "title": "Splunk Health State", "type": "example"} -{"concepts": ["agents", "tool boundaries", "validation", "provenance"], "domain": "agent-architecture", "id": "map:agent-architecture:overview", "path": "docs/maps/agent-architecture.md", "source_hash": "635c4a912e4ccca15d6ea2cda1f6075b11c8a383ad69f2a027c63eed0a8b25fa", "status": "active", "summary": "Navigation map for agent architecture doctrine and graph notes.\n", "title": "Agent Architecture Map", "type": "map"} -{"concepts": ["idempotency", "mutation", "evidence", "operability"], "domain": "automation", "id": "map:automation:overview", "path": "docs/maps/automation.md", "source_hash": "355f6e8e8028d5cd7918e5029a0c5fa5406f05be2ccac88d819b2859788e0bbf", "status": "active", "summary": "Navigation map for automation doctrine and graph notes.\n", "title": "Automation Map", "type": "map"} -{"concepts": ["boundaries", "typing", "contracts"], "domain": "coding", "id": "map:coding:overview", "path": "docs/maps/coding.md", "source_hash": "1fd777c4adfb4bb204c94d86935739f8c8af53919c4af0c86ba53ca3a9be1343", "status": "active", "summary": "Navigation map for coding doctrine and graph notes.\n", "title": "Coding Map", "type": "map"} -{"concepts": ["observability", "evidence", "system state"], "domain": "observability", "id": "map:observability:overview", "path": "docs/maps/observability.md", "source_hash": "4a9819a06f9ee2982d7dcd2609419c1c173ff456ae9450965f7f907599d09de7", "status": "active", "summary": "Navigation map for observability doctrine and graph notes.\n", "title": "Observability Map", "type": "map"} -{"concepts": ["doctrine graph", "engineering doctrine", "navigation"], "domain": "repo-wide", "id": "map:repo:engineering-doctrine", "path": "docs/maps/engineering-doctrine.md", "source_hash": "b1e5f8880d5b7d3ad5d65a9c4df280064bdcebd8f99a47bc0225fa884338439a", "status": "active", "summary": "Navigation map for the core TEA doctrine graph.\n", "title": "Engineering Doctrine Map", "type": "map"} -{"concepts": ["boundary", "contract", "mutation", "validation"], "domain": "coding", "id": "note:boundaries:tools-should-make-boundaries-obvious", "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "67e4542285231e248bd08882102d4f91ff7206acdac24d42d5f91518137bd1ec", "status": "active", "summary": "Tools should make read, write, validation, and execution boundaries visible.\n", "title": "Tools Should Make Boundaries Obvious", "type": "note"} -{"concepts": ["operability", "context-regression", "provenance"], "domain": "operability", "id": "note:context:hidden-context-is-operational-risk", "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "2eae072416ab707a0a784717ac9ef40e1714fc8c0de7d1fb76d478fa5a9f9f17", "status": "active", "summary": "Knowledge that exists only in the original author's memory makes systems fragile.\n", "title": "Hidden Context Is Operational Risk", "type": "note"} -{"concepts": ["evidence", "observability", "metrics"], "domain": "observability", "id": "note:evidence:evidence-over-vanity-metrics", "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "03464366d74704df3fe70b59b539c8879ebddfa7648ed3621361dde764e8801c", "status": "active", "summary": "Prefer evidence that changes decisions over metrics that only make activity visible.\n", "title": "Evidence Over Vanity Metrics", "type": "note"} -{"concepts": ["evidence", "operability", "explicit-state", "context-regression"], "domain": "repo-wide", "id": "note:evidence:systems-should-tell-on-themselves", "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "431dc9c90e89a3bbcd8007259dfc5d390143579b2e3d20aae8f4e6dc2d8110c2", "status": "active", "summary": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible.\n", "title": "Systems Should Tell on Themselves", "type": "note"} -{"concepts": ["mutation", "evidence", "change-control", "validation"], "domain": "automation", "id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "d73c7358c6f44cfd23cc50cadaf111d74654d6cc9c34288ce41b8fc2c7b97cc1", "status": "active", "summary": "Mutation should be deliberate, visible, bounded, and backed by evidence.\n", "title": "Mutation Should Be Atomic Visible and Hard to Misunderstand", "type": "note"} -{"concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "domain": "observability", "id": "note:observability:operators-should-not-hallucinate-system-state", "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d117bf010b09488ad271a2105ef3ad5f66492c44b2696232546a39faeaae39b9", "status": "active", "summary": "Operators and agents should inspect evidence instead of guessing current system state.\n", "title": "Operators Should Not Hallucinate System State", "type": "note"} -{"concepts": ["operability", "provenance", "context-regression", "evidence"], "domain": "operability", "id": "note:operability:future-operators-need-context", "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "0f45a679d6e41d377b94a1b9d3c380fb8cfa0cbd260688ee6828f791d7e81fcf", "status": "active", "summary": "Durable systems preserve enough context for future operators to diagnose and recover without rediscovery.\n", "title": "Future Operators Need Context", "type": "note"} -{"concepts": ["agent editing", "review", "provenance", "proposed edges"], "domain": "agent-architecture", "id": "standard:repo:agent-kb-editing-standard", "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "0fa9832f6491e93e1a071cb7a781202334f0a873baf803e93d92117d4326be65", "status": "active", "summary": "Defines how agents may add or change graph knowledge without silently redefining doctrine.\n", "title": "Agent KB Editing Standard", "type": "standard"} -{"concepts": ["generated artifacts", "determinism", "reports", "exports"], "domain": "repo-wide", "id": "standard:repo:generated-artifact-standard", "path": "docs/standards/generated-artifact-standard.md", "source_hash": "f6c03341ae01906532e8f3557cae5c7cce4d29f12c5c86d6b1f7bdfd57795192", "status": "active", "summary": "Defines generated graph artifacts, stale checks, determinism, and review expectations.\n", "title": "Generated Artifact Standard", "type": "standard"} -{"concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "domain": "repo-wide", "id": "standard:repo:graph-knowledge-base-standard", "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "fb3d93becd96891d6c3073057a7566d4822264452a216ae9f532096f90f07a5e", "status": "active", "summary": "Defines graph source units, node types, edge types, IDs, frontmatter, and generated artifacts.\n", "title": "Graph Knowledge Base Standard", "type": "standard"} -{"concepts": ["edges", "linking", "related links", "graph hygiene"], "domain": "repo-wide", "id": "standard:repo:graph-linking-standard", "path": "docs/standards/graph-linking-standard.md", "source_hash": "bc844d5f44fa50ec5222a67709eba7b58a2a791ff6f08263fad5bcc231af4e57", "status": "active", "summary": "Defines when to create semantic graph edges and when to rely on Markdown links.\n", "title": "Graph Linking Standard", "type": "standard"} -{"concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "domain": "coding", "id": "standard:repo:python-type-discipline", "path": "docs/standards/python-type-discipline.md", "source_hash": "dcb9705cd7bd226579c4c84c974307c0dffe1baaabe5df9c29de4a6595c58dff", "status": "active", "summary": "Defines how tea_kb uses Pydantic, dataclasses, NewType, StrEnum, Protocol, and standard collections.\n", "title": "Python Type Discipline", "type": "standard"} -{"concepts": ["visualization", "diagnostics", "graph", "source links"], "domain": "repo-wide", "id": "standard:repo:visualization-standard", "path": "docs/standards/visualization-standard.md", "source_hash": "f62e6f03edc7caea1e40ac89849b4de55adeb0ad2392efaef911bdfcb2fb2d59", "status": "active", "summary": "Defines graph visualizations as diagnostic artifacts, not decorative output.\n", "title": "Visualization Standard", "type": "standard"} +{"concepts": ["observability", "explicit-state", "evidence"], "created": "2026-06-07", "domain": "observability", "id": "antipattern:hallucinated-operational-state", "path": "kb/antipatterns/hallucinated-operational-state.md", "source_hash": "012874934322f6dd181146d8d9a1aa114fb287f78f488fa55bdce1dc5ec0e12e", "status": "active", "summary": "A human, agent, or tool claims system state without evidence from authoritative sources.\n", "title": "Hallucinated Operational State", "type": "antipattern", "updated": "2026-06-07"} +{"concepts": ["operability", "context-regression"], "created": "2026-06-07", "domain": "operability", "id": "antipattern:hidden-operational-context", "path": "kb/antipatterns/hidden-operational-context.md", "source_hash": "025ffd2524030434edbe42f0b38e65adad73df6afa43fd5747762324f7274972", "status": "active", "summary": "A system relies on unstated human knowledge to operate or diagnose safely.\n", "title": "Hidden Operational Context", "type": "antipattern", "updated": "2026-06-07"} +{"concepts": ["mutation", "evidence"], "created": "2026-06-07", "domain": "automation", "id": "antipattern:undocumented-mutation", "path": "kb/antipatterns/undocumented-mutation.md", "source_hash": "7705be70f5f6cd16e8d4c1d1834a2cef4fecf4f83825f39bb5ec5e1ebd5356bf", "status": "active", "summary": "A tool mutates state without clear plan, boundary, evidence, or recovery path.\n", "title": "Undocumented Mutation", "type": "antipattern", "updated": "2026-06-07"} +{"concepts": ["evidence", "metrics"], "created": "2026-06-07", "domain": "observability", "id": "antipattern:vanity-metrics", "path": "kb/antipatterns/vanity-metrics.md", "source_hash": "8e0f0d24d2a6ad4f57fa54d88f7a31cd3090ac84f9e10e9853243ff4b27722d3", "status": "active", "summary": "Metrics that show activity without improving decisions, diagnosis, or safety.\n", "title": "Vanity Metrics", "type": "antipattern", "updated": "2026-06-07"} +{"concepts": ["agents"], "created": "2026-06-07", "domain": "agent-architecture", "id": "concept:agents", "path": "kb/concepts/agents.md", "source_hash": "24ccfa334bd56a999170a2b88da59c6ac25bf9254d55e04e19ea06311c7a39b5", "status": "active", "summary": "Software actors that use model output, tools, context, and control boundaries to perform work.\n", "title": "Agents", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["automation"], "created": "2026-06-07", "domain": "automation", "id": "concept:automation", "path": "kb/concepts/automation.md", "source_hash": "e6b3c224f21044e9d590fea68f460de4bb081e7762eeba8636431912ba5e92f6", "status": "active", "summary": "Software-controlled execution of repeatable operational or engineering work.\n", "title": "Automation", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["boundary", "encapsulation"], "created": "2026-06-07", "domain": "coding", "id": "concept:boundary", "path": "kb/concepts/boundary.md", "source_hash": "a1192857b4b2b2739e768c0870306fcc2e44b45619e40dee2c4a79e9ee2b5210", "status": "active", "summary": "A public interface where messy internals, external systems, or side effects are contained.\n", "title": "Boundary", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["change-control"], "created": "2026-06-07", "domain": "automation", "id": "concept:change-control", "path": "kb/concepts/change-control.md", "source_hash": "90fbf59d42d8b22421336f3306e5bceec51770ecf91f85c250f0549dc1038856", "status": "active", "summary": "Explicit handling of what can change, who approves it, how it is validated, and how it is recovered.\n", "title": "Change Control", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["context-regression"], "created": "2026-06-07", "domain": "repo-wide", "id": "concept:context-regression", "path": "kb/concepts/context-regression.md", "source_hash": "935e7a95105c734fc883e4468bdfa4e79dfc1b70155dfe825aa1cc75c667deb4", "status": "active", "summary": "Rediscovery of knowledge that should already exist as durable doctrine.\n", "title": "Context Regression", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["contract"], "created": "2026-06-07", "domain": "coding", "id": "concept:contract", "path": "kb/concepts/contract.md", "source_hash": "351cc302acbafbe1a4a15734fb1dabe24980c5cdf43f52046ba31a4d58011a72", "status": "active", "summary": "A promise about inputs, outputs, side effects, errors, compatibility, or behavior.\n", "title": "Contract", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["diagnostics"], "created": "2026-06-07", "domain": "observability", "id": "concept:diagnostics", "path": "kb/concepts/diagnostics.md", "source_hash": "825cb8afeebd7b3d97cd57a6331f5878dde574a3c7f93a85e891a355b67f1d8c", "status": "active", "summary": "Evidence and methods used to determine what is happening and why.\n", "title": "Diagnostics", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["evidence"], "created": "2026-06-07", "domain": "repo-wide", "id": "concept:evidence", "path": "kb/concepts/evidence.md", "source_hash": "84178afd04bd0c967b09a08f5af7f00d4462635f028ed5dfb15891c8bce00016", "status": "active", "summary": "Structured proof that supports an operational, architectural, or review claim.\n", "title": "Evidence", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["explicit-state", "state"], "created": "2026-06-07", "domain": "repo-wide", "id": "concept:explicit-state", "path": "kb/concepts/explicit-state.md", "source_hash": "9db8575d1ef4e79bc01627a5e0d9bd7ad8dee93851e6ead43912130f252878d8", "status": "active", "summary": "State modeled clearly enough for humans and tools to inspect and reason about it.\n", "title": "Explicit State", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["idempotency"], "created": "2026-06-07", "domain": "automation", "id": "concept:idempotency", "path": "kb/concepts/idempotency.md", "source_hash": "e4637e2dae4d3a6bd1bc13b8bac6f898bd140f2829f2d3c71644f1ec4435a8ad", "status": "active", "summary": "Repeating an operation does not cause unintended additional effects.\n", "title": "Idempotency", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["metrics"], "created": "2026-06-07", "domain": "observability", "id": "concept:metrics", "path": "kb/concepts/metrics.md", "source_hash": "a645635646fea74b513f570e840159801e7f7d1e8c05ef428c952edfe3a5c079", "status": "active", "summary": "Numeric measurements that should support diagnosis, decisions, or trend analysis.\n", "title": "Metrics", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["mutation"], "created": "2026-06-07", "domain": "automation", "id": "concept:mutation", "path": "kb/concepts/mutation.md", "source_hash": "e413905351925ca5b2a535ec0ebe882c9d8bc7a8118586e59403140e58c1fb29", "status": "active", "summary": "An operation that changes system, repository, workflow, or external state.\n", "title": "Mutation", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["observability"], "created": "2026-06-07", "domain": "observability", "id": "concept:observability", "path": "kb/concepts/observability.md", "source_hash": "8f5405fefec5d5614e4ecd7af09cd65a484a331eef2c02b33ab2d11ef9932dcb", "status": "active", "summary": "The ability to understand system behavior from emitted evidence.\n", "title": "Observability", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["operability"], "created": "2026-06-07", "domain": "repo-wide", "id": "concept:operability", "path": "kb/concepts/operability.md", "source_hash": "996fecfaaf870c1416128ed6f7fa6286d4672a98a6b6bef52a86d25d5a1fb8bc", "status": "active", "summary": "The ability to run, diagnose, recover, audit, and safely evolve a system.\n", "title": "Operability", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["provenance"], "created": "2026-06-07", "domain": "repo-wide", "id": "concept:provenance", "path": "kb/concepts/provenance.md", "source_hash": "1aee746d8ec7bd253ee3c5a0aa714cbb285cb3549ed5615013d8e403f5a7f0f9", "status": "active", "summary": "Information about where a claim, node, edge, artifact, or decision came from.\n", "title": "Provenance", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["validation"], "created": "2026-06-07", "domain": "repo-wide", "id": "concept:validation", "path": "kb/concepts/validation.md", "source_hash": "e587799ad11cbe5c65c892bf9c957c7c6d4708a12d6091bf0e90e0336322df33", "status": "active", "summary": "Explicit checks that reject invalid source, state, plans, edges, or generated artifacts.\n", "title": "Validation", "type": "concept", "updated": "2026-06-07"} +{"concepts": ["second brain", "markdown", "maps of content", "related links"], "created": "2026-06-07", "domain": "repo-wide", "id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "source_hash": "d048d9503d48828173764f0f71aafa6f3e6cda1fa328261ebb82207415620120", "status": "active", "summary": "Use GitHub-native Markdown as the second-brain substrate for tea-style.\n", "title": "Adopt GitHub-Native Second-Brain Doctrine", "type": "decision", "updated": "2026-06-07"} +{"concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "source_hash": "0aec41614c3e4a8a54b43e615c03b072e5bb08d8a2a3c2acadda4e58915f8f22", "status": "active", "summary": "Markdown notes and frontmatter are the source of truth; graph artifacts are generated from visible source files.\n", "title": "Adopt Markdown-Native Doctrine Graph", "type": "decision", "updated": "2026-06-07"} +{"concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "created": "2026-06-07", "domain": "repo-wide", "id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "source_hash": "a77b9597e084651017b1b13d6c5b02ec42d984af3b315ef979c30e7a91809fef", "status": "active", "summary": "Include a bounded Python package and CLI for validating, building, reporting, visualizing, and exporting the Markdown doctrine graph.\n", "title": "Ship TEA KB Lifecycle Tooling", "type": "decision", "updated": "2026-06-07"} +{"concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "created": "2026-06-07", "domain": "repo-wide", "id": "doctrine:repo:engineering-control-spine", "path": "docs/doctrines/engineering-control-spine.md", "source_hash": "9c746ba392aa02a80999fa0d863368470118e69bd69362a7ed1827c1c9251d9e", "status": "active", "summary": "Good systems are easy to reason about, easy to change, hard to misuse, and observable when they fail.\n", "title": "Engineering Control Spine", "type": "doctrine", "updated": "2026-06-07"} +{"concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "id": "doctrine:repo:systems-should-tell-on-themselves", "path": "docs/doctrines/systems-should-tell-on-themselves.md", "source_hash": "f65fd72cabea0b1427bb6e6cea731b8db1bf72c5285950a708e71f9c17c20135", "status": "active", "summary": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible.\n", "title": "Systems Should Tell on Themselves", "type": "doctrine", "updated": "2026-06-07"} +{"concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "created": "2026-06-07", "domain": "repo-wide", "id": "doctrine:repo:tea-style-doctrine", "path": "docs/doctrines/tea-style-doctrine.md", "source_hash": "daca776cb688af9609470fc8baf4c803d356fba42253d19231f53cc78e3a70d4", "status": "active", "summary": "tea-style is a Markdown-native engineering doctrine graph with embedded Python lifecycle tooling.\n", "title": "TEA Style Doctrine", "type": "doctrine", "updated": "2026-06-07"} +{"concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "created": "2026-06-07", "domain": "repo-wide", "id": "doctrine:repo:typed-encapsulated-architecture-style", "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "source_hash": "b145d89cd2f73f58be1550b1f3e669f311925b87c4056204a34b5a66f8f3fd83", "status": "active", "summary": "TEA is a decision style for explicit, modular, typed, reviewable, and durable systems.\n", "title": "Typed Encapsulated Architecture Style", "type": "doctrine", "updated": "2026-06-07"} +{"concepts": ["agents", "boundary", "validation"], "created": "2026-06-07", "domain": "agent-architecture", "id": "example:agents:agent-tool-boundary", "path": "kb/examples/agent-tool-boundary.md", "source_hash": "4583817ae677e5cffd7b27eae2ca92c469f05ef765993830f23803aa61bc6795", "status": "active", "summary": "Agent tools should expose deterministic read, validation, dry-run, and mutation boundaries.\n", "title": "Agent Tool Boundary", "type": "example", "updated": "2026-06-07"} +{"concepts": ["automation", "evidence", "mutation"], "created": "2026-06-07", "domain": "automation", "id": "example:automation:safe-automation-script", "path": "kb/examples/safe-automation-script.md", "source_hash": "d1b8dc96ae035b65d09fdcf7138a38f914179a6a98a2579022b9d5acc6a8dce1", "status": "active", "summary": "A safe automation script separates planning, validation, execution, and evidence.\n", "title": "Safe Automation Script", "type": "example", "updated": "2026-06-07"} +{"concepts": ["observability", "evidence", "explicit-state"], "created": "2026-06-07", "domain": "observability", "id": "example:observability:splunk-health-state", "path": "kb/examples/splunk-health-state.md", "source_hash": "b4278288b5548c1d6aa6aa2f11544249e3a9bf6ac14cc1640bed2492d172c74a", "status": "active", "summary": "Health should be reported as layered evidence, not a single unsupported label.\n", "title": "Splunk Health State", "type": "example", "updated": "2026-06-07"} +{"concepts": ["agents", "tool boundaries", "validation", "provenance"], "created": "2026-06-07", "domain": "agent-architecture", "id": "map:agent-architecture:overview", "path": "docs/maps/agent-architecture.md", "source_hash": "738f14686e60cd9a0a4cc2045f3abf01fecf4c9a50249fd00265bce2cab9d63a", "status": "active", "summary": "Navigation map for agent architecture doctrine and graph notes.\n", "title": "Agent Architecture Map", "type": "map", "updated": "2026-06-07"} +{"concepts": ["idempotency", "mutation", "evidence", "operability"], "created": "2026-06-07", "domain": "automation", "id": "map:automation:overview", "path": "docs/maps/automation.md", "source_hash": "aa445870ed5d0b17f9a14c91abdb8aa28cd4c83133508d6f31914bcff50902cf", "status": "active", "summary": "Navigation map for automation doctrine and graph notes.\n", "title": "Automation Map", "type": "map", "updated": "2026-06-07"} +{"concepts": ["boundaries", "typing", "contracts"], "created": "2026-06-07", "domain": "coding", "id": "map:coding:overview", "path": "docs/maps/coding.md", "source_hash": "9b8e30f5c8bad631008e310ee45fac2fff4682ce1c82967e1cd6b498a6e26ba0", "status": "active", "summary": "Navigation map for coding doctrine and graph notes.\n", "title": "Coding Map", "type": "map", "updated": "2026-06-07"} +{"concepts": ["observability", "evidence", "system state"], "created": "2026-06-07", "domain": "observability", "id": "map:observability:overview", "path": "docs/maps/observability.md", "source_hash": "92e038c56f4ea63c6a6b4615c97b51be8a3aa1ac62fe7816e6f3757daa34dad8", "status": "active", "summary": "Navigation map for observability doctrine and graph notes.\n", "title": "Observability Map", "type": "map", "updated": "2026-06-07"} +{"concepts": ["doctrine graph", "engineering doctrine", "navigation"], "created": "2026-06-07", "domain": "repo-wide", "id": "map:repo:engineering-doctrine", "path": "docs/maps/engineering-doctrine.md", "source_hash": "83dd02914fdf1e26126e0245f3c2b53f9ecc3f4a81fb90471afaffe3110eb458", "status": "active", "summary": "Navigation map for the core TEA doctrine graph.\n", "title": "Engineering Doctrine Map", "type": "map", "updated": "2026-06-07"} +{"concepts": ["boundary", "contract", "mutation", "validation"], "created": "2026-06-07", "domain": "coding", "id": "note:boundaries:tools-should-make-boundaries-obvious", "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "source_hash": "91450a08b1fac2371d00db076f6827563ff5fb067bffd4fe893f785f63454c29", "status": "active", "summary": "Tools should make read, write, validation, and execution boundaries visible.\n", "title": "Tools Should Make Boundaries Obvious", "type": "note", "updated": "2026-06-07"} +{"concepts": ["operability", "context-regression", "provenance"], "created": "2026-06-07", "domain": "operability", "id": "note:context:hidden-context-is-operational-risk", "path": "kb/notes/context/hidden-context-is-operational-risk.md", "source_hash": "c0fa5a5fd6a82301a9e28494533a2d1d2b2f5b0f51d2f056e8556ef19bfddc8c", "status": "active", "summary": "Knowledge that exists only in the original author's memory makes systems fragile.\n", "title": "Hidden Context Is Operational Risk", "type": "note", "updated": "2026-06-07"} +{"concepts": ["evidence", "observability", "metrics"], "created": "2026-06-07", "domain": "observability", "id": "note:evidence:evidence-over-vanity-metrics", "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "source_hash": "cce30d96f7e60662829e1226e1b37c11bb20137dd0625b6223262b2a00dc0c12", "status": "active", "summary": "Prefer evidence that changes decisions over metrics that only make activity visible.\n", "title": "Evidence Over Vanity Metrics", "type": "note", "updated": "2026-06-07"} +{"concepts": ["evidence", "operability", "explicit-state", "context-regression"], "created": "2026-06-07", "domain": "repo-wide", "id": "note:evidence:systems-should-tell-on-themselves", "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "02f064d1370a0ed7113295c2590aa4cd6fd77bc0d3a74b81f26d2c74fd707f69", "status": "active", "summary": "Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible.\n", "title": "Systems Should Tell on Themselves", "type": "note", "updated": "2026-06-07"} +{"concepts": ["mutation", "evidence", "change-control", "validation"], "created": "2026-06-07", "domain": "automation", "id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "source_hash": "fcc7c88d0ae91640c1373faffe771611ca334738bf063491def32f867233366f", "status": "active", "summary": "Mutation should be deliberate, visible, bounded, and backed by evidence.\n", "title": "Mutation Should Be Atomic Visible and Hard to Misunderstand", "type": "note", "updated": "2026-06-07"} +{"concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "created": "2026-06-07", "domain": "observability", "id": "note:observability:operators-should-not-hallucinate-system-state", "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "source_hash": "d5ddeb8f538135967e0d89eb4eebed044dbee2a71b1585e7fd5b3d6b81844bd9", "status": "active", "summary": "Operators and agents should inspect evidence instead of guessing current system state.\n", "title": "Operators Should Not Hallucinate System State", "type": "note", "updated": "2026-06-07"} +{"concepts": ["operability", "provenance", "context-regression", "evidence"], "created": "2026-06-07", "domain": "operability", "id": "note:operability:future-operators-need-context", "path": "kb/notes/operability/future-operators-need-context.md", "source_hash": "1a4f0988863882a838676d5c0999e891f00aa38179e70d1546d11a0ce91d246b", "status": "active", "summary": "Durable systems preserve enough context for future operators to diagnose and recover without rediscovery.\n", "title": "Future Operators Need Context", "type": "note", "updated": "2026-06-07"} +{"concepts": ["agent editing", "review", "provenance", "proposed edges"], "created": "2026-06-07", "domain": "agent-architecture", "id": "standard:repo:agent-kb-editing-standard", "path": "docs/standards/agent-kb-editing-standard.md", "source_hash": "86d55999a54d4bcb965c10ce868a19b7c52932f1febdfe3a048e851b80e1b80c", "status": "active", "summary": "Defines how agents may add or change graph knowledge without silently redefining doctrine.\n", "title": "Agent KB Editing Standard", "type": "standard", "updated": "2026-06-07"} +{"concepts": ["generated artifacts", "determinism", "reports", "exports"], "created": "2026-06-07", "domain": "repo-wide", "id": "standard:repo:generated-artifact-standard", "path": "docs/standards/generated-artifact-standard.md", "source_hash": "c2e29f55490e67eebd26ecd07897b9b382fc1403aaa262f8ab235c326490915d", "status": "active", "summary": "Defines generated graph artifacts, stale checks, determinism, and review expectations.\n", "title": "Generated Artifact Standard", "type": "standard", "updated": "2026-06-07"} +{"concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "created": "2026-06-07", "domain": "repo-wide", "id": "standard:repo:graph-knowledge-base-standard", "path": "docs/standards/graph-knowledge-base-standard.md", "source_hash": "b8fcce84f9989def3cc3568fc6c4fb6d0edcf4b14f246eab93ad377082f0a5dc", "status": "active", "summary": "Defines graph source units, node types, edge types, IDs, frontmatter, and generated artifacts.\n", "title": "Graph Knowledge Base Standard", "type": "standard", "updated": "2026-06-07"} +{"concepts": ["edges", "linking", "related links", "graph hygiene"], "created": "2026-06-07", "domain": "repo-wide", "id": "standard:repo:graph-linking-standard", "path": "docs/standards/graph-linking-standard.md", "source_hash": "8cf58408f07558e1d0441cbdc2d260f5a23a88db1c018ac791790479bed9567b", "status": "active", "summary": "Defines when to create semantic graph edges and when to rely on Markdown links.\n", "title": "Graph Linking Standard", "type": "standard", "updated": "2026-06-07"} +{"concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "created": "2026-06-07", "domain": "coding", "id": "standard:repo:python-type-discipline", "path": "docs/standards/python-type-discipline.md", "source_hash": "3539b200ff521ed3db066e1acaa5798b35e54f65c84cc8a9a0dfdefee99231f8", "status": "active", "summary": "Defines how tea_kb uses Pydantic, dataclasses, NewType, StrEnum, Protocol, and standard collections.\n", "title": "Python Type Discipline", "type": "standard", "updated": "2026-06-07"} +{"concepts": ["visualization", "diagnostics", "graph", "source links"], "created": "2026-06-07", "domain": "repo-wide", "id": "standard:repo:visualization-standard", "path": "docs/standards/visualization-standard.md", "source_hash": "16dd790ed00bcb20431770c466fc5d93a9fcc91da19e9c3a930541434a49a5d7", "status": "active", "summary": "Defines graph visualizations as diagnostic artifacts, not decorative output.\n", "title": "Visualization Standard", "type": "standard", "updated": "2026-06-07"} diff --git a/graph/generated/reports/health.md b/graph/generated/reports/health.md index b671239..91f492d 100644 --- a/graph/generated/reports/health.md +++ b/graph/generated/reports/health.md @@ -4,7 +4,7 @@ - Nodes: 48 - Edges: 87 -- Chunks: 183 +- Chunks: 184 - Notes: 7 - Concepts: 16 - Antipatterns: 4 diff --git a/graph/generated/reports/timeline.md b/graph/generated/reports/timeline.md new file mode 100644 index 0000000..5de8bdf --- /dev/null +++ b/graph/generated/reports/timeline.md @@ -0,0 +1,104 @@ +# Knowledge Timeline + +## Summary + +- Timeline events: 48 +- Created events: 48 +- Updated events: 0 +- Dated nodes: 48 + +## Overall Growth + +| Date | Events | Nodes | +|---|---:|---| +| 2026-06-07 | 48 | `antipattern:hallucinated-operational-state`, `antipattern:hidden-operational-context`, `antipattern:undocumented-mutation`, `antipattern:vanity-metrics`, `concept:agents`, `concept:automation`, `concept:boundary`, `concept:change-control` ... | + +## Major Concept Timelines + +### evidence + +14 node(s) carry this concept. + +| Date | Event | Node | Type | Path | +|---|---|---|---|---| +| 2026-06-07 | created | `antipattern:hallucinated-operational-state` | antipattern | kb/antipatterns/hallucinated-operational-state.md | +| 2026-06-07 | created | `antipattern:undocumented-mutation` | antipattern | kb/antipatterns/undocumented-mutation.md | +| 2026-06-07 | created | `antipattern:vanity-metrics` | antipattern | kb/antipatterns/vanity-metrics.md | +| 2026-06-07 | created | `concept:evidence` | concept | kb/concepts/evidence.md | +| 2026-06-07 | created | `doctrine:repo:systems-should-tell-on-themselves` | doctrine | docs/doctrines/systems-should-tell-on-themselves.md | +| 2026-06-07 | created | `example:automation:safe-automation-script` | example | kb/examples/safe-automation-script.md | +| 2026-06-07 | created | `example:observability:splunk-health-state` | example | kb/examples/splunk-health-state.md | +| 2026-06-07 | created | `map:automation:overview` | map | docs/maps/automation.md | +| 2026-06-07 | created | `map:observability:overview` | map | docs/maps/observability.md | +| 2026-06-07 | created | `note:evidence:evidence-over-vanity-metrics` | note | kb/notes/evidence/evidence-over-vanity-metrics.md | +| 2026-06-07 | created | `note:evidence:systems-should-tell-on-themselves` | note | kb/notes/evidence/systems-should-tell-on-themselves.md | +| 2026-06-07 | created | `note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand` | note | kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md | +| 2026-06-07 | created | `note:observability:operators-should-not-hallucinate-system-state` | note | kb/notes/observability/operators-should-not-hallucinate-system-state.md | +| 2026-06-07 | created | `note:operability:future-operators-need-context` | note | kb/notes/operability/future-operators-need-context.md | + +### operability + +9 node(s) carry this concept. + +| Date | Event | Node | Type | Path | +|---|---|---|---|---| +| 2026-06-07 | created | `antipattern:hidden-operational-context` | antipattern | kb/antipatterns/hidden-operational-context.md | +| 2026-06-07 | created | `concept:operability` | concept | kb/concepts/operability.md | +| 2026-06-07 | created | `doctrine:repo:engineering-control-spine` | doctrine | docs/doctrines/engineering-control-spine.md | +| 2026-06-07 | created | `doctrine:repo:systems-should-tell-on-themselves` | doctrine | docs/doctrines/systems-should-tell-on-themselves.md | +| 2026-06-07 | created | `doctrine:repo:typed-encapsulated-architecture-style` | doctrine | docs/doctrines/typed-encapsulated-architecture-style.md | +| 2026-06-07 | created | `map:automation:overview` | map | docs/maps/automation.md | +| 2026-06-07 | created | `note:context:hidden-context-is-operational-risk` | note | kb/notes/context/hidden-context-is-operational-risk.md | +| 2026-06-07 | created | `note:evidence:systems-should-tell-on-themselves` | note | kb/notes/evidence/systems-should-tell-on-themselves.md | +| 2026-06-07 | created | `note:operability:future-operators-need-context` | note | kb/notes/operability/future-operators-need-context.md | + +### mutation + +6 node(s) carry this concept. + +| Date | Event | Node | Type | Path | +|---|---|---|---|---| +| 2026-06-07 | created | `antipattern:undocumented-mutation` | antipattern | kb/antipatterns/undocumented-mutation.md | +| 2026-06-07 | created | `concept:mutation` | concept | kb/concepts/mutation.md | +| 2026-06-07 | created | `example:automation:safe-automation-script` | example | kb/examples/safe-automation-script.md | +| 2026-06-07 | created | `map:automation:overview` | map | docs/maps/automation.md | +| 2026-06-07 | created | `note:boundaries:tools-should-make-boundaries-obvious` | note | kb/notes/boundaries/tools-should-make-boundaries-obvious.md | +| 2026-06-07 | created | `note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand` | note | kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md | + +### observability + +6 node(s) carry this concept. + +| Date | Event | Node | Type | Path | +|---|---|---|---|---| +| 2026-06-07 | created | `antipattern:hallucinated-operational-state` | antipattern | kb/antipatterns/hallucinated-operational-state.md | +| 2026-06-07 | created | `concept:observability` | concept | kb/concepts/observability.md | +| 2026-06-07 | created | `example:observability:splunk-health-state` | example | kb/examples/splunk-health-state.md | +| 2026-06-07 | created | `map:observability:overview` | map | docs/maps/observability.md | +| 2026-06-07 | created | `note:evidence:evidence-over-vanity-metrics` | note | kb/notes/evidence/evidence-over-vanity-metrics.md | +| 2026-06-07 | created | `note:observability:operators-should-not-hallucinate-system-state` | note | kb/notes/observability/operators-should-not-hallucinate-system-state.md | + +### validation + +6 node(s) carry this concept. + +| Date | Event | Node | Type | Path | +|---|---|---|---|---| +| 2026-06-07 | created | `concept:validation` | concept | kb/concepts/validation.md | +| 2026-06-07 | created | `decision:repo:0003-ship-tea-kb-lifecycle-tooling` | decision | docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md | +| 2026-06-07 | created | `example:agents:agent-tool-boundary` | example | kb/examples/agent-tool-boundary.md | +| 2026-06-07 | created | `map:agent-architecture:overview` | map | docs/maps/agent-architecture.md | +| 2026-06-07 | created | `note:boundaries:tools-should-make-boundaries-obvious` | note | kb/notes/boundaries/tools-should-make-boundaries-obvious.md | +| 2026-06-07 | created | `note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand` | note | kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md | + +### context-regression + +5 node(s) carry this concept. + +| Date | Event | Node | Type | Path | +|---|---|---|---|---| +| 2026-06-07 | created | `antipattern:hidden-operational-context` | antipattern | kb/antipatterns/hidden-operational-context.md | +| 2026-06-07 | created | `concept:context-regression` | concept | kb/concepts/context-regression.md | +| 2026-06-07 | created | `note:context:hidden-context-is-operational-risk` | note | kb/notes/context/hidden-context-is-operational-risk.md | +| 2026-06-07 | created | `note:evidence:systems-should-tell-on-themselves` | note | kb/notes/evidence/systems-should-tell-on-themselves.md | +| 2026-06-07 | created | `note:operability:future-operators-need-context` | note | kb/notes/operability/future-operators-need-context.md | diff --git a/graph/generated/timeline.jsonl b/graph/generated/timeline.jsonl new file mode 100644 index 0000000..fd6020b --- /dev/null +++ b/graph/generated/timeline.jsonl @@ -0,0 +1,48 @@ +{"concepts": ["observability", "explicit-state", "evidence"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "antipattern:hallucinated-operational-state", "node_type": "antipattern", "path": "kb/antipatterns/hallucinated-operational-state.md", "title": "Hallucinated Operational State"} +{"concepts": ["operability", "context-regression"], "date": "2026-06-07", "domain": "operability", "event_type": "created", "node_id": "antipattern:hidden-operational-context", "node_type": "antipattern", "path": "kb/antipatterns/hidden-operational-context.md", "title": "Hidden Operational Context"} +{"concepts": ["mutation", "evidence"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "antipattern:undocumented-mutation", "node_type": "antipattern", "path": "kb/antipatterns/undocumented-mutation.md", "title": "Undocumented Mutation"} +{"concepts": ["evidence", "metrics"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "antipattern:vanity-metrics", "node_type": "antipattern", "path": "kb/antipatterns/vanity-metrics.md", "title": "Vanity Metrics"} +{"concepts": ["agents"], "date": "2026-06-07", "domain": "agent-architecture", "event_type": "created", "node_id": "concept:agents", "node_type": "concept", "path": "kb/concepts/agents.md", "title": "Agents"} +{"concepts": ["automation"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "concept:automation", "node_type": "concept", "path": "kb/concepts/automation.md", "title": "Automation"} +{"concepts": ["boundary", "encapsulation"], "date": "2026-06-07", "domain": "coding", "event_type": "created", "node_id": "concept:boundary", "node_type": "concept", "path": "kb/concepts/boundary.md", "title": "Boundary"} +{"concepts": ["change-control"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "concept:change-control", "node_type": "concept", "path": "kb/concepts/change-control.md", "title": "Change Control"} +{"concepts": ["context-regression"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "concept:context-regression", "node_type": "concept", "path": "kb/concepts/context-regression.md", "title": "Context Regression"} +{"concepts": ["contract"], "date": "2026-06-07", "domain": "coding", "event_type": "created", "node_id": "concept:contract", "node_type": "concept", "path": "kb/concepts/contract.md", "title": "Contract"} +{"concepts": ["diagnostics"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "concept:diagnostics", "node_type": "concept", "path": "kb/concepts/diagnostics.md", "title": "Diagnostics"} +{"concepts": ["evidence"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "concept:evidence", "node_type": "concept", "path": "kb/concepts/evidence.md", "title": "Evidence"} +{"concepts": ["explicit-state", "state"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "concept:explicit-state", "node_type": "concept", "path": "kb/concepts/explicit-state.md", "title": "Explicit State"} +{"concepts": ["idempotency"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "concept:idempotency", "node_type": "concept", "path": "kb/concepts/idempotency.md", "title": "Idempotency"} +{"concepts": ["metrics"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "concept:metrics", "node_type": "concept", "path": "kb/concepts/metrics.md", "title": "Metrics"} +{"concepts": ["mutation"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "concept:mutation", "node_type": "concept", "path": "kb/concepts/mutation.md", "title": "Mutation"} +{"concepts": ["observability"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "concept:observability", "node_type": "concept", "path": "kb/concepts/observability.md", "title": "Observability"} +{"concepts": ["operability"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "concept:operability", "node_type": "concept", "path": "kb/concepts/operability.md", "title": "Operability"} +{"concepts": ["provenance"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "concept:provenance", "node_type": "concept", "path": "kb/concepts/provenance.md", "title": "Provenance"} +{"concepts": ["validation"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "concept:validation", "node_type": "concept", "path": "kb/concepts/validation.md", "title": "Validation"} +{"concepts": ["second brain", "markdown", "maps of content", "related links"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "decision:repo:0001-adopt-github-native-second-brain-doctrine", "node_type": "decision", "path": "docs/decisions/0001-adopt-github-native-second-brain-doctrine.md", "title": "Adopt GitHub-Native Second-Brain Doctrine"} +{"concepts": ["markdown", "frontmatter", "graph", "generated artifacts"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "decision:repo:0002-adopt-markdown-native-doctrine-graph", "node_type": "decision", "path": "docs/decisions/0002-adopt-markdown-native-doctrine-graph.md", "title": "Adopt Markdown-Native Doctrine Graph"} +{"concepts": ["lifecycle tooling", "validation", "graph", "reports", "visualization"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "decision:repo:0003-ship-tea-kb-lifecycle-tooling", "node_type": "decision", "path": "docs/decisions/0003-ship-tea-kb-lifecycle-tooling.md", "title": "Ship TEA KB Lifecycle Tooling"} +{"concepts": ["change control", "boundaries", "state", "contracts", "feedback loops", "operability"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "doctrine:repo:engineering-control-spine", "node_type": "doctrine", "path": "docs/doctrines/engineering-control-spine.md", "title": "Engineering Control Spine"} +{"concepts": ["evidence", "operability", "state exposure", "failure modes", "context regression"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "doctrine:repo:systems-should-tell-on-themselves", "node_type": "doctrine", "path": "docs/doctrines/systems-should-tell-on-themselves.md", "title": "Systems Should Tell on Themselves"} +{"concepts": ["doctrine graph", "lifecycle tooling", "markdown", "context regression"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "doctrine:repo:tea-style-doctrine", "node_type": "doctrine", "path": "docs/doctrines/tea-style-doctrine.md", "title": "TEA Style Doctrine"} +{"concepts": ["typing", "encapsulation", "architecture", "contracts", "operability"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "doctrine:repo:typed-encapsulated-architecture-style", "node_type": "doctrine", "path": "docs/doctrines/typed-encapsulated-architecture-style.md", "title": "Typed Encapsulated Architecture Style"} +{"concepts": ["agents", "boundary", "validation"], "date": "2026-06-07", "domain": "agent-architecture", "event_type": "created", "node_id": "example:agents:agent-tool-boundary", "node_type": "example", "path": "kb/examples/agent-tool-boundary.md", "title": "Agent Tool Boundary"} +{"concepts": ["automation", "evidence", "mutation"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "example:automation:safe-automation-script", "node_type": "example", "path": "kb/examples/safe-automation-script.md", "title": "Safe Automation Script"} +{"concepts": ["observability", "evidence", "explicit-state"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "example:observability:splunk-health-state", "node_type": "example", "path": "kb/examples/splunk-health-state.md", "title": "Splunk Health State"} +{"concepts": ["agents", "tool boundaries", "validation", "provenance"], "date": "2026-06-07", "domain": "agent-architecture", "event_type": "created", "node_id": "map:agent-architecture:overview", "node_type": "map", "path": "docs/maps/agent-architecture.md", "title": "Agent Architecture Map"} +{"concepts": ["idempotency", "mutation", "evidence", "operability"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "map:automation:overview", "node_type": "map", "path": "docs/maps/automation.md", "title": "Automation Map"} +{"concepts": ["boundaries", "typing", "contracts"], "date": "2026-06-07", "domain": "coding", "event_type": "created", "node_id": "map:coding:overview", "node_type": "map", "path": "docs/maps/coding.md", "title": "Coding Map"} +{"concepts": ["observability", "evidence", "system state"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "map:observability:overview", "node_type": "map", "path": "docs/maps/observability.md", "title": "Observability Map"} +{"concepts": ["doctrine graph", "engineering doctrine", "navigation"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "map:repo:engineering-doctrine", "node_type": "map", "path": "docs/maps/engineering-doctrine.md", "title": "Engineering Doctrine Map"} +{"concepts": ["boundary", "contract", "mutation", "validation"], "date": "2026-06-07", "domain": "coding", "event_type": "created", "node_id": "note:boundaries:tools-should-make-boundaries-obvious", "node_type": "note", "path": "kb/notes/boundaries/tools-should-make-boundaries-obvious.md", "title": "Tools Should Make Boundaries Obvious"} +{"concepts": ["operability", "context-regression", "provenance"], "date": "2026-06-07", "domain": "operability", "event_type": "created", "node_id": "note:context:hidden-context-is-operational-risk", "node_type": "note", "path": "kb/notes/context/hidden-context-is-operational-risk.md", "title": "Hidden Context Is Operational Risk"} +{"concepts": ["evidence", "observability", "metrics"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "note:evidence:evidence-over-vanity-metrics", "node_type": "note", "path": "kb/notes/evidence/evidence-over-vanity-metrics.md", "title": "Evidence Over Vanity Metrics"} +{"concepts": ["evidence", "operability", "explicit-state", "context-regression"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "note:evidence:systems-should-tell-on-themselves", "node_type": "note", "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "title": "Systems Should Tell on Themselves"} +{"concepts": ["mutation", "evidence", "change-control", "validation"], "date": "2026-06-07", "domain": "automation", "event_type": "created", "node_id": "note:mutation:mutation-should-be-atomic-visible-and-hard-to-misunderstand", "node_type": "note", "path": "kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md", "title": "Mutation Should Be Atomic Visible and Hard to Misunderstand"} +{"concepts": ["observability", "explicit-state", "evidence", "diagnostics"], "date": "2026-06-07", "domain": "observability", "event_type": "created", "node_id": "note:observability:operators-should-not-hallucinate-system-state", "node_type": "note", "path": "kb/notes/observability/operators-should-not-hallucinate-system-state.md", "title": "Operators Should Not Hallucinate System State"} +{"concepts": ["operability", "provenance", "context-regression", "evidence"], "date": "2026-06-07", "domain": "operability", "event_type": "created", "node_id": "note:operability:future-operators-need-context", "node_type": "note", "path": "kb/notes/operability/future-operators-need-context.md", "title": "Future Operators Need Context"} +{"concepts": ["agent editing", "review", "provenance", "proposed edges"], "date": "2026-06-07", "domain": "agent-architecture", "event_type": "created", "node_id": "standard:repo:agent-kb-editing-standard", "node_type": "standard", "path": "docs/standards/agent-kb-editing-standard.md", "title": "Agent KB Editing Standard"} +{"concepts": ["generated artifacts", "determinism", "reports", "exports"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "standard:repo:generated-artifact-standard", "node_type": "standard", "path": "docs/standards/generated-artifact-standard.md", "title": "Generated Artifact Standard"} +{"concepts": ["graph", "frontmatter", "node", "edge", "generated artifacts"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "standard:repo:graph-knowledge-base-standard", "node_type": "standard", "path": "docs/standards/graph-knowledge-base-standard.md", "title": "Graph Knowledge Base Standard"} +{"concepts": ["edges", "linking", "related links", "graph hygiene"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "standard:repo:graph-linking-standard", "node_type": "standard", "path": "docs/standards/graph-linking-standard.md", "title": "Graph Linking Standard"} +{"concepts": ["typing", "pydantic", "dataclasses", "protocols", "static analysis"], "date": "2026-06-07", "domain": "coding", "event_type": "created", "node_id": "standard:repo:python-type-discipline", "node_type": "standard", "path": "docs/standards/python-type-discipline.md", "title": "Python Type Discipline"} +{"concepts": ["visualization", "diagnostics", "graph", "source links"], "date": "2026-06-07", "domain": "repo-wide", "event_type": "created", "node_id": "standard:repo:visualization-standard", "node_type": "standard", "path": "docs/standards/visualization-standard.md", "title": "Visualization Standard"} diff --git a/graph/generated/visualizations/README.md b/graph/generated/visualizations/README.md new file mode 100644 index 0000000..4898368 --- /dev/null +++ b/graph/generated/visualizations/README.md @@ -0,0 +1,22 @@ +# Generated Visualizations + +Generated by `uv run tea-kb build` from Markdown/frontmatter graph source. + +## README visuals + +- [Repository system](repo-system.svg) +- [Research support map](research-support.svg) +- [Knowledge base growth](timeline-overview.svg) + +## Diagnostic views + +- [Interactive graph overview](overview.html) + +## Major concept timelines + +- [evidence](concept-timeline-evidence.svg) - 14 node(s) +- [operability](concept-timeline-operability.svg) - 9 node(s) +- [mutation](concept-timeline-mutation.svg) - 6 node(s) +- [observability](concept-timeline-observability.svg) - 6 node(s) +- [validation](concept-timeline-validation.svg) - 6 node(s) +- [context-regression](concept-timeline-context-regression.svg) - 5 node(s) diff --git a/graph/generated/visualizations/concept-timeline-context-regression.svg b/graph/generated/visualizations/concept-timeline-context-regression.svg new file mode 100644 index 0000000..05729ad --- /dev/null +++ b/graph/generated/visualizations/concept-timeline-context-regression.svg @@ -0,0 +1,59 @@ + + + + + + + + + + +Concept Timeline: context-regression +5 dated event(s) associated with this concept. + + +2026-06-07 + + + +created +Hidden Operational Context +antipattern - antipattern:hidden-operational-context + + +2026-06-07 + + + +created +Context Regression +concept - concept:context-regression + + +2026-06-07 + + + +created +Hidden Context Is Operational Risk +note - note:context:hidden-context-is-operational-risk + + +2026-06-07 + + + +created +Systems Should Tell on Themselves +note - note:evidence:systems-should-tell-on-themselves + + +2026-06-07 + + + +created +Future Operators Need Context +note - note:operability:future-operators-need-context + + \ No newline at end of file diff --git a/graph/generated/visualizations/concept-timeline-evidence.svg b/graph/generated/visualizations/concept-timeline-evidence.svg new file mode 100644 index 0000000..6816348 --- /dev/null +++ b/graph/generated/visualizations/concept-timeline-evidence.svg @@ -0,0 +1,140 @@ + + + + + + + + + + +Concept Timeline: evidence +14 dated event(s) associated with this concept. + + +2026-06-07 + + + +created +Hallucinated Operational State +antipattern - antipattern:hallucinated-operational-state + + +2026-06-07 + + + +created +Undocumented Mutation +antipattern - antipattern:undocumented-mutation + + +2026-06-07 + + + +created +Vanity Metrics +antipattern - antipattern:vanity-metrics + + +2026-06-07 + + + +created +Evidence +concept - concept:evidence + + +2026-06-07 + + + +created +Systems Should Tell on Themselves +doctrine - doctrine:repo:systems-should-tell-on-themselves + + +2026-06-07 + + + +created +Safe Automation Script +example - example:automation:safe-automation-script + + +2026-06-07 + + + +created +Splunk Health State +example - example:observability:splunk-health-state + + +2026-06-07 + + + +created +Automation Map +map - map:automation:overview + + +2026-06-07 + + + +created +Observability Map +map - map:observability:overview + + +2026-06-07 + + + +created +Evidence Over Vanity Metrics +note - note:evidence:evidence-over-vanity-metrics + + +2026-06-07 + + + +created +Systems Should Tell on Themselves +note - note:evidence:systems-should-tell-on-themselves + + +2026-06-07 + + + +created +Mutation Should Be Atomic Visible and Hard to Misunderstand +note - note:mutation:mutation-should-be-atomic-visible-and-hard-to... + + +2026-06-07 + + + +created +Operators Should Not Hallucinate System State +note - note:observability:operators-should-not-hallucinate-system-... + + +2026-06-07 + + + +created +Future Operators Need Context +note - note:operability:future-operators-need-context + + \ No newline at end of file diff --git a/graph/generated/visualizations/concept-timeline-mutation.svg b/graph/generated/visualizations/concept-timeline-mutation.svg new file mode 100644 index 0000000..59a59a9 --- /dev/null +++ b/graph/generated/visualizations/concept-timeline-mutation.svg @@ -0,0 +1,68 @@ + + + + + + + + + + +Concept Timeline: mutation +6 dated event(s) associated with this concept. + + +2026-06-07 + + + +created +Undocumented Mutation +antipattern - antipattern:undocumented-mutation + + +2026-06-07 + + + +created +Mutation +concept - concept:mutation + + +2026-06-07 + + + +created +Safe Automation Script +example - example:automation:safe-automation-script + + +2026-06-07 + + + +created +Automation Map +map - map:automation:overview + + +2026-06-07 + + + +created +Tools Should Make Boundaries Obvious +note - note:boundaries:tools-should-make-boundaries-obvious + + +2026-06-07 + + + +created +Mutation Should Be Atomic Visible and Hard to Misunderstand +note - note:mutation:mutation-should-be-atomic-visible-and-hard-to... + + \ No newline at end of file diff --git a/graph/generated/visualizations/concept-timeline-observability.svg b/graph/generated/visualizations/concept-timeline-observability.svg new file mode 100644 index 0000000..a513c9d --- /dev/null +++ b/graph/generated/visualizations/concept-timeline-observability.svg @@ -0,0 +1,68 @@ + + + + + + + + + + +Concept Timeline: observability +6 dated event(s) associated with this concept. + + +2026-06-07 + + + +created +Hallucinated Operational State +antipattern - antipattern:hallucinated-operational-state + + +2026-06-07 + + + +created +Observability +concept - concept:observability + + +2026-06-07 + + + +created +Splunk Health State +example - example:observability:splunk-health-state + + +2026-06-07 + + + +created +Observability Map +map - map:observability:overview + + +2026-06-07 + + + +created +Evidence Over Vanity Metrics +note - note:evidence:evidence-over-vanity-metrics + + +2026-06-07 + + + +created +Operators Should Not Hallucinate System State +note - note:observability:operators-should-not-hallucinate-system-... + + \ No newline at end of file diff --git a/graph/generated/visualizations/concept-timeline-operability.svg b/graph/generated/visualizations/concept-timeline-operability.svg new file mode 100644 index 0000000..f57193f --- /dev/null +++ b/graph/generated/visualizations/concept-timeline-operability.svg @@ -0,0 +1,95 @@ + + + + + + + + + + +Concept Timeline: operability +9 dated event(s) associated with this concept. + + +2026-06-07 + + + +created +Hidden Operational Context +antipattern - antipattern:hidden-operational-context + + +2026-06-07 + + + +created +Operability +concept - concept:operability + + +2026-06-07 + + + +created +Engineering Control Spine +doctrine - doctrine:repo:engineering-control-spine + + +2026-06-07 + + + +created +Systems Should Tell on Themselves +doctrine - doctrine:repo:systems-should-tell-on-themselves + + +2026-06-07 + + + +created +Typed Encapsulated Architecture Style +doctrine - doctrine:repo:typed-encapsulated-architecture-style + + +2026-06-07 + + + +created +Automation Map +map - map:automation:overview + + +2026-06-07 + + + +created +Hidden Context Is Operational Risk +note - note:context:hidden-context-is-operational-risk + + +2026-06-07 + + + +created +Systems Should Tell on Themselves +note - note:evidence:systems-should-tell-on-themselves + + +2026-06-07 + + + +created +Future Operators Need Context +note - note:operability:future-operators-need-context + + \ No newline at end of file diff --git a/graph/generated/visualizations/concept-timeline-validation.svg b/graph/generated/visualizations/concept-timeline-validation.svg new file mode 100644 index 0000000..34cf49f --- /dev/null +++ b/graph/generated/visualizations/concept-timeline-validation.svg @@ -0,0 +1,68 @@ + + + + + + + + + + +Concept Timeline: validation +6 dated event(s) associated with this concept. + + +2026-06-07 + + + +created +Validation +concept - concept:validation + + +2026-06-07 + + + +created +Ship TEA KB Lifecycle Tooling +decision - decision:repo:0003-ship-tea-kb-lifecycle-tooling + + +2026-06-07 + + + +created +Agent Tool Boundary +example - example:agents:agent-tool-boundary + + +2026-06-07 + + + +created +Agent Architecture Map +map - map:agent-architecture:overview + + +2026-06-07 + + + +created +Tools Should Make Boundaries Obvious +note - note:boundaries:tools-should-make-boundaries-obvious + + +2026-06-07 + + + +created +Mutation Should Be Atomic Visible and Hard to Misunderstand +note - note:mutation:mutation-should-be-atomic-visible-and-hard-to... + + \ No newline at end of file diff --git a/graph/generated/visualizations/overview.html b/graph/generated/visualizations/overview.html index ea91bac..c49b2e3 100644 --- a/graph/generated/visualizations/overview.html +++ b/graph/generated/visualizations/overview.html @@ -13,7 +13,7 @@

TEA Graph Overview

-

Nodes: 48. Edges: 87. Chunks: 183.

+

Nodes: 48. Edges: 87. Chunks: 184.

Nodes

diff --git a/graph/generated/visualizations/repo-system.svg b/graph/generated/visualizations/repo-system.svg new file mode 100644 index 0000000..b5b4256 --- /dev/null +++ b/graph/generated/visualizations/repo-system.svg @@ -0,0 +1,48 @@ + + + + + + + + + + +How tea-style Works +Markdown stays canonical. Tooling regenerates evidence. + + +Markdown Source +48 graph nodes +7 notes +16 concepts +frontmatter is canonical + + +tea-kb Lifecycle +parse frontmatter +validate contracts +build graph +report health +render visualizations + + +Generated Brew +nodes / edges / chunks +timeline events +Markdown reports +SVG + HTML views + + +Consumers +README visuals +GitHub Actions +human review +future search/RAG +agent context + + + + +CI enforces: validate -> tests -> build --check + \ No newline at end of file diff --git a/graph/generated/visualizations/research-support.svg b/graph/generated/visualizations/research-support.svg new file mode 100644 index 0000000..c0c8fcb --- /dev/null +++ b/graph/generated/visualizations/research-support.svg @@ -0,0 +1,76 @@ + + + + + + + + + + +Research Support Map +Doctrine, standards, decisions, notes, and examples support each other as a graph. + +Doctrines +4 + +Standards +6 + +Decisions +3 + +Notes +7 + +Examples +3 +Highest-degree doctrine nodes +Major concepts in use + + +Engineering Control Spine +doctrine:repo:engineering-contr... + + + +TEA Style Doctrine +doctrine:repo:tea-style-doctrine + + + +Systems Should Tell on Themselves +note:evidence:systems-should-te... + + + +Systems Should Tell on Themselves +doctrine:repo:systems-should-te... + + + +Graph Knowledge Base Standard +standard:repo:graph-knowledge-b... + + + +evidence +14 + + +operability +9 + + +mutation +6 + + +observability +6 + + +validation +6 +87 semantic edges connect research into reviewable paths. + \ No newline at end of file diff --git a/graph/generated/visualizations/timeline-overview.svg b/graph/generated/visualizations/timeline-overview.svg new file mode 100644 index 0000000..58ab24a --- /dev/null +++ b/graph/generated/visualizations/timeline-overview.svg @@ -0,0 +1,36 @@ + + + + + + + + + + +Knowledge Base Growth +Generated from `created` and `updated` frontmatter dates. + + +48 +2026-06-07 +48 created / 0 updated +Event mix + +antipattern: 4 + +concept: 16 + +decision: 3 + +doctrine: 4 + +example: 3 + +map: 5 + +note: 7 + +standard: 6 +48 timeline event(s) across 1 date(s). + \ No newline at end of file diff --git a/graph/schema.md b/graph/schema.md index 27fd299..26165a8 100644 --- a/graph/schema.md +++ b/graph/schema.md @@ -14,6 +14,8 @@ The graph is a directed labeled property graph derived from authored Markdown/fr "title": "Systems Should Tell on Themselves", "domain": "repo-wide", "status": "active", + "created": "2026-06-07", + "updated": "2026-06-07", "concepts": ["evidence", "operability"], "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", "source_hash": "..." @@ -42,11 +44,30 @@ The graph is a directed labeled property graph derived from authored Markdown/fr "concepts": ["evidence", "operability"], "domain": "repo-wide", "node_type": "note", + "created": "2026-06-07", + "updated": "2026-06-07", "outbound_edges": ["doctrine:repo:systems-should-tell-on-themselves"], "source_hash": "..." } ``` +## Timeline event shape +```json +{ + "date": "2026-06-07", + "event_type": "created", + "node_id": "note:evidence:systems-should-tell-on-themselves", + "node_type": "note", + "title": "Systems Should Tell on Themselves", + "domain": "repo-wide", + "path": "kb/notes/evidence/systems-should-tell-on-themselves.md", + "concepts": ["evidence", "operability"] +} +``` + +Timeline events are derived from source frontmatter. `created` emits a `created` event. +`updated` emits an `updated` event when it differs from `created`. + ## Related pages - [docs/standards/graph-knowledge-base-standard.md](../docs/standards/graph-knowledge-base-standard.md) - [docs/standards/generated-artifact-standard.md](../docs/standards/generated-artifact-standard.md) diff --git a/kb/antipatterns/hallucinated-operational-state.md b/kb/antipatterns/hallucinated-operational-state.md index f7886a3..946d695 100644 --- a/kb/antipatterns/hallucinated-operational-state.md +++ b/kb/antipatterns/hallucinated-operational-state.md @@ -4,6 +4,8 @@ title: Hallucinated Operational State type: antipattern domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > A human, agent, or tool claims system state without evidence from authoritative sources. concepts: diff --git a/kb/antipatterns/hidden-operational-context.md b/kb/antipatterns/hidden-operational-context.md index 794d1db..80898cd 100644 --- a/kb/antipatterns/hidden-operational-context.md +++ b/kb/antipatterns/hidden-operational-context.md @@ -4,6 +4,8 @@ title: Hidden Operational Context type: antipattern domain: operability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > A system relies on unstated human knowledge to operate or diagnose safely. concepts: diff --git a/kb/antipatterns/undocumented-mutation.md b/kb/antipatterns/undocumented-mutation.md index ba9c2cb..f3ff26d 100644 --- a/kb/antipatterns/undocumented-mutation.md +++ b/kb/antipatterns/undocumented-mutation.md @@ -4,6 +4,8 @@ title: Undocumented Mutation type: antipattern domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > A tool mutates state without clear plan, boundary, evidence, or recovery path. concepts: diff --git a/kb/antipatterns/vanity-metrics.md b/kb/antipatterns/vanity-metrics.md index c6f23d0..8d2471a 100644 --- a/kb/antipatterns/vanity-metrics.md +++ b/kb/antipatterns/vanity-metrics.md @@ -4,6 +4,8 @@ title: Vanity Metrics type: antipattern domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Metrics that show activity without improving decisions, diagnosis, or safety. concepts: diff --git a/kb/concepts/agents.md b/kb/concepts/agents.md index 53ce4f4..c12b1a9 100644 --- a/kb/concepts/agents.md +++ b/kb/concepts/agents.md @@ -4,6 +4,8 @@ title: Agents type: concept domain: agent-architecture status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Software actors that use model output, tools, context, and control boundaries to perform work. concepts: diff --git a/kb/concepts/automation.md b/kb/concepts/automation.md index cff9ab1..9035aee 100644 --- a/kb/concepts/automation.md +++ b/kb/concepts/automation.md @@ -4,6 +4,8 @@ title: Automation type: concept domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Software-controlled execution of repeatable operational or engineering work. concepts: diff --git a/kb/concepts/boundary.md b/kb/concepts/boundary.md index dca07b5..c84ee7e 100644 --- a/kb/concepts/boundary.md +++ b/kb/concepts/boundary.md @@ -4,6 +4,8 @@ title: Boundary type: concept domain: coding status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > A public interface where messy internals, external systems, or side effects are contained. concepts: diff --git a/kb/concepts/change-control.md b/kb/concepts/change-control.md index 424caf0..e119560 100644 --- a/kb/concepts/change-control.md +++ b/kb/concepts/change-control.md @@ -4,6 +4,8 @@ title: Change Control type: concept domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Explicit handling of what can change, who approves it, how it is validated, and how it is recovered. concepts: diff --git a/kb/concepts/context-regression.md b/kb/concepts/context-regression.md index f839406..1d3feac 100644 --- a/kb/concepts/context-regression.md +++ b/kb/concepts/context-regression.md @@ -4,6 +4,8 @@ title: Context Regression type: concept domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Rediscovery of knowledge that should already exist as durable doctrine. concepts: diff --git a/kb/concepts/contract.md b/kb/concepts/contract.md index 9d12754..ac3cbd7 100644 --- a/kb/concepts/contract.md +++ b/kb/concepts/contract.md @@ -4,6 +4,8 @@ title: Contract type: concept domain: coding status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > A promise about inputs, outputs, side effects, errors, compatibility, or behavior. concepts: diff --git a/kb/concepts/diagnostics.md b/kb/concepts/diagnostics.md index 47f6eb7..2a9f9cb 100644 --- a/kb/concepts/diagnostics.md +++ b/kb/concepts/diagnostics.md @@ -4,6 +4,8 @@ title: Diagnostics type: concept domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Evidence and methods used to determine what is happening and why. concepts: diff --git a/kb/concepts/evidence.md b/kb/concepts/evidence.md index e60f660..3bcff7e 100644 --- a/kb/concepts/evidence.md +++ b/kb/concepts/evidence.md @@ -4,6 +4,8 @@ title: Evidence type: concept domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Structured proof that supports an operational, architectural, or review claim. concepts: diff --git a/kb/concepts/explicit-state.md b/kb/concepts/explicit-state.md index fe7b119..e38c150 100644 --- a/kb/concepts/explicit-state.md +++ b/kb/concepts/explicit-state.md @@ -4,6 +4,8 @@ title: Explicit State type: concept domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > State modeled clearly enough for humans and tools to inspect and reason about it. concepts: diff --git a/kb/concepts/idempotency.md b/kb/concepts/idempotency.md index e314952..36985cc 100644 --- a/kb/concepts/idempotency.md +++ b/kb/concepts/idempotency.md @@ -4,6 +4,8 @@ title: Idempotency type: concept domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Repeating an operation does not cause unintended additional effects. concepts: diff --git a/kb/concepts/metrics.md b/kb/concepts/metrics.md index 2d01fea..33783f6 100644 --- a/kb/concepts/metrics.md +++ b/kb/concepts/metrics.md @@ -4,6 +4,8 @@ title: Metrics type: concept domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Numeric measurements that should support diagnosis, decisions, or trend analysis. concepts: diff --git a/kb/concepts/mutation.md b/kb/concepts/mutation.md index da3f429..83362e5 100644 --- a/kb/concepts/mutation.md +++ b/kb/concepts/mutation.md @@ -4,6 +4,8 @@ title: Mutation type: concept domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > An operation that changes system, repository, workflow, or external state. concepts: diff --git a/kb/concepts/observability.md b/kb/concepts/observability.md index a4e86ef..f786bea 100644 --- a/kb/concepts/observability.md +++ b/kb/concepts/observability.md @@ -4,6 +4,8 @@ title: Observability type: concept domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > The ability to understand system behavior from emitted evidence. concepts: diff --git a/kb/concepts/operability.md b/kb/concepts/operability.md index f67a0b5..be59eab 100644 --- a/kb/concepts/operability.md +++ b/kb/concepts/operability.md @@ -4,6 +4,8 @@ title: Operability type: concept domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > The ability to run, diagnose, recover, audit, and safely evolve a system. concepts: diff --git a/kb/concepts/provenance.md b/kb/concepts/provenance.md index 4edfc94..09fd8fb 100644 --- a/kb/concepts/provenance.md +++ b/kb/concepts/provenance.md @@ -4,6 +4,8 @@ title: Provenance type: concept domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Information about where a claim, node, edge, artifact, or decision came from. concepts: diff --git a/kb/concepts/validation.md b/kb/concepts/validation.md index ce58096..1c5c453 100644 --- a/kb/concepts/validation.md +++ b/kb/concepts/validation.md @@ -4,6 +4,8 @@ title: Validation type: concept domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Explicit checks that reject invalid source, state, plans, edges, or generated artifacts. concepts: diff --git a/kb/examples/agent-tool-boundary.md b/kb/examples/agent-tool-boundary.md index 641565e..bc3dd0f 100644 --- a/kb/examples/agent-tool-boundary.md +++ b/kb/examples/agent-tool-boundary.md @@ -4,6 +4,8 @@ title: Agent Tool Boundary type: example domain: agent-architecture status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Agent tools should expose deterministic read, validation, dry-run, and mutation boundaries. concepts: diff --git a/kb/examples/safe-automation-script.md b/kb/examples/safe-automation-script.md index 619e72b..ddfa77e 100644 --- a/kb/examples/safe-automation-script.md +++ b/kb/examples/safe-automation-script.md @@ -4,6 +4,8 @@ title: Safe Automation Script type: example domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > A safe automation script separates planning, validation, execution, and evidence. concepts: diff --git a/kb/examples/splunk-health-state.md b/kb/examples/splunk-health-state.md index 22d6a6d..4af55b4 100644 --- a/kb/examples/splunk-health-state.md +++ b/kb/examples/splunk-health-state.md @@ -4,6 +4,8 @@ title: Splunk Health State type: example domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Health should be reported as layered evidence, not a single unsupported label. concepts: diff --git a/kb/notes/boundaries/tools-should-make-boundaries-obvious.md b/kb/notes/boundaries/tools-should-make-boundaries-obvious.md index fe5668d..3598c7d 100644 --- a/kb/notes/boundaries/tools-should-make-boundaries-obvious.md +++ b/kb/notes/boundaries/tools-should-make-boundaries-obvious.md @@ -4,6 +4,8 @@ title: Tools Should Make Boundaries Obvious type: note domain: coding status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Tools should make read, write, validation, and execution boundaries visible. concepts: diff --git a/kb/notes/context/hidden-context-is-operational-risk.md b/kb/notes/context/hidden-context-is-operational-risk.md index 5d5dde6..1aa76ff 100644 --- a/kb/notes/context/hidden-context-is-operational-risk.md +++ b/kb/notes/context/hidden-context-is-operational-risk.md @@ -4,6 +4,8 @@ title: Hidden Context Is Operational Risk type: note domain: operability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Knowledge that exists only in the original author's memory makes systems fragile. concepts: diff --git a/kb/notes/evidence/evidence-over-vanity-metrics.md b/kb/notes/evidence/evidence-over-vanity-metrics.md index ae31e8d..5ac8c6c 100644 --- a/kb/notes/evidence/evidence-over-vanity-metrics.md +++ b/kb/notes/evidence/evidence-over-vanity-metrics.md @@ -4,6 +4,8 @@ title: Evidence Over Vanity Metrics type: note domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Prefer evidence that changes decisions over metrics that only make activity visible. concepts: diff --git a/kb/notes/evidence/systems-should-tell-on-themselves.md b/kb/notes/evidence/systems-should-tell-on-themselves.md index 8cdc2a6..2a96f49 100644 --- a/kb/notes/evidence/systems-should-tell-on-themselves.md +++ b/kb/notes/evidence/systems-should-tell-on-themselves.md @@ -4,6 +4,8 @@ title: Systems Should Tell on Themselves type: note domain: repo-wide status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Good systems reduce guessing by exposing state, capturing evidence, and making failure modes visible. concepts: diff --git a/kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md b/kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md index 2dde5c5..c978a20 100644 --- a/kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md +++ b/kb/notes/mutation/mutation-should-be-atomic-visible-and-hard-to-misunderstand.md @@ -4,6 +4,8 @@ title: Mutation Should Be Atomic Visible and Hard to Misunderstand type: note domain: automation status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Mutation should be deliberate, visible, bounded, and backed by evidence. concepts: diff --git a/kb/notes/observability/operators-should-not-hallucinate-system-state.md b/kb/notes/observability/operators-should-not-hallucinate-system-state.md index 602d751..833cf01 100644 --- a/kb/notes/observability/operators-should-not-hallucinate-system-state.md +++ b/kb/notes/observability/operators-should-not-hallucinate-system-state.md @@ -4,6 +4,8 @@ title: Operators Should Not Hallucinate System State type: note domain: observability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Operators and agents should inspect evidence instead of guessing current system state. concepts: diff --git a/kb/notes/operability/future-operators-need-context.md b/kb/notes/operability/future-operators-need-context.md index a87999f..d1d7376 100644 --- a/kb/notes/operability/future-operators-need-context.md +++ b/kb/notes/operability/future-operators-need-context.md @@ -4,6 +4,8 @@ title: Future Operators Need Context type: note domain: operability status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > Durable systems preserve enough context for future operators to diagnose and recover without rediscovery. concepts: diff --git a/src/tea_kb/boundary/frontmatter.py b/src/tea_kb/boundary/frontmatter.py index 22814a0..cc2f005 100644 --- a/src/tea_kb/boundary/frontmatter.py +++ b/src/tea_kb/boundary/frontmatter.py @@ -3,6 +3,7 @@ from __future__ import annotations from dataclasses import dataclass +from datetime import date from pathlib import Path from typing import Any @@ -28,6 +29,8 @@ class FrontmatterModel(BaseModel): type: NodeType domain: str = Field(min_length=1) status: str = "active" + created: date | None = None + updated: date | None = None summary: str | None = None concepts: list[str] = Field(default_factory=list) applies_when: list[str] = Field(default_factory=list) @@ -55,6 +58,8 @@ def to_node(self, source_hash: str) -> KnowledgeNode: source_hash=source_hash, summary=self.metadata.summary, aliases=tuple(self.metadata.aliases), + created=self.metadata.created, + updated=self.metadata.updated, ) diff --git a/src/tea_kb/cli/app.py b/src/tea_kb/cli/app.py index 1d58e7c..0bb5d2f 100644 --- a/src/tea_kb/cli/app.py +++ b/src/tea_kb/cli/app.py @@ -4,6 +4,7 @@ import json import shutil +from datetime import date from pathlib import Path import typer @@ -17,6 +18,13 @@ from tea_kb.lifecycle import all_artifacts, load_and_validate, report_only_artifacts from tea_kb.reports.diagnostics import Severity, ValidationReport from tea_kb.viz.mermaid import render_path_mermaid +from tea_kb.viz.pyvis_export import overview_artifact +from tea_kb.viz.svg import ( + repo_system_svg_artifact, + research_support_svg_artifact, + svg_visualization_artifacts, + timeline_overview_svg_artifact, +) app = typer.Typer(no_args_is_help=True) new_app = typer.Typer(no_args_is_help=True) @@ -158,13 +166,32 @@ def viz( result, validation = load_and_validate(repo) _exit_for_report(validation) if view == "overview": - ArtifactWriter(repo).write([all_artifacts(result, validation)[-1]]) + ArtifactWriter(repo).write([overview_artifact(result.graph)]) console.print("Wrote graph/generated/visualizations/overview.html") return + if view == "timeline": + ArtifactWriter(repo).write([timeline_overview_svg_artifact(result.graph)]) + console.print("Wrote graph/generated/visualizations/timeline-overview.svg") + return + if view == "system": + ArtifactWriter(repo).write([repo_system_svg_artifact(result.graph)]) + console.print("Wrote graph/generated/visualizations/repo-system.svg") + return + if view == "research": + ArtifactWriter(repo).write([research_support_svg_artifact(result.graph)]) + console.print("Wrote graph/generated/visualizations/research-support.svg") + return + if view == "all": + artifacts = [overview_artifact(result.graph), *svg_visualization_artifacts(result.graph)] + ArtifactWriter(repo).write(artifacts) + console.print(f"Wrote {len(artifacts)} visualization artifact(s).") + return if view == "path" and source and target: console.print(render_path_mermaid(result.graph, source, target)) return - console.print("Supported views: overview, path ") + console.print( + "Supported views: overview, timeline, system, research, all, path " + ) raise typer.Exit(2) @@ -321,12 +348,15 @@ def _write_template( console.print(f"Refusing to overwrite existing file: {path.as_posix()}") raise typer.Exit(1) target.parent.mkdir(parents=True, exist_ok=True) + today = date.today().isoformat() content = f"""--- id: {node_id} title: {title} type: {node_type} domain: {domain} status: active +created: {today} +updated: {today} summary: > TODO concepts: [] diff --git a/src/tea_kb/domain/models.py b/src/tea_kb/domain/models.py index c1a5a71..0cc5ac6 100644 --- a/src/tea_kb/domain/models.py +++ b/src/tea_kb/domain/models.py @@ -3,6 +3,7 @@ from __future__ import annotations from dataclasses import dataclass, field +from datetime import date from pathlib import Path from tea_kb.domain.enums import EdgeType, NodeType @@ -21,6 +22,8 @@ class KnowledgeNode: source_hash: str summary: str | None = None aliases: tuple[str, ...] = () + created: date | None = None + updated: date | None = None @dataclass(frozen=True, slots=True) @@ -44,6 +47,8 @@ class KnowledgeChunk: node_type: NodeType outbound_edges: tuple[NodeId, ...] source_hash: str + created: date | None = None + updated: date | None = None @dataclass(frozen=True, slots=True) diff --git a/src/tea_kb/graph/builder.py b/src/tea_kb/graph/builder.py index ee99f1f..7280be6 100644 --- a/src/tea_kb/graph/builder.py +++ b/src/tea_kb/graph/builder.py @@ -99,6 +99,8 @@ def build_graph(root: Path) -> BuildResult: node_type=node.node_type, outbound_edges=tuple(edge_targets_by_source.get(node.id, [])), source_hash=node.source_hash, + created=node.created, + updated=node.updated, ) ) diff --git a/src/tea_kb/graph/exporters.py b/src/tea_kb/graph/exporters.py index c1e011a..b52a9bb 100644 --- a/src/tea_kb/graph/exporters.py +++ b/src/tea_kb/graph/exporters.py @@ -3,10 +3,12 @@ from __future__ import annotations import json +from datetime import date from pathlib import Path from tea_kb.domain.enums import NodeType from tea_kb.domain.models import KnowledgeEdge, KnowledgeGraph, KnowledgeNode +from tea_kb.graph.timeline import timeline_events from tea_kb.io.artifact_writer import Artifact @@ -16,6 +18,7 @@ def graph_jsonl_artifacts(graph: KnowledgeGraph) -> list[Artifact]: Artifact(Path("graph/generated/edges.jsonl"), _edges_jsonl(graph)), Artifact(Path("graph/generated/chunks.jsonl"), _chunks_jsonl(graph)), Artifact(Path("graph/generated/concepts.jsonl"), _concepts_jsonl(graph)), + Artifact(Path("graph/generated/timeline.jsonl"), _timeline_jsonl(graph)), ] @@ -53,6 +56,8 @@ def _chunks_jsonl(graph: KnowledgeGraph) -> str: "node_type": chunk.node_type.value, "outbound_edges": [str(edge) for edge in chunk.outbound_edges], "source_hash": chunk.source_hash, + "created": _date_value(chunk.created), + "updated": _date_value(chunk.updated), } for chunk in graph.chunks ] @@ -67,6 +72,8 @@ def _concepts_jsonl(graph: KnowledgeGraph) -> str: "aliases": list(node.aliases), "status": node.status, "path": node.path.as_posix(), + "created": _date_value(node.created), + "updated": _date_value(node.updated), } for node in sorted(graph.nodes.values(), key=lambda item: item.id) if node.node_type == NodeType.CONCEPT @@ -74,6 +81,23 @@ def _concepts_jsonl(graph: KnowledgeGraph) -> str: return _jsonl(records) +def _timeline_jsonl(graph: KnowledgeGraph) -> str: + records = [ + { + "date": event.date.isoformat(), + "event_type": event.event_type, + "node_id": str(event.node_id), + "node_type": event.node_type.value, + "title": event.title, + "domain": event.domain, + "path": event.path.as_posix(), + "concepts": [str(concept) for concept in event.concepts], + } + for event in timeline_events(graph) + ] + return _jsonl(records) + + def _node_record(node: KnowledgeNode) -> dict[str, object]: return { "id": str(node.id), @@ -85,6 +109,8 @@ def _node_record(node: KnowledgeNode) -> dict[str, object]: "path": node.path.as_posix(), "source_hash": node.source_hash, "summary": node.summary, + "created": _date_value(node.created), + "updated": _date_value(node.updated), } @@ -96,3 +122,7 @@ def _jsonl(records: list[dict[str, object]]) -> str: return "".join( json.dumps(record, sort_keys=True, ensure_ascii=False) + "\n" for record in records ) + + +def _date_value(value: date | None) -> str | None: + return value.isoformat() if value is not None else None diff --git a/src/tea_kb/graph/timeline.py b/src/tea_kb/graph/timeline.py new file mode 100644 index 0000000..1c33a8a --- /dev/null +++ b/src/tea_kb/graph/timeline.py @@ -0,0 +1,63 @@ +"""Timeline views derived from graph node dates.""" + +from __future__ import annotations + +from collections import Counter +from dataclasses import dataclass +from datetime import date +from pathlib import Path + +from tea_kb.domain.enums import NodeType +from tea_kb.domain.ids import ConceptId, NodeId +from tea_kb.domain.models import KnowledgeGraph, KnowledgeNode + + +@dataclass(frozen=True, slots=True) +class TimelineEvent: + date: date + event_type: str + node_id: NodeId + title: str + node_type: NodeType + domain: str + path: Path + concepts: tuple[ConceptId, ...] + + +def timeline_events(graph: KnowledgeGraph) -> tuple[TimelineEvent, ...]: + events: list[TimelineEvent] = [] + for node in graph.nodes.values(): + if node.created is not None: + events.append(_event_for_node(node, node.created, "created")) + if node.updated is not None and node.updated != node.created: + events.append(_event_for_node(node, node.updated, "updated")) + return tuple( + sorted(events, key=lambda item: (item.date.isoformat(), item.event_type, item.node_id)) + ) + + +def major_concepts(graph: KnowledgeGraph, limit: int = 6) -> tuple[tuple[ConceptId, int], ...]: + counts: Counter[ConceptId] = Counter( + concept for node in graph.nodes.values() for concept in node.concepts + ) + ranked = sorted(counts.items(), key=lambda item: (-item[1], str(item[0]))) + return tuple((concept, count) for concept, count in ranked[:limit] if count > 0) + + +def events_for_concept( + events: tuple[TimelineEvent, ...], concept: ConceptId +) -> tuple[TimelineEvent, ...]: + return tuple(event for event in events if concept in event.concepts) + + +def _event_for_node(node: KnowledgeNode, event_date: date, event_type: str) -> TimelineEvent: + return TimelineEvent( + date=event_date, + event_type=event_type, + node_id=node.id, + title=node.title, + node_type=node.node_type, + domain=node.domain, + path=node.path, + concepts=node.concepts, + ) diff --git a/src/tea_kb/graph/validators.py b/src/tea_kb/graph/validators.py index 9fe5224..5842473 100644 --- a/src/tea_kb/graph/validators.py +++ b/src/tea_kb/graph/validators.py @@ -27,6 +27,7 @@ def validate_build_result(result: BuildResult, root: Path) -> ValidationReport: diagnostics.extend(_validate_acyclic_edges(graph, EdgeType.DEPENDS_ON)) diagnostics.extend(_validate_acyclic_edges(graph, EdgeType.SUPERSEDES)) diagnostics.extend(_validate_markdown_links(graph, root)) + diagnostics.extend(_validate_timeline_dates(graph)) diagnostics.extend(_validate_orphans(graph)) diagnostics.extend(_validate_dense_links(graph)) diagnostics.extend(_validate_related_to_overuse(graph)) @@ -110,6 +111,42 @@ def _validate_markdown_links(graph: KnowledgeGraph, root: Path) -> list[Diagnost return diagnostics +def _validate_timeline_dates(graph: KnowledgeGraph) -> list[Diagnostic]: + diagnostics: list[Diagnostic] = [] + for node in graph.nodes.values(): + if node.created is None: + diagnostics.append( + Diagnostic( + severity=Severity.WARNING, + code="missing-created-date", + message=f"{node.id} missing created date", + path=node.path.as_posix(), + node_id=str(node.id), + ) + ) + if node.updated is None: + diagnostics.append( + Diagnostic( + severity=Severity.WARNING, + code="missing-updated-date", + message=f"{node.id} missing updated date", + path=node.path.as_posix(), + node_id=str(node.id), + ) + ) + if node.created and node.updated and node.updated < node.created: + diagnostics.append( + Diagnostic( + severity=Severity.ERROR, + code="invalid-updated-date", + message=f"{node.id} updated date is before created date", + path=node.path.as_posix(), + node_id=str(node.id), + ) + ) + return diagnostics + + def _validate_orphans(graph: KnowledgeGraph) -> list[Diagnostic]: diagnostics: list[Diagnostic] = [] for node in graph.nodes.values(): diff --git a/src/tea_kb/lifecycle.py b/src/tea_kb/lifecycle.py index 6d25061..4ed924e 100644 --- a/src/tea_kb/lifecycle.py +++ b/src/tea_kb/lifecycle.py @@ -11,6 +11,7 @@ from tea_kb.reports.diagnostics import ValidationReport from tea_kb.reports.markdown_report import report_artifacts from tea_kb.viz.pyvis_export import overview_artifact +from tea_kb.viz.svg import svg_visualization_artifacts def load_and_validate(root: Path) -> tuple[BuildResult, ValidationReport]: @@ -25,6 +26,7 @@ def all_artifacts(result: BuildResult, report: ValidationReport) -> list[Artifac *graph_jsonl_artifacts(graph), *report_artifacts(graph, report), overview_artifact(graph), + *svg_visualization_artifacts(graph), ] diff --git a/src/tea_kb/parse/chunks.py b/src/tea_kb/parse/chunks.py index 3793321..e8569f1 100644 --- a/src/tea_kb/parse/chunks.py +++ b/src/tea_kb/parse/chunks.py @@ -2,6 +2,7 @@ from __future__ import annotations +from datetime import date from pathlib import Path from tea_kb.domain.enums import NodeType @@ -20,6 +21,8 @@ def build_chunks( node_type: NodeType, outbound_edges: tuple[NodeId, ...], source_hash: str, + created: date | None, + updated: date | None, ) -> tuple[KnowledgeChunk, ...]: chunks: list[KnowledgeChunk] = [] for section in sections: @@ -38,6 +41,8 @@ def build_chunks( node_type=node_type, outbound_edges=outbound_edges, source_hash=source_hash, + created=created, + updated=updated, ) ) return tuple(chunks) diff --git a/src/tea_kb/reports/markdown_report.py b/src/tea_kb/reports/markdown_report.py index e337b51..6808224 100644 --- a/src/tea_kb/reports/markdown_report.py +++ b/src/tea_kb/reports/markdown_report.py @@ -8,6 +8,7 @@ from tea_kb.domain.enums import NodeType from tea_kb.domain.ids import concept_id_for from tea_kb.domain.models import KnowledgeGraph +from tea_kb.graph.timeline import events_for_concept, major_concepts, timeline_events from tea_kb.io.artifact_writer import Artifact from tea_kb.reports.diagnostics import ValidationReport @@ -21,6 +22,7 @@ def report_artifacts(graph: KnowledgeGraph, report: ValidationReport) -> list[Ar Path("graph/generated/reports/duplicate-concepts.md"), render_duplicate_concepts(graph) ), Artifact(Path("graph/generated/reports/proposed-edges.md"), render_proposed_edges(graph)), + Artifact(Path("graph/generated/reports/timeline.md"), render_timeline_report(graph)), ] @@ -146,6 +148,65 @@ def render_proposed_edges(graph: KnowledgeGraph) -> str: return "\n".join(lines) +def render_timeline_report(graph: KnowledgeGraph) -> str: + events = timeline_events(graph) + created = sum(1 for event in events if event.event_type == "created") + updated = sum(1 for event in events if event.event_type == "updated") + rows_by_date: defaultdict[str, list[str]] = defaultdict(list) + for event in events: + rows_by_date[event.date.isoformat()].append(str(event.node_id)) + + lines = [ + "# Knowledge Timeline", + "", + "## Summary", + "", + f"- Timeline events: {len(events)}", + f"- Created events: {created}", + f"- Updated events: {updated}", + f"- Dated nodes: {sum(1 for node in graph.nodes.values() if node.created or node.updated)}", + "", + "## Overall Growth", + "", + "| Date | Events | Nodes |", + "|---|---:|---|", + ] + if rows_by_date: + for date_value, node_ids in sorted(rows_by_date.items()): + visible_nodes = ", ".join(f"`{node_id}`" for node_id in node_ids[:8]) + suffix = " ..." if len(node_ids) > 8 else "" + lines.append(f"| {date_value} | {len(node_ids)} | {visible_nodes}{suffix} |") + else: + lines.append("| None | 0 | None |") + + lines.extend(["", "## Major Concept Timelines", ""]) + for concept, count in major_concepts(graph): + concept_events = events_for_concept(events, concept) + lines.extend( + [ + f"### {concept}", + "", + f"{count} node(s) carry this concept.", + "", + "| Date | Event | Node | Type | Path |", + "|---|---|---|---|---|", + ] + ) + for event in concept_events[:20]: + lines.append( + "| " + f"{event.date.isoformat()} | " + f"{event.event_type} | " + f"`{event.node_id}` | " + f"{event.node_type.value} | " + f"{event.path.as_posix()} |" + ) + if not concept_events: + lines.append("| None | None | None | None | None |") + lines.append("") + return "\n".join(lines) + + def _highest_degree_rows(graph: KnowledgeGraph, limit: int = 10) -> list[str]: rows: list[tuple[str, int, int]] = [] for node in graph.nodes.values(): diff --git a/src/tea_kb/viz/svg.py b/src/tea_kb/viz/svg.py new file mode 100644 index 0000000..6f25dd9 --- /dev/null +++ b/src/tea_kb/viz/svg.py @@ -0,0 +1,543 @@ +"""Deterministic SVG visualizations for README and graph review.""" + +from __future__ import annotations + +from collections import Counter, defaultdict +from html import escape +from pathlib import Path + +from tea_kb.domain.enums import NodeType +from tea_kb.domain.ids import ConceptId, slugify +from tea_kb.domain.models import KnowledgeGraph, KnowledgeNode +from tea_kb.graph.timeline import ( + TimelineEvent, + events_for_concept, + major_concepts, + timeline_events, +) +from tea_kb.io.artifact_writer import Artifact + +SVG_DIR = Path("graph/generated/visualizations") +PALETTE = { + "bg": "#f8fafc", + "ink": "#172033", + "muted": "#64748b", + "line": "#cbd5e1", + "blue": "#2563eb", + "teal": "#0f766e", + "amber": "#b45309", + "rose": "#be123c", + "violet": "#6d28d9", + "green": "#15803d", +} + + +def svg_visualization_artifacts(graph: KnowledgeGraph) -> list[Artifact]: + artifacts = [ + visualization_index_artifact(graph), + repo_system_svg_artifact(graph), + research_support_svg_artifact(graph), + timeline_overview_svg_artifact(graph), + ] + artifacts.extend( + concept_timeline_svg_artifact(graph, concept) for concept, _ in major_concepts(graph) + ) + return artifacts + + +def visualization_index_artifact(graph: KnowledgeGraph) -> Artifact: + concept_lines = [ + f"- [{concept}](concept-timeline-{_concept_slug(concept)}.svg) - {count} node(s)" + for concept, count in major_concepts(graph) + ] + lines = [ + "# Generated Visualizations", + "", + "Generated by `uv run tea-kb build` from Markdown/frontmatter graph source.", + "", + "## README visuals", + "", + "- [Repository system](repo-system.svg)", + "- [Research support map](research-support.svg)", + "- [Knowledge base growth](timeline-overview.svg)", + "", + "## Diagnostic views", + "", + "- [Interactive graph overview](overview.html)", + "", + "## Major concept timelines", + "", + *(concept_lines or ["- None"]), + "", + ] + return Artifact(SVG_DIR / "README.md", "\n".join(lines)) + + +def repo_system_svg_artifact(graph: KnowledgeGraph) -> Artifact: + return Artifact(SVG_DIR / "repo-system.svg", render_repo_system_svg(graph)) + + +def research_support_svg_artifact(graph: KnowledgeGraph) -> Artifact: + return Artifact(SVG_DIR / "research-support.svg", render_research_support_svg(graph)) + + +def timeline_overview_svg_artifact(graph: KnowledgeGraph) -> Artifact: + return Artifact(SVG_DIR / "timeline-overview.svg", render_timeline_overview_svg(graph)) + + +def concept_timeline_svg_artifact(graph: KnowledgeGraph, concept: ConceptId) -> Artifact: + filename = f"concept-timeline-{_concept_slug(concept)}.svg" + return Artifact(SVG_DIR / filename, render_concept_timeline_svg(graph, concept)) + + +def render_repo_system_svg(graph: KnowledgeGraph) -> str: + type_counts = Counter(node.node_type.value for node in graph.nodes.values()) + cards = [ + _card( + 52, + 148, + 230, + 210, + "Markdown Source", + [ + f"{len(graph.nodes)} graph nodes", + f"{type_counts.get(NodeType.NOTE.value, 0)} notes", + f"{type_counts.get(NodeType.CONCEPT.value, 0)} concepts", + "frontmatter is canonical", + ], + PALETTE["teal"], + ), + _card( + 338, + 120, + 240, + 266, + "tea-kb Lifecycle", + [ + "parse frontmatter", + "validate contracts", + "build graph", + "report health", + "render visualizations", + ], + PALETTE["blue"], + ), + _card( + 634, + 148, + 230, + 210, + "Generated Brew", + [ + "nodes / edges / chunks", + "timeline events", + "Markdown reports", + "SVG + HTML views", + ], + PALETTE["amber"], + ), + _card( + 920, + 120, + 230, + 266, + "Consumers", + [ + "README visuals", + "GitHub Actions", + "human review", + "future search/RAG", + "agent context", + ], + PALETTE["rose"], + ), + ] + lines = [ + _svg_open(1200, 520, "How tea-style works"), + _title("How tea-style Works", "Markdown stays canonical. Tooling regenerates evidence."), + *cards, + _arrow(282, 252, 338, 252), + _arrow(578, 252, 634, 252), + _arrow(864, 252, 920, 252), + _loop_arrow(), + _text(600, 456, "CI enforces: validate -> tests -> build --check", 18, "600", "middle"), + "", + ] + return "\n".join(lines) + + +def render_research_support_svg(graph: KnowledgeGraph) -> str: + type_counts = Counter(node.node_type.value for node in graph.nodes.values()) + top_nodes = sorted( + graph.nodes.values(), + key=lambda node: ( + len(graph.inbound_edges(node.id)) + len(graph.outbound_edges(node.id)), + str(node.id), + ), + reverse=True, + )[:5] + top_concepts = major_concepts(graph, limit=5) + lines = [ + _svg_open(1200, 620, "Research and doctrine support map"), + _title( + "Research Support Map", + "Doctrine, standards, decisions, notes, and examples support each other as a graph.", + ), + _metric_card( + 58, 136, "Doctrines", type_counts.get(NodeType.DOCTRINE.value, 0), PALETTE["violet"] + ), + _metric_card( + 292, 136, "Standards", type_counts.get(NodeType.STANDARD.value, 0), PALETTE["blue"] + ), + _metric_card( + 526, 136, "Decisions", type_counts.get(NodeType.DECISION.value, 0), PALETTE["teal"] + ), + _metric_card(760, 136, "Notes", type_counts.get(NodeType.NOTE.value, 0), PALETTE["green"]), + _metric_card( + 994, 136, "Examples", type_counts.get(NodeType.EXAMPLE.value, 0), PALETTE["amber"] + ), + _text(58, 292, "Highest-degree doctrine nodes", 20, "700", "start"), + _text(658, 292, "Major concepts in use", 20, "700", "start"), + *_ranked_rows(58, 318, top_nodes), + *_concept_rows(658, 318, top_concepts), + _text( + 600, + 570, + f"{len(graph.edges)} semantic edges connect research into reviewable paths.", + 18, + "600", + "middle", + ), + "", + ] + return "\n".join(lines) + + +def render_timeline_overview_svg(graph: KnowledgeGraph) -> str: + events = timeline_events(graph) + by_date: defaultdict[str, list[str]] = defaultdict(list) + by_type = Counter(event.node_type.value for event in events) + for event in events: + by_date[event.date.isoformat()].append(event.event_type) + + dates = sorted(by_date) + points = _timeline_points(dates, 120, 1080) + lines = [ + _svg_open(1200, 520, "Knowledge base growth timeline"), + _title( + "Knowledge Base Growth", + "Generated from `created` and `updated` frontmatter dates.", + ), + f"", + ] + if not events: + lines.append(_text(600, 260, "No dated graph nodes yet.", 22, "700", "middle")) + for date_value in dates: + x = points[date_value] + events_for_date = by_date[date_value] + created = events_for_date.count("created") + updated = events_for_date.count("updated") + total = len(events_for_date) + radius = min(42, 14 + total * 2) + lines.extend( + [ + f"", + _text(x, 252, str(total), 18, "800", "middle", "#ffffff"), + _text(x, 188, date_value, 16, "700", "middle"), + _text(x, 310, f"{created} created / {updated} updated", 14, "600", "middle"), + ] + ) + lines.extend( + [ + _text(84, 396, "Event mix", 18, "700", "start"), + *_type_badges(84, 418, by_type), + _text( + 600, + 476, + f"{len(events)} timeline event(s) across {len(dates)} date(s).", + 18, + "600", + "middle", + ), + "", + ] + ) + return "\n".join(lines) + + +def render_concept_timeline_svg(graph: KnowledgeGraph, concept: ConceptId) -> str: + events = events_for_concept(timeline_events(graph), concept) + shown = events[:18] + height = max(320, 164 + len(shown) * 74) + lines = [ + _svg_open(1200, height, f"Timeline for {concept}"), + _title( + f"Concept Timeline: {concept}", + f"{len(events)} dated event(s) associated with this concept.", + ), + ( + f"" + ), + ] + if not shown: + lines.append(_text(600, 220, "No dated events for this concept.", 20, "700", "middle")) + for index, event in enumerate(shown): + y = 142 + index * 74 + color = PALETTE["green"] if event.event_type == "created" else PALETTE["amber"] + lines.extend( + [ + f"", + _text(126, y + 5, event.date.isoformat(), 14, "700", "end"), + _event_card(204, y - 28, event, color), + ] + ) + if len(events) > len(shown): + lines.append( + _text( + 600, + height - 34, + f"Showing {len(shown)} of {len(events)} events. See timeline.jsonl.", + 15, + "600", + "middle", + ) + ) + lines.append("") + return "\n".join(lines) + + +def _svg_open(width: int, height: int, label: str) -> str: + return "\n".join( + [ + ( + '' + ), + "", + ( + ' ' + ), + f' ', + " ", + ' ', + ( + ' ' + ), + " ", + "", + f'', + ] + ) + + +def _title(title: str, subtitle: str) -> str: + return "\n".join( + [ + _text(52, 62, title, 30, "800", "start"), + _text(52, 96, subtitle, 16, "500", "start", PALETTE["muted"]), + ] + ) + + +def _card(x: int, y: int, width: int, height: int, title: str, lines: list[str], color: str) -> str: + body = [ + ( + f"" + ), + f"", + _text(x + 20, y + 46, title, 19, "800", "start"), + ] + body.extend( + _text(x + 20, y + 80 + index * 28, line, 15, "600", "start", PALETTE["muted"]) + for index, line in enumerate(lines) + ) + return "\n".join(body) + + +def _metric_card(x: int, y: int, label: str, value: int, color: str) -> str: + return "\n".join( + [ + ( + f"" + ), + _text(x + 24, y + 38, label, 16, "700", "start", PALETTE["muted"]), + _text(x + 24, y + 76, str(value), 34, "800", "start", color), + ] + ) + + +def _ranked_rows(x: int, y: int, nodes: list[KnowledgeNode]) -> list[str]: + rows: list[str] = [] + for index, node in enumerate(nodes): + node_id = str(node.id) + title = str(node.title) + path = node.path + row_y = y + index * 44 + rows.extend( + [ + f"", + ( + f"" + ), + _text(x + 14, row_y + 22, _truncate(title, 46), 14, "700", "start"), + _text( + x + 376, + row_y + 22, + _truncate(node_id, 34), + 12, + "600", + "start", + PALETTE["muted"], + ), + "", + ] + ) + return rows + + +def _concept_rows(x: int, y: int, concepts: tuple[tuple[ConceptId, int], ...]) -> list[str]: + rows: list[str] = [] + for index, (concept, count) in enumerate(concepts): + row_y = y + index * 44 + width = min(420, 110 + count * 18) + fill_width = min(width, 64 + count * 14) + rows.extend( + [ + ( + f"" + ), + ( + f"" + ), + _text(x + 14, row_y + 22, str(concept), 14, "700", "start"), + _text( + x + width - 16, + row_y + 22, + str(count), + 14, + "800", + "end", + PALETTE["blue"], + ), + ] + ) + return rows + + +def _event_card(x: int, y: int, event: TimelineEvent, color: str) -> str: + title = _truncate(str(event.title), 72) + node_id = _truncate(str(event.node_id), 62) + node_type = event.node_type.value + path = event.path + event_type = str(event.event_type) + return "\n".join( + [ + f"", + ( + f"" + ), + ( + f"" + ), + _text(x + 59, y + 33, event_type, 12, "800", "middle", color), + _text(x + 118, y + 23, title, 15, "800", "start"), + _text( + x + 118, + y + 43, + f"{node_type} - {node_id}", + 12, + "600", + "start", + PALETTE["muted"], + ), + "", + ] + ) + + +def _type_badges(x: int, y: int, counts: Counter[str]) -> list[str]: + colors = [ + PALETTE["blue"], + PALETTE["teal"], + PALETTE["amber"], + PALETTE["rose"], + PALETTE["violet"], + ] + rows: list[str] = [] + cursor = x + for index, (label, count) in enumerate(sorted(counts.items())): + color = colors[index % len(colors)] + width = 128 + len(label) * 7 + rows.extend( + [ + ( + f"" + ), + _text(cursor + 18, y + 24, f"{label}: {count}", 14, "800", "start", color), + ] + ) + cursor += width + 14 + return rows + + +def _timeline_points(dates: list[str], start: int, end: int) -> dict[str, int]: + if not dates: + return {} + if len(dates) == 1: + return {dates[0]: (start + end) // 2} + step = (end - start) / (len(dates) - 1) + return {date_value: round(start + index * step) for index, date_value in enumerate(dates)} + + +def _arrow(x1: int, y1: int, x2: int, y2: int) -> str: + return ( + f"" + ) + + +def _loop_arrow() -> str: + return ( + "" + ) + + +def _text( + x: int, + y: int, + value: str, + size: int, + weight: str, + anchor: str, + fill: str | None = None, +) -> str: + color = fill or PALETTE["ink"] + return ( + f"{escape(value)}" + ) + + +def _truncate(value: str, limit: int) -> str: + if len(value) <= limit: + return value + return value[: limit - 3] + "..." + + +def _concept_slug(concept: ConceptId) -> str: + return slugify(str(concept).removeprefix("concept:")) diff --git a/tests/fixtures/valid_note.md b/tests/fixtures/valid_note.md index 21e08e9..4dddaa7 100644 --- a/tests/fixtures/valid_note.md +++ b/tests/fixtures/valid_note.md @@ -4,6 +4,8 @@ title: Valid Note type: note domain: test status: active +created: 2026-06-07 +updated: 2026-06-07 summary: > A valid test note. concepts: diff --git a/tests/integration/test_graph_lifecycle.py b/tests/integration/test_graph_lifecycle.py index e0bdf06..e1fea4d 100644 --- a/tests/integration/test_graph_lifecycle.py +++ b/tests/integration/test_graph_lifecycle.py @@ -15,6 +15,8 @@ def test_build_and_validate_fixture_graph(tmp_path: Path) -> None: type: concept domain: test status: active +created: 2026-06-07 +updated: 2026-06-07 concepts: - evidence edges: {} @@ -54,6 +56,8 @@ def test_jsonl_export_is_stable(tmp_path: Path) -> None: type: concept domain: test status: active +created: 2026-06-07 +updated: 2026-06-07 concepts: - evidence edges: {} @@ -75,3 +79,5 @@ def test_jsonl_export_is_stable(tmp_path: Path) -> None: assert artifacts[0].path.as_posix() == "graph/generated/nodes.jsonl" assert '"id": "concept:evidence"' in artifacts[0].content + assert artifacts[-1].path.as_posix() == "graph/generated/timeline.jsonl" + assert '"event_type": "created"' in artifacts[-1].content diff --git a/tests/unit/test_frontmatter.py b/tests/unit/test_frontmatter.py index f4bea2d..cc8cf6d 100644 --- a/tests/unit/test_frontmatter.py +++ b/tests/unit/test_frontmatter.py @@ -1,3 +1,4 @@ +from datetime import date from pathlib import Path import pytest @@ -12,6 +13,8 @@ def test_parse_valid_frontmatter() -> None: assert parsed.metadata.id == "note:test:valid-note" assert parsed.metadata.type == "note" + assert parsed.metadata.created == date(2026, 6, 7) + assert parsed.metadata.updated == date(2026, 6, 7) assert parsed.metadata.edges
IDTypeDomainSource