arscontexta 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (418) hide show
  1. package/.claude-plugin/marketplace.json +11 -0
  2. package/.claude-plugin/plugin.json +22 -0
  3. package/README.md +683 -0
  4. package/agents/knowledge-guide.md +49 -0
  5. package/bin/cli.mjs +66 -0
  6. package/generators/agents-md.md +240 -0
  7. package/generators/claude-md.md +379 -0
  8. package/generators/features/atomic-notes.md +124 -0
  9. package/generators/features/ethical-guardrails.md +58 -0
  10. package/generators/features/graph-analysis.md +188 -0
  11. package/generators/features/helper-functions.md +92 -0
  12. package/generators/features/maintenance.md +164 -0
  13. package/generators/features/methodology-knowledge.md +70 -0
  14. package/generators/features/mocs.md +144 -0
  15. package/generators/features/multi-domain.md +61 -0
  16. package/generators/features/personality.md +71 -0
  17. package/generators/features/processing-pipeline.md +428 -0
  18. package/generators/features/schema.md +149 -0
  19. package/generators/features/self-evolution.md +229 -0
  20. package/generators/features/self-space.md +78 -0
  21. package/generators/features/semantic-search.md +99 -0
  22. package/generators/features/session-rhythm.md +85 -0
  23. package/generators/features/templates.md +85 -0
  24. package/generators/features/wiki-links.md +88 -0
  25. package/generators/soul-md.md +121 -0
  26. package/hooks/hooks.json +45 -0
  27. package/hooks/scripts/auto-commit.sh +44 -0
  28. package/hooks/scripts/session-capture.sh +35 -0
  29. package/hooks/scripts/session-orient.sh +86 -0
  30. package/hooks/scripts/write-validate.sh +42 -0
  31. package/methodology/AI shifts knowledge systems from externalizing memory to externalizing attention.md +59 -0
  32. package/methodology/BM25 retrieval fails on full-length descriptions because query term dilution reduces match scores.md +39 -0
  33. package/methodology/IBIS framework maps claim-based architecture to structured argumentation.md +58 -0
  34. package/methodology/LLM attention degrades as context fills.md +49 -0
  35. package/methodology/MOC construction forces synthesis that automated generation from metadata cannot replicate.md +49 -0
  36. package/methodology/MOC maintenance investment compounds because orientation savings multiply across every future session.md +41 -0
  37. package/methodology/MOCs are attention management devices not just organizational tools.md +51 -0
  38. package/methodology/PKM failure follows a predictable cycle.md +50 -0
  39. package/methodology/ThreadMode to DocumentMode transformation is the core value creation step.md +52 -0
  40. package/methodology/WIP limits force processing over accumulation.md +53 -0
  41. package/methodology/Zeigarnik effect validates capture-first philosophy because open loops drain attention.md +42 -0
  42. package/methodology/academic research uses structured extraction with cross-source synthesis.md +566 -0
  43. package/methodology/adapt the four-phase processing pipeline to domain-specific throughput needs.md +197 -0
  44. package/methodology/agent notes externalize navigation intuition that search cannot discover and traversal cannot reconstruct.md +48 -0
  45. package/methodology/agent self-memory should be architecturally separate from user knowledge systems.md +48 -0
  46. package/methodology/agent session boundaries create natural automation checkpoints that human-operated systems lack.md +56 -0
  47. package/methodology/agent-cognition.md +107 -0
  48. package/methodology/agents are simultaneously methodology executors and subjects creating a unique trust asymmetry.md +66 -0
  49. package/methodology/aspect-oriented programming solved the same cross-cutting concern problem that hooks solve.md +39 -0
  50. package/methodology/associative ontologies beat hierarchical taxonomies because heterarchy adapts while hierarchy brittles.md +53 -0
  51. package/methodology/attention residue may have a minimum granularity that cannot be subdivided.md +46 -0
  52. package/methodology/auto-commit hooks eliminate prospective memory failures by converting remember-to-act into guaranteed execution.md +47 -0
  53. package/methodology/automated detection is always safe because it only reads state while automated remediation risks content corruption.md +42 -0
  54. package/methodology/automation should be retired when its false positive rate exceeds its true positive rate or it catches zero issues.md +56 -0
  55. package/methodology/backlinks implicitly define notes by revealing usage context.md +35 -0
  56. package/methodology/backward maintenance asks what would be different if written today.md +62 -0
  57. package/methodology/balance onboarding enforcement and questions to prevent premature complexity.md +229 -0
  58. package/methodology/basic level categorization determines optimal MOC granularity.md +51 -0
  59. package/methodology/batching by context similarity reduces switching costs in agent processing.md +43 -0
  60. package/methodology/behavioral anti-patterns matter more than tool selection.md +42 -0
  61. package/methodology/betweenness centrality identifies bridge notes connecting disparate knowledge domains.md +57 -0
  62. package/methodology/blueprints that teach construction outperform downloads that provide pre-built code for platform-dependent modules.md +42 -0
  63. package/methodology/bootstrapping principle enables self-improving systems.md +62 -0
  64. package/methodology/build automatic memory through cognitive offloading and session handoffs.md +285 -0
  65. package/methodology/capture the reaction to content not just the content itself.md +41 -0
  66. package/methodology/claims must be specific enough to be wrong.md +36 -0
  67. package/methodology/closure rituals create clean breaks that prevent attention residue bleed.md +44 -0
  68. package/methodology/cognitive offloading is the architectural foundation for vault design.md +46 -0
  69. package/methodology/cognitive outsourcing risk in agent-operated systems.md +55 -0
  70. package/methodology/coherence maintains consistency despite inconsistent inputs.md +96 -0
  71. package/methodology/coherent architecture emerges from wiki links spreading activation and small-world topology.md +48 -0
  72. package/methodology/community detection algorithms can inform when MOCs should split or merge.md +52 -0
  73. package/methodology/complete navigation requires four complementary types that no single mechanism provides.md +43 -0
  74. package/methodology/complex systems evolve from simple working systems.md +59 -0
  75. package/methodology/composable knowledge architecture builds systems from independent toggleable modules not monolithic templates.md +61 -0
  76. package/methodology/compose multi-domain systems through separate templates and shared graph.md +372 -0
  77. package/methodology/concept-orientation beats source-orientation for cross-domain connections.md +51 -0
  78. package/methodology/confidence thresholds gate automated action between the mechanical and judgment zones.md +50 -0
  79. package/methodology/configuration dimensions interact so choices in one create pressure on others.md +58 -0
  80. package/methodology/configuration paralysis emerges when derivation surfaces too many decisions.md +44 -0
  81. package/methodology/context files function as agent operating systems through self-referential self-extension.md +46 -0
  82. package/methodology/context phrase clarity determines how deep a navigation hierarchy can scale.md +46 -0
  83. package/methodology/continuous small-batch processing eliminates review dread.md +48 -0
  84. package/methodology/controlled disorder engineers serendipity through semantic rather than topical linking.md +51 -0
  85. package/methodology/creative writing uses worldbuilding consistency with character tracking.md +672 -0
  86. package/methodology/cross-links between MOC territories indicate creative leaps and integration depth.md +43 -0
  87. package/methodology/dangling links reveal which notes want to exist.md +62 -0
  88. package/methodology/data exit velocity measures how quickly content escapes vendor lock-in.md +74 -0
  89. package/methodology/decontextualization risk means atomicity may strip meaning that cannot be recovered.md +48 -0
  90. package/methodology/dense interlinked research claims enable derivation while sparse references only enable templating.md +47 -0
  91. package/methodology/dependency resolution through topological sort makes module composition transparent and verifiable.md +56 -0
  92. package/methodology/derivation generates knowledge systems from composable research claims not template customization.md +63 -0
  93. package/methodology/derivation-engine.md +27 -0
  94. package/methodology/derived systems follow a seed-evolve-reseed lifecycle.md +56 -0
  95. package/methodology/description quality for humans diverges from description quality for keyword search.md +73 -0
  96. package/methodology/descriptions are retrieval filters not summaries.md +112 -0
  97. package/methodology/design MOCs as attention management devices with lifecycle governance.md +318 -0
  98. package/methodology/design-dimensions.md +66 -0
  99. package/methodology/digital mutability enables note evolution that physical permanence forbids.md +54 -0
  100. package/methodology/discovery-retrieval.md +48 -0
  101. package/methodology/distinctiveness scoring treats description quality as measurable.md +69 -0
  102. package/methodology/does agent processing recover what fast capture loses.md +43 -0
  103. package/methodology/domain-compositions.md +37 -0
  104. package/methodology/dual-coding with visual elements could enhance agent traversal.md +55 -0
  105. package/methodology/each module must be describable in one sentence under 200 characters or it does too many things.md +45 -0
  106. package/methodology/each new note compounds value by creating traversal paths.md +55 -0
  107. package/methodology/eight configuration dimensions parameterize the space of possible knowledge systems.md +56 -0
  108. package/methodology/elaborative encoding is the quality gate for new notes.md +55 -0
  109. package/methodology/enforce schema with graduated strictness across capture processing and query zones.md +221 -0
  110. package/methodology/enforcing atomicity can create paralysis when ideas resist decomposition.md +43 -0
  111. package/methodology/engineering uses technical decision tracking with architectural memory.md +766 -0
  112. package/methodology/every knowledge domain shares a four-phase processing skeleton that diverges only in the process step.md +53 -0
  113. package/methodology/evolution observations provide actionable signals for system adaptation.md +67 -0
  114. package/methodology/external memory shapes cognition more than base model.md +60 -0
  115. package/methodology/faceted classification treats notes as multi-dimensional objects rather than folder contents.md +65 -0
  116. package/methodology/failure-modes.md +27 -0
  117. package/methodology/false universalism applies same processing logic regardless of domain.md +49 -0
  118. package/methodology/federated wiki pattern enables multi-agent divergence as feature not bug.md +59 -0
  119. package/methodology/flat files break at retrieval scale.md +75 -0
  120. package/methodology/forced engagement produces weak connections.md +48 -0
  121. package/methodology/four abstraction layers separate platform-agnostic from platform-dependent knowledge system features.md +47 -0
  122. package/methodology/fresh context per task preserves quality better than chaining phases.md +44 -0
  123. package/methodology/friction reveals architecture.md +63 -0
  124. package/methodology/friction-driven module adoption prevents configuration debt by adding complexity only at pain points.md +48 -0
  125. package/methodology/gardening cycle implements tend prune fertilize operations.md +41 -0
  126. package/methodology/generation effect gate blocks processing without transformation.md +40 -0
  127. package/methodology/goal-driven memory orchestration enables autonomous domain learning through directed compute allocation.md +41 -0
  128. package/methodology/good descriptions layer heuristic then mechanism then implication.md +57 -0
  129. package/methodology/graph-structure.md +65 -0
  130. package/methodology/guided notes might outperform post-hoc structuring for high-volume capture.md +37 -0
  131. package/methodology/health wellness uses symptom-trigger correlation with multi-dimensional tracking.md +819 -0
  132. package/methodology/hook composition creates emergent methodology from independent single-concern components.md +47 -0
  133. package/methodology/hook enforcement guarantees quality while instruction enforcement merely suggests it.md +51 -0
  134. package/methodology/hook-driven learning loops create self-improving methodology through observation accumulation.md +62 -0
  135. package/methodology/hooks are the agent habit system that replaces the missing basal ganglia.md +40 -0
  136. package/methodology/hooks cannot replace genuine cognitive engagement yet more automation is always tempting.md +87 -0
  137. package/methodology/hooks enable context window efficiency by delegating deterministic checks to external processes.md +47 -0
  138. package/methodology/idempotent maintenance operations are safe to automate because running them twice produces the same result as running them once.md +44 -0
  139. package/methodology/implement condition-based maintenance triggers for derived systems.md +255 -0
  140. package/methodology/implicit dependencies create distributed monoliths that fail silently across configurations.md +58 -0
  141. package/methodology/implicit knowledge emerges from traversal.md +55 -0
  142. package/methodology/incremental formalization happens through repeated touching of old notes.md +60 -0
  143. package/methodology/incremental reading enables cross-source connection finding.md +39 -0
  144. package/methodology/index.md +32 -0
  145. package/methodology/inline links carry richer relationship data than metadata fields.md +91 -0
  146. package/methodology/insight accretion differs from productivity in knowledge systems.md +41 -0
  147. package/methodology/intermediate packets enable assembly over creation.md +52 -0
  148. package/methodology/intermediate representation pattern enables reliable vault operations beyond regex.md +62 -0
  149. package/methodology/justification chains enable forward backward and evolution reasoning about configuration decisions.md +46 -0
  150. package/methodology/knowledge system architecture is parameterized by platform capabilities not fixed by methodology.md +51 -0
  151. package/methodology/knowledge systems become communication partners through complexity and memory humans cannot sustain.md +47 -0
  152. package/methodology/knowledge systems share universal operations and structural components across all methodology traditions.md +46 -0
  153. package/methodology/legal case management uses precedent chains with regulatory change propagation.md +892 -0
  154. package/methodology/live index via periodic regeneration keeps discovery current.md +58 -0
  155. package/methodology/local-first file formats are inherently agent-native.md +69 -0
  156. package/methodology/logic column pattern separates reasoning from procedure.md +35 -0
  157. package/methodology/maintenance operations are more universal than creative pipelines because structural health is domain-invariant.md +47 -0
  158. package/methodology/maintenance scheduling frequency should match consequence speed not detection capability.md +50 -0
  159. package/methodology/maintenance targeting should prioritize mechanism and theory notes.md +26 -0
  160. package/methodology/maintenance-patterns.md +72 -0
  161. package/methodology/markdown plus YAML plus ripgrep implements a queryable graph database without infrastructure.md +55 -0
  162. package/methodology/maturity field enables agent context prioritization.md +33 -0
  163. package/methodology/memory-architecture.md +27 -0
  164. package/methodology/metacognitive confidence can diverge from retrieval capability.md +42 -0
  165. package/methodology/metadata reduces entropy enabling precision over recall.md +91 -0
  166. package/methodology/methodology development should follow the trajectory from documentation to skill to hook as understanding hardens.md +80 -0
  167. package/methodology/methodology traditions are named points in a shared configuration space not competing paradigms.md +64 -0
  168. package/methodology/mnemonic medium embeds verification into navigation.md +46 -0
  169. package/methodology/module communication through shared YAML fields creates loose coupling without direct dependencies.md +44 -0
  170. package/methodology/module deactivation must account for structural artifacts that survive the toggle.md +49 -0
  171. package/methodology/multi-domain systems compose through separate templates and shared graph.md +61 -0
  172. package/methodology/multi-domain-composition.md +27 -0
  173. package/methodology/narrow folksonomy optimizes for single-operator retrieval unlike broad consensus tagging.md +53 -0
  174. package/methodology/navigation infrastructure passes through distinct scaling regimes that require qualitative strategy shifts.md +48 -0
  175. package/methodology/navigational vertigo emerges in pure association systems without local hierarchy.md +54 -0
  176. package/methodology/note titles should function as APIs enabling sentence transclusion.md +51 -0
  177. package/methodology/note-design.md +57 -0
  178. package/methodology/notes are skills /342/200/224 curated knowledge injected when relevant.md" +62 -0
  179. package/methodology/notes function as cognitive anchors that stabilize attention during complex tasks.md +41 -0
  180. package/methodology/novel domains derive by mapping knowledge type to closest reference domain then adapting.md +50 -0
  181. package/methodology/nudge theory explains graduated hook enforcement as choice architecture for agents.md +59 -0
  182. package/methodology/observation and tension logs function as dead-letter queues for failed automation.md +51 -0
  183. package/methodology/operational memory and knowledge memory serve different functions in agent architecture.md +48 -0
  184. package/methodology/operational wisdom requires contextual observation.md +52 -0
  185. package/methodology/orchestrated vault creation transforms arscontexta from tool to autonomous knowledge factory.md +40 -0
  186. package/methodology/organic emergence versus active curation creates a fundamental vault governance tension.md +68 -0
  187. package/methodology/orphan notes are seeds not failures.md +38 -0
  188. package/methodology/over-automation corrupts quality when hooks encode judgment rather than verification.md +62 -0
  189. package/methodology/people relationships uses Dunbar-layered graphs with interaction tracking.md +659 -0
  190. package/methodology/personal assistant uses life area management with review automation.md +610 -0
  191. package/methodology/platform adapter translation is semantic not mechanical because hook event meanings differ.md +40 -0
  192. package/methodology/platform capability tiers determine which knowledge system features can be implemented.md +48 -0
  193. package/methodology/platform fragmentation means identical conceptual operations require different implementations across agent environments.md +44 -0
  194. package/methodology/premature complexity is the most common derivation failure mode.md +45 -0
  195. package/methodology/prevent domain-specific failure modes through the vulnerability matrix.md +336 -0
  196. package/methodology/processing effort should follow retrieval demand.md +57 -0
  197. package/methodology/processing-workflows.md +75 -0
  198. package/methodology/product management uses feedback pipelines with experiment tracking.md +789 -0
  199. package/methodology/productivity porn risk in meta-system building.md +30 -0
  200. package/methodology/programmable notes could enable property-triggered workflows.md +64 -0
  201. package/methodology/progressive disclosure means reading right not reading less.md +69 -0
  202. package/methodology/progressive schema validates only what active modules require not the full system schema.md +49 -0
  203. package/methodology/project management uses decision tracking with stakeholder context.md +776 -0
  204. package/methodology/propositional link semantics transform wiki links from associative to reasoned.md +87 -0
  205. package/methodology/prospective memory requires externalization.md +53 -0
  206. package/methodology/provenance tracks where beliefs come from.md +62 -0
  207. package/methodology/queries evolve during search so agents should checkpoint.md +35 -0
  208. package/methodology/question-answer metadata enables inverted search patterns.md +39 -0
  209. package/methodology/random note resurfacing prevents write-only memory.md +33 -0
  210. package/methodology/reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring.md +59 -0
  211. package/methodology/reflection synthesizes existing notes into new insight.md +100 -0
  212. package/methodology/retrieval utility should drive design over capture completeness.md +69 -0
  213. package/methodology/retrieval verification loop tests description quality at scale.md +81 -0
  214. package/methodology/role field makes graph structure explicit.md +94 -0
  215. package/methodology/scaffolding enables divergence that fine-tuning cannot.md +67 -0
  216. package/methodology/schema enforcement via validation agents enables soft consistency.md +60 -0
  217. package/methodology/schema evolution follows observe-then-formalize not design-then-enforce.md +65 -0
  218. package/methodology/schema field names are the only domain specific element in the universal note pattern.md +46 -0
  219. package/methodology/schema fields should use domain-native vocabulary not abstract terminology.md +47 -0
  220. package/methodology/schema templates reduce cognitive overhead at capture time.md +55 -0
  221. package/methodology/schema validation hooks externalize inhibitory control that degrades under cognitive load.md +48 -0
  222. package/methodology/schema-enforcement.md +27 -0
  223. package/methodology/self-extension requires context files to contain platform operations knowledge not just methodology.md +47 -0
  224. package/methodology/sense-making vs storage does compression lose essential nuance.md +73 -0
  225. package/methodology/session boundary hooks implement cognitive bookends for orientation and reflection.md +60 -0
  226. package/methodology/session handoff creates continuity without persistent memory.md +43 -0
  227. package/methodology/session outputs are packets for future selves.md +43 -0
  228. package/methodology/session transcript mining enables experiential validation that structural tests cannot provide.md +38 -0
  229. package/methodology/skill context budgets constrain knowledge system complexity on agent platforms.md +52 -0
  230. package/methodology/skills encode methodology so manual execution bypasses quality gates.md +50 -0
  231. package/methodology/small-world topology requires hubs and dense local links.md +99 -0
  232. package/methodology/source attribution enables tracing claims to foundations.md +38 -0
  233. package/methodology/spaced repetition scheduling could optimize vault maintenance.md +44 -0
  234. package/methodology/spreading activation models how agents should traverse.md +79 -0
  235. package/methodology/stale navigation actively misleads because agents trust curated maps completely.md +43 -0
  236. package/methodology/stigmergy coordinates agents through environmental traces without direct communication.md +62 -0
  237. package/methodology/storage versus thinking distinction determines which tool patterns apply.md +56 -0
  238. package/methodology/structure enables navigation without reading everything.md +52 -0
  239. package/methodology/structure without processing provides no value.md +56 -0
  240. package/methodology/student learning uses prerequisite graphs with spaced retrieval.md +770 -0
  241. package/methodology/summary coherence tests composability before filing.md +37 -0
  242. package/methodology/tag rot applies to wiki links because titles serve as both identifier and display text.md +50 -0
  243. package/methodology/temporal media must convert to spatial text for agent traversal.md +43 -0
  244. package/methodology/temporal processing priority creates age-based inbox urgency.md +45 -0
  245. package/methodology/temporal separation of capture and processing preserves context freshness.md +39 -0
  246. package/methodology/ten universal primitives form the kernel of every viable agent knowledge system.md +162 -0
  247. package/methodology/testing effect could enable agent knowledge verification.md +38 -0
  248. package/methodology/the AgentSkills standard embodies progressive disclosure at the skill level.md +40 -0
  249. package/methodology/the derivation engine improves recursively as deployed systems generate observations.md +49 -0
  250. package/methodology/the determinism boundary separates hook methodology from skill methodology.md +46 -0
  251. package/methodology/the fix-versus-report decision depends on determinism reversibility and accumulated trust.md +45 -0
  252. package/methodology/the generation effect requires active transformation not just storage.md +57 -0
  253. package/methodology/the no wrong patches guarantee ensures any valid module combination produces a valid system.md +58 -0
  254. package/methodology/the system is the argument.md +46 -0
  255. package/methodology/the vault constitutes identity for agents.md +86 -0
  256. package/methodology/the vault methodology transfers because it encodes cognitive science not domain specifics.md +47 -0
  257. package/methodology/therapy journal uses warm personality with pattern detection for emotional processing.md +584 -0
  258. package/methodology/three capture schools converge through agent-mediated synthesis.md +55 -0
  259. package/methodology/three concurrent maintenance loops operate at different timescales to catch different classes of problems.md +56 -0
  260. package/methodology/throughput matters more than accumulation.md +58 -0
  261. package/methodology/title as claim enables traversal as reasoning.md +50 -0
  262. package/methodology/topological organization beats temporal for knowledge work.md +52 -0
  263. package/methodology/trading uses conviction tracking with thesis-outcome correlation.md +699 -0
  264. package/methodology/trails transform ephemeral navigation into persistent artifacts.md +39 -0
  265. package/methodology/transform universal vocabulary to domain-native language through six levels.md +259 -0
  266. package/methodology/type field enables structured queries without folder hierarchies.md +53 -0
  267. package/methodology/use-case presets dissolve the tension between composability and simplicity.md +44 -0
  268. package/methodology/vault conventions may impose hidden rigidity on thinking.md +44 -0
  269. package/methodology/verbatim risk applies to agents too.md +31 -0
  270. package/methodology/vibe notetaking is the emerging industry consensus for AI-native self-organization.md +56 -0
  271. package/methodology/vivid memories need verification.md +45 -0
  272. package/methodology/vocabulary-transformation.md +27 -0
  273. package/methodology/voice capture is the highest-bandwidth channel for agent-delegated knowledge systems.md +45 -0
  274. package/methodology/wiki links are the digital evolution of analog indexing.md +73 -0
  275. package/methodology/wiki links as social contract transforms agents into stewards of incomplete references.md +52 -0
  276. package/methodology/wiki links create navigation paths that shape retrieval.md +63 -0
  277. package/methodology/wiki links implement GraphRAG without the infrastructure.md +101 -0
  278. package/methodology/writing for audience blocks authentic creation.md +22 -0
  279. package/methodology/you operate a system that takes notes.md +79 -0
  280. package/openclaw/SKILL.md +110 -0
  281. package/package.json +45 -0
  282. package/platforms/README.md +51 -0
  283. package/platforms/claude-code/generator.md +61 -0
  284. package/platforms/claude-code/hooks/README.md +186 -0
  285. package/platforms/claude-code/hooks/auto-commit.sh.template +38 -0
  286. package/platforms/claude-code/hooks/session-capture.sh.template +72 -0
  287. package/platforms/claude-code/hooks/session-orient.sh.template +189 -0
  288. package/platforms/claude-code/hooks/write-validate.sh.template +106 -0
  289. package/platforms/openclaw/generator.md +82 -0
  290. package/platforms/openclaw/hooks/README.md +89 -0
  291. package/platforms/openclaw/hooks/bootstrap.ts.template +224 -0
  292. package/platforms/openclaw/hooks/command-new.ts.template +165 -0
  293. package/platforms/openclaw/hooks/heartbeat.ts.template +214 -0
  294. package/platforms/shared/features/README.md +70 -0
  295. package/platforms/shared/skill-blocks/graph.md +145 -0
  296. package/platforms/shared/skill-blocks/learn.md +119 -0
  297. package/platforms/shared/skill-blocks/next.md +131 -0
  298. package/platforms/shared/skill-blocks/pipeline.md +326 -0
  299. package/platforms/shared/skill-blocks/ralph.md +616 -0
  300. package/platforms/shared/skill-blocks/reduce.md +1142 -0
  301. package/platforms/shared/skill-blocks/refactor.md +129 -0
  302. package/platforms/shared/skill-blocks/reflect.md +780 -0
  303. package/platforms/shared/skill-blocks/remember.md +524 -0
  304. package/platforms/shared/skill-blocks/rethink.md +574 -0
  305. package/platforms/shared/skill-blocks/reweave.md +680 -0
  306. package/platforms/shared/skill-blocks/seed.md +320 -0
  307. package/platforms/shared/skill-blocks/stats.md +145 -0
  308. package/platforms/shared/skill-blocks/tasks.md +171 -0
  309. package/platforms/shared/skill-blocks/validate.md +323 -0
  310. package/platforms/shared/skill-blocks/verify.md +562 -0
  311. package/platforms/shared/templates/README.md +35 -0
  312. package/presets/experimental/categories.yaml +1 -0
  313. package/presets/experimental/preset.yaml +38 -0
  314. package/presets/experimental/starter/README.md +7 -0
  315. package/presets/experimental/vocabulary.yaml +7 -0
  316. package/presets/personal/categories.yaml +7 -0
  317. package/presets/personal/preset.yaml +41 -0
  318. package/presets/personal/starter/goals.md +21 -0
  319. package/presets/personal/starter/index.md +17 -0
  320. package/presets/personal/starter/life-areas.md +21 -0
  321. package/presets/personal/starter/people.md +21 -0
  322. package/presets/personal/vocabulary.yaml +32 -0
  323. package/presets/research/categories.yaml +8 -0
  324. package/presets/research/preset.yaml +41 -0
  325. package/presets/research/starter/index.md +17 -0
  326. package/presets/research/starter/methods.md +21 -0
  327. package/presets/research/starter/open-questions.md +21 -0
  328. package/presets/research/vocabulary.yaml +33 -0
  329. package/reference/AUDIT-REPORT.md +238 -0
  330. package/reference/claim-map.md +172 -0
  331. package/reference/components.md +327 -0
  332. package/reference/conversation-patterns.md +542 -0
  333. package/reference/derivation-validation.md +649 -0
  334. package/reference/dimension-claim-map.md +134 -0
  335. package/reference/evolution-lifecycle.md +297 -0
  336. package/reference/failure-modes.md +235 -0
  337. package/reference/interaction-constraints.md +204 -0
  338. package/reference/kernel.yaml +242 -0
  339. package/reference/methodology.md +283 -0
  340. package/reference/open-questions.md +279 -0
  341. package/reference/personality-layer.md +302 -0
  342. package/reference/self-space.md +299 -0
  343. package/reference/semantic-vs-keyword.md +288 -0
  344. package/reference/session-lifecycle.md +298 -0
  345. package/reference/templates/base-note.md +16 -0
  346. package/reference/templates/companion-note.md +70 -0
  347. package/reference/templates/creative-note.md +16 -0
  348. package/reference/templates/learning-note.md +16 -0
  349. package/reference/templates/life-note.md +16 -0
  350. package/reference/templates/moc.md +26 -0
  351. package/reference/templates/relationship-note.md +17 -0
  352. package/reference/templates/research-note.md +19 -0
  353. package/reference/templates/session-log.md +24 -0
  354. package/reference/templates/therapy-note.md +16 -0
  355. package/reference/test-fixtures/edge-case-constraints.md +148 -0
  356. package/reference/test-fixtures/multi-domain.md +164 -0
  357. package/reference/test-fixtures/novel-domain-gaming.md +138 -0
  358. package/reference/test-fixtures/research-minimal.md +102 -0
  359. package/reference/test-fixtures/therapy-full.md +155 -0
  360. package/reference/testing-milestones.md +1087 -0
  361. package/reference/three-spaces.md +363 -0
  362. package/reference/tradition-presets.md +203 -0
  363. package/reference/use-case-presets.md +341 -0
  364. package/reference/validate-kernel.sh +432 -0
  365. package/reference/vocabulary-transforms.md +85 -0
  366. package/scripts/sync-thinking.sh +147 -0
  367. package/skill-sources/graph/SKILL.md +567 -0
  368. package/skill-sources/graph/skill.json +17 -0
  369. package/skill-sources/learn/SKILL.md +254 -0
  370. package/skill-sources/learn/skill.json +17 -0
  371. package/skill-sources/next/SKILL.md +407 -0
  372. package/skill-sources/next/skill.json +17 -0
  373. package/skill-sources/pipeline/SKILL.md +314 -0
  374. package/skill-sources/pipeline/skill.json +17 -0
  375. package/skill-sources/ralph/SKILL.md +604 -0
  376. package/skill-sources/ralph/skill.json +17 -0
  377. package/skill-sources/reduce/SKILL.md +1113 -0
  378. package/skill-sources/reduce/skill.json +17 -0
  379. package/skill-sources/refactor/SKILL.md +448 -0
  380. package/skill-sources/refactor/skill.json +17 -0
  381. package/skill-sources/reflect/SKILL.md +747 -0
  382. package/skill-sources/reflect/skill.json +17 -0
  383. package/skill-sources/remember/SKILL.md +534 -0
  384. package/skill-sources/remember/skill.json +17 -0
  385. package/skill-sources/rethink/SKILL.md +658 -0
  386. package/skill-sources/rethink/skill.json +17 -0
  387. package/skill-sources/reweave/SKILL.md +657 -0
  388. package/skill-sources/reweave/skill.json +17 -0
  389. package/skill-sources/seed/SKILL.md +303 -0
  390. package/skill-sources/seed/skill.json +17 -0
  391. package/skill-sources/stats/SKILL.md +371 -0
  392. package/skill-sources/stats/skill.json +17 -0
  393. package/skill-sources/tasks/SKILL.md +402 -0
  394. package/skill-sources/tasks/skill.json +17 -0
  395. package/skill-sources/validate/SKILL.md +310 -0
  396. package/skill-sources/validate/skill.json +17 -0
  397. package/skill-sources/verify/SKILL.md +532 -0
  398. package/skill-sources/verify/skill.json +17 -0
  399. package/skills/add-domain/SKILL.md +441 -0
  400. package/skills/add-domain/skill.json +17 -0
  401. package/skills/architect/SKILL.md +568 -0
  402. package/skills/architect/skill.json +17 -0
  403. package/skills/ask/SKILL.md +388 -0
  404. package/skills/ask/skill.json +17 -0
  405. package/skills/health/SKILL.md +760 -0
  406. package/skills/health/skill.json +17 -0
  407. package/skills/help/SKILL.md +348 -0
  408. package/skills/help/skill.json +17 -0
  409. package/skills/recommend/SKILL.md +553 -0
  410. package/skills/recommend/skill.json +17 -0
  411. package/skills/reseed/SKILL.md +385 -0
  412. package/skills/reseed/skill.json +17 -0
  413. package/skills/setup/SKILL.md +1688 -0
  414. package/skills/setup/skill.json +17 -0
  415. package/skills/tutorial/SKILL.md +496 -0
  416. package/skills/tutorial/skill.json +17 -0
  417. package/skills/upgrade/SKILL.md +395 -0
  418. package/skills/upgrade/skill.json +17 -0
@@ -0,0 +1,224 @@
1
+ // Ars Contexta — Session Orientation Hook (OpenClaw)
2
+ // Event: agent:bootstrap
3
+ // Purpose: Load workspace context, identity, methodology, and maintenance
4
+ // signals when the bot starts a new session. Ensures the bot
5
+ // always knows what exists and can orient to current priorities.
6
+ //
7
+ // This is a TEMPLATE. During /init, {{VARIABLE}} markers are replaced
8
+ // with values from the derivation manifest.
9
+ //
10
+ // This hook is the OpenClaw equivalent of session-orient.sh (Claude Code).
11
+ // Key difference: OpenClaw loads context via file reads and inject(),
12
+ // not shell output capture.
13
+
14
+ import type { AgentContext } from "@openclaw/sdk";
15
+
16
+ export default async function bootstrap(context: AgentContext) {
17
+ const sections: string[] = [];
18
+
19
+ // ─────────────────────────────────────────────
20
+ // 1. Persistent Working Memory (goals)
21
+ // ─────────────────────────────────────────────
22
+ // Goals orient the bot to what matters before anything else.
23
+ // Check both self/ and ops/ locations for the goals file.
24
+
25
+ const goalsFromSelf = await context.readFile("self/goals.md").catch(() => null);
26
+ const goalsFromOps = await context.readFile("ops/goals.md").catch(() => null);
27
+ const goals = goalsFromSelf || goalsFromOps;
28
+
29
+ if (goals) {
30
+ sections.push("## Current Goals\n");
31
+ sections.push(goals);
32
+ sections.push("");
33
+ }
34
+
35
+ // ─────────────────────────────────────────────
36
+ // 2. Learned Behavioral Patterns (methodology)
37
+ // ─────────────────────────────────────────────
38
+ // Load the 5 most recent methodology notes (titles only).
39
+ // These are behavioral learnings from /remember that the
40
+ // bot should be aware of without reading full content.
41
+
42
+ const methFiles = await context
43
+ .listFiles("ops/methodology/", { pattern: "*.md", sortBy: "modified", limit: 5 })
44
+ .catch(() => []);
45
+
46
+ if (methFiles.length > 0) {
47
+ sections.push("## Recent Methodology Learnings\n");
48
+ for (const file of methFiles) {
49
+ const content = await context.readFile(file).catch(() => "");
50
+ const titleMatch = content.match(/^# (.+)$/m);
51
+ if (titleMatch) {
52
+ sections.push(`- ${titleMatch[1]}`);
53
+ }
54
+ }
55
+ sections.push("");
56
+ }
57
+
58
+ // ─────────────────────────────────────────────
59
+ // 3. Previous Session State (continuity)
60
+ // ─────────────────────────────────────────────
61
+ // If a previous session's state was captured, load it
62
+ // so the bot can resume where it left off.
63
+
64
+ const previousSession = await context
65
+ .readFile("ops/sessions/current.json")
66
+ .catch(() => null);
67
+
68
+ if (previousSession) {
69
+ sections.push("## Previous Session Context\n");
70
+ sections.push(previousSession);
71
+ sections.push("");
72
+ }
73
+
74
+ // ─────────────────────────────────────────────
75
+ // 4. Workspace Map (structural orientation)
76
+ // ─────────────────────────────────────────────
77
+ // Unlike Claude Code which generates a tree via shell,
78
+ // OpenClaw loads the pre-generated WORKSPACE-MAP.md file.
79
+ // This gives the bot a map of all files without reading any.
80
+
81
+ const workspaceMap = await context
82
+ .readFile("WORKSPACE-MAP.md")
83
+ .catch(() => null);
84
+
85
+ if (workspaceMap) {
86
+ sections.push("## Workspace Structure\n");
87
+ sections.push(workspaceMap);
88
+ sections.push("");
89
+ } else {
90
+ // Fallback: list markdown files if no workspace map exists
91
+ const allFiles = await context
92
+ .listFiles(".", { pattern: "*.md", recursive: true, maxDepth: 3 })
93
+ .catch(() => []);
94
+
95
+ if (allFiles.length > 0) {
96
+ sections.push("## Workspace Structure\n");
97
+ for (const file of allFiles) {
98
+ sections.push(` ${file}`);
99
+ }
100
+ sections.push("");
101
+ }
102
+ }
103
+
104
+ // ─────────────────────────────────────────────
105
+ // 5. Identity (self space — conditional)
106
+ // ─────────────────────────────────────────────
107
+ // {{IF_SELF_SPACE}}
108
+ // If self/ space is enabled, load identity and methodology
109
+ // so the bot remembers who it is across sessions.
110
+
111
+ const identity = await context.readFile("self/identity.md").catch(() => null);
112
+ if (identity) {
113
+ sections.push("## Identity\n");
114
+ sections.push(identity);
115
+ sections.push("");
116
+ }
117
+
118
+ const methodology = await context
119
+ .readFile("self/methodology.md")
120
+ .catch(() => null);
121
+ if (methodology) {
122
+ sections.push(methodology);
123
+ sections.push("");
124
+ }
125
+
126
+ // Also load the memory orientation file
127
+ const memory = await context
128
+ .readFile("self/MEMORY.md")
129
+ .catch(() => await context.readFile("self/README.md").catch(() => null));
130
+ if (memory) {
131
+ sections.push(memory);
132
+ sections.push("");
133
+ }
134
+ // {{END_IF_SELF_SPACE}}
135
+
136
+ // ─────────────────────────────────────────────
137
+ // 6. Condition-Based Maintenance Signals
138
+ // ─────────────────────────────────────────────
139
+ // Check vault state against thresholds. These are not
140
+ // time-based triggers but measurements of actual state.
141
+ // Fires only when a condition is violated.
142
+
143
+ const signals: string[] = [];
144
+
145
+ // Observation accumulation threshold (default: 10)
146
+ const obsFiles = await context
147
+ .listFiles("ops/observations/", { pattern: "*.md" })
148
+ .catch(() => []);
149
+ const obsCount = obsFiles.length;
150
+ if (obsCount >= {{OBS_THRESHOLD:-10}}) {
151
+ signals.push(
152
+ `CONDITION: ${obsCount} pending observations. Consider /{DOMAIN:rethink}.`
153
+ );
154
+ }
155
+
156
+ // Tension accumulation threshold (default: 5)
157
+ const tensionFiles = await context
158
+ .listFiles("ops/tensions/", { pattern: "*.md" })
159
+ .catch(() => []);
160
+ const tensionCount = tensionFiles.length;
161
+ if (tensionCount >= {{TENSION_THRESHOLD:-5}}) {
162
+ signals.push(
163
+ `CONDITION: ${tensionCount} unresolved tensions. Consider /{DOMAIN:rethink}.`
164
+ );
165
+ }
166
+
167
+ // Unprocessed sessions threshold (default: 5)
168
+ const sessionFiles = await context
169
+ .listFiles("ops/sessions/", { pattern: "*.json" })
170
+ .catch(() => []);
171
+ const sessCount = sessionFiles.filter(
172
+ (f: string) => !f.endsWith("current.json")
173
+ ).length;
174
+ if (sessCount >= 5) {
175
+ signals.push(
176
+ `CONDITION: ${sessCount} unprocessed sessions. Consider /remember --mine-sessions.`
177
+ );
178
+ }
179
+
180
+ // Inbox pressure (default: 3 items)
181
+ const inboxFiles = await context
182
+ .listFiles("{{INBOX_DIR:-inbox}}/", { pattern: "*.md" })
183
+ .catch(() => []);
184
+ const inboxCount = inboxFiles.length;
185
+ if (inboxCount >= 3) {
186
+ signals.push(
187
+ `CONDITION: ${inboxCount} items in {{INBOX_DIR:-inbox}}/. Consider /{DOMAIN:reduce} or /pipeline.`
188
+ );
189
+ }
190
+
191
+ // Tutorial resume check
192
+ const tutorialState = await context
193
+ .readFile("ops/tutorial-state.yaml")
194
+ .catch(() => null);
195
+ if (tutorialState) {
196
+ const stepMatch = tutorialState.match(/^current_step:\s*(\d+)/m);
197
+ if (stepMatch) {
198
+ const step = parseInt(stepMatch[1], 10);
199
+ if (step <= 5) {
200
+ signals.push(
201
+ `NOTE: Unfinished tutorial (step ${step} of 5). Resume with /tutorial.`
202
+ );
203
+ }
204
+ }
205
+ }
206
+
207
+ if (signals.length > 0) {
208
+ sections.push("## Maintenance Signals\n");
209
+ for (const signal of signals) {
210
+ sections.push(signal);
211
+ }
212
+ sections.push("");
213
+ }
214
+
215
+ // ─────────────────────────────────────────────
216
+ // 7. Inject all collected context
217
+ // ─────────────────────────────────────────────
218
+ // OpenClaw's inject() adds content to the bot's context
219
+ // at session start, equivalent to stdout in Claude Code hooks.
220
+
221
+ if (sections.length > 0) {
222
+ context.inject(sections.join("\n"));
223
+ }
224
+ }
@@ -0,0 +1,165 @@
1
+ // Ars Contexta — Capture Validation Hook (OpenClaw)
2
+ // Event: command:new
3
+ // Purpose: Validate and normalize incoming content through the messaging
4
+ // gateway. Ensures every capture has minimal schema compliance
5
+ // and proper routing before it enters the vault.
6
+ //
7
+ // This is a TEMPLATE. During /init, {{VARIABLE}} markers are replaced
8
+ // with values from the derivation manifest.
9
+ //
10
+ // This hook combines two Claude Code hooks into one:
11
+ // - write-validate.sh (schema enforcement)
12
+ // - auto-commit.sh (git persistence)
13
+ // OpenClaw's command:new fires on incoming messages, which is the
14
+ // natural capture boundary for the messaging platform.
15
+
16
+ import type { CommandContext, CommandContent } from "@openclaw/sdk";
17
+
18
+ export default async function onNewCommand(
19
+ content: CommandContent,
20
+ context: CommandContext
21
+ ) {
22
+ // ─────────────────────────────────────────────
23
+ // 1. Determine content type and routing
24
+ // ─────────────────────────────────────────────
25
+ // Route incoming content to the appropriate location.
26
+ // Quick captures go to inbox. Structured content with
27
+ // frontmatter may go directly to the knowledge space.
28
+
29
+ const text = content.text || "";
30
+ const hasYamlFrontmatter = text.trimStart().startsWith("---");
31
+ const timestamp = new Date().toISOString();
32
+ const datePrefix = timestamp.slice(0, 10);
33
+
34
+ // ─────────────────────────────────────────────
35
+ // 2. Timestamp injection
36
+ // ─────────────────────────────────────────────
37
+ // Add a created timestamp if not already present.
38
+ // This ensures every piece of content is temporally anchored.
39
+
40
+ let processed = text;
41
+
42
+ if (hasYamlFrontmatter) {
43
+ // Content has frontmatter — inject created field if missing
44
+ if (!text.match(/^created:/m)) {
45
+ processed = text.replace(
46
+ /^---\s*\n/,
47
+ `---\ncreated: ${datePrefix}\n`
48
+ );
49
+ }
50
+ } else {
51
+ // No frontmatter — wrap with minimal schema
52
+ processed = [
53
+ "---",
54
+ `description: captured from messaging on ${datePrefix}`,
55
+ `created: ${datePrefix}`,
56
+ "---",
57
+ "",
58
+ text,
59
+ ].join("\n");
60
+ }
61
+
62
+ // ─────────────────────────────────────────────
63
+ // 3. Generate filename
64
+ // ─────────────────────────────────────────────
65
+ // Use a date-prefixed descriptive filename.
66
+ // Extract first line as potential title, sanitize for filesystem.
67
+
68
+ const firstLine = text.split("\n").find((line: string) => line.trim().length > 0) || "capture";
69
+ const titleSlug = firstLine
70
+ .replace(/^#\s*/, "")
71
+ .replace(/[^a-zA-Z0-9\s-]/g, "")
72
+ .trim()
73
+ .toLowerCase()
74
+ .replace(/\s+/g, "-")
75
+ .slice(0, 60);
76
+
77
+ const filename = `${datePrefix}-${titleSlug}.md`;
78
+ const filepath = `{{INBOX_DIR:-inbox}}/${filename}`;
79
+
80
+ // ─────────────────────────────────────────────
81
+ // 4. Write to inbox
82
+ // ─────────────────────────────────────────────
83
+ // Content enters through inbox. Processing moves it
84
+ // to the knowledge space later via /reduce or /pipeline.
85
+
86
+ await context.writeFile(filepath, processed);
87
+
88
+ // ─────────────────────────────────────────────
89
+ // 5. Schema validation (knowledge space writes)
90
+ // ─────────────────────────────────────────────
91
+ // If this content targets the knowledge space directly
92
+ // (rare via messaging, but possible), validate schema.
93
+
94
+ const isKnowledgeNote =
95
+ filepath.startsWith("{{NOTES_DIR:-notes}}/") ||
96
+ filepath.includes("thinking/");
97
+
98
+ if (isKnowledgeNote) {
99
+ const warnings: string[] = [];
100
+
101
+ // Check YAML frontmatter existence
102
+ if (!processed.trimStart().startsWith("---")) {
103
+ warnings.push(
104
+ `SCHEMA WARN: Missing YAML frontmatter. Every {{DOMAIN:note}} needs frontmatter with at least description and topics.`
105
+ );
106
+ }
107
+
108
+ // Check required field: description
109
+ if (!processed.match(/^description:/m)) {
110
+ warnings.push(
111
+ `SCHEMA WARN: Missing 'description' field. Description enables filtering and progressive disclosure.`
112
+ );
113
+ }
114
+
115
+ // Check required field: topics
116
+ if (!processed.match(/^topics:/m)) {
117
+ warnings.push(
118
+ `SCHEMA WARN: Missing 'topics' field. Every {{DOMAIN:note}} must belong to at least one {{DOMAIN:topic_map}}.`
119
+ );
120
+ }
121
+
122
+ // Description quality check
123
+ const descMatch = processed.match(/^description:\s*(.+)$/m);
124
+ if (descMatch && descMatch[1].length < 20) {
125
+ warnings.push(
126
+ `SCHEMA WARN: Description seems too short. Should add context beyond the title (~100-200 chars).`
127
+ );
128
+ }
129
+
130
+ if (warnings.length > 0) {
131
+ context.respond(warnings.join("\n"));
132
+ }
133
+ }
134
+
135
+ // ─────────────────────────────────────────────
136
+ // 6. Git persistence
137
+ // ─────────────────────────────────────────────
138
+ // Auto-commit the captured content so nothing is lost.
139
+ // OpenClaw bots may not have direct git access, so this
140
+ // is a best-effort operation via the exec API.
141
+
142
+ try {
143
+ await context.exec("git", [
144
+ "add",
145
+ filepath,
146
+ ]);
147
+ await context.exec("git", [
148
+ "commit",
149
+ "-m",
150
+ `Auto: ${filename}`,
151
+ "--no-verify",
152
+ "--quiet",
153
+ ]);
154
+ } catch {
155
+ // Git not available or not a git repo — skip silently.
156
+ // Content is already written to disk; git is a bonus.
157
+ }
158
+
159
+ // ─────────────────────────────────────────────
160
+ // 7. Confirmation
161
+ // ─────────────────────────────────────────────
162
+ // Brief confirmation so the human knows capture succeeded.
163
+
164
+ context.respond(`Captured to ${filepath}`);
165
+ }
@@ -0,0 +1,214 @@
1
+ // Ars Contexta — Heartbeat Hook (OpenClaw)
2
+ // Event: heartbeat (periodic)
3
+ // Purpose: Periodic background maintenance that runs between conversations.
4
+ // Checks vault health, processes accumulated sessions, and surfaces
5
+ // maintenance signals without requiring explicit user invocation.
6
+ //
7
+ // This is a TEMPLATE. During /init, {{VARIABLE}} markers are replaced
8
+ // with values from the derivation manifest.
9
+ //
10
+ // This hook has no Claude Code equivalent. Claude Code relies on the
11
+ // Stop hook (session-capture.sh) and manual /rethink invocations.
12
+ // OpenClaw's heartbeat event enables background processing between
13
+ // conversations, which is unique to the messaging platform model.
14
+ //
15
+ // The heartbeat is conservative: it DETECTS and REPORTS but does NOT
16
+ // auto-remediate. Detection is always safe because it only reads state.
17
+ // Remediation requires judgment and runs through skills.
18
+
19
+ import type { HeartbeatContext } from "@openclaw/sdk";
20
+
21
+ export default async function heartbeat(context: HeartbeatContext) {
22
+ const signals: string[] = [];
23
+ const actions: string[] = [];
24
+
25
+ // ─────────────────────────────────────────────
26
+ // 1. Session Accumulation Check
27
+ // ─────────────────────────────────────────────
28
+ // Count unprocessed sessions. When sessions accumulate,
29
+ // they contain methodology learnings that should be mined.
30
+ // This is the trigger for /remember --mine-sessions.
31
+
32
+ const sessionFiles = await context
33
+ .listFiles("ops/sessions/", { pattern: "*.json" })
34
+ .catch(() => []);
35
+ const unprocessedSessions = sessionFiles.filter(
36
+ (f: string) => !f.endsWith("current.json")
37
+ ).length;
38
+
39
+ if (unprocessedSessions >= 5) {
40
+ signals.push(
41
+ `${unprocessedSessions} unprocessed sessions in ops/sessions/`
42
+ );
43
+ actions.push(
44
+ "Consider running /remember --mine-sessions to extract methodology learnings."
45
+ );
46
+ }
47
+
48
+ // ─────────────────────────────────────────────
49
+ // 2. Observation Accumulation Check
50
+ // ─────────────────────────────────────────────
51
+ // Observations accumulate during normal work. When enough
52
+ // pile up, /rethink should triage and promote the valuable ones.
53
+
54
+ const obsFiles = await context
55
+ .listFiles("ops/observations/", { pattern: "*.md" })
56
+ .catch(() => []);
57
+ const pendingObs = await countByStatus(context, obsFiles, "pending");
58
+
59
+ if (pendingObs >= {{OBS_THRESHOLD:-10}}) {
60
+ signals.push(`${pendingObs} pending observations`);
61
+ actions.push(
62
+ "Consider running /{DOMAIN:rethink} to triage observations."
63
+ );
64
+ }
65
+
66
+ // ─────────────────────────────────────────────
67
+ // 3. Tension Accumulation Check
68
+ // ─────────────────────────────────────────────
69
+ // Tensions represent contradictions in the knowledge graph.
70
+ // Unresolved tensions degrade system coherence over time.
71
+
72
+ const tensionFiles = await context
73
+ .listFiles("ops/tensions/", { pattern: "*.md" })
74
+ .catch(() => []);
75
+ const pendingTensions = await countByStatus(
76
+ context,
77
+ tensionFiles,
78
+ "pending"
79
+ );
80
+ const openTensions = await countByStatus(context, tensionFiles, "open");
81
+ const unresolvedTensions = pendingTensions + openTensions;
82
+
83
+ if (unresolvedTensions >= {{TENSION_THRESHOLD:-5}}) {
84
+ signals.push(`${unresolvedTensions} unresolved tensions`);
85
+ actions.push(
86
+ "Consider running /{DOMAIN:rethink} to address tensions."
87
+ );
88
+ }
89
+
90
+ // ─────────────────────────────────────────────
91
+ // 4. Inbox Pressure Check
92
+ // ─────────────────────────────────────────────
93
+ // Inbox items represent captured content that has not been
94
+ // processed into the knowledge graph. Accumulation means
95
+ // the processing pipeline is falling behind capture rate.
96
+
97
+ const inboxFiles = await context
98
+ .listFiles("{{INBOX_DIR:-inbox}}/", { pattern: "*.md", recursive: true })
99
+ .catch(() => []);
100
+ const inboxCount = inboxFiles.length;
101
+
102
+ if (inboxCount >= 3) {
103
+ signals.push(`${inboxCount} items in {{INBOX_DIR:-inbox}}/`);
104
+ actions.push(
105
+ "Consider running /{DOMAIN:reduce} or /pipeline to process inbox."
106
+ );
107
+ }
108
+
109
+ // ─────────────────────────────────────────────
110
+ // 5. Orphan Note Detection
111
+ // ─────────────────────────────────────────────
112
+ // Notes without incoming links are disconnected from the
113
+ // knowledge graph. They represent lost value — ideas that
114
+ // exist but cannot be found through traversal.
115
+
116
+ const noteFiles = await context
117
+ .listFiles("{{NOTES_DIR:-notes}}/", { pattern: "*.md" })
118
+ .catch(() => []);
119
+
120
+ let orphanCount = 0;
121
+ for (const noteFile of noteFiles) {
122
+ const noteName = noteFile
123
+ .replace(/^.*\//, "")
124
+ .replace(/\.md$/, "");
125
+
126
+ // Search for incoming wiki links
127
+ const backlinks = await context
128
+ .searchFiles(`[[${noteName}]]`, {
129
+ directory: "{{NOTES_DIR:-notes}}/",
130
+ pattern: "*.md",
131
+ })
132
+ .catch(() => []);
133
+
134
+ // Exclude self-references
135
+ const externalBacklinks = backlinks.filter(
136
+ (f: string) => !f.endsWith(noteFile)
137
+ );
138
+
139
+ if (externalBacklinks.length === 0) {
140
+ orphanCount++;
141
+ }
142
+ }
143
+
144
+ if (orphanCount > 0) {
145
+ signals.push(`${orphanCount} orphan notes (no incoming links)`);
146
+ actions.push(
147
+ "Consider running /{DOMAIN:reflect} to find connections for orphan notes."
148
+ );
149
+ }
150
+
151
+ // ─────────────────────────────────────────────
152
+ // 6. Goals Staleness Check
153
+ // ─────────────────────────────────────────────
154
+ // If goals haven't been updated recently, they may be stale.
155
+ // Stale goals misguide session orientation.
156
+
157
+ const goalsFile =
158
+ (await context.readFile("self/goals.md").catch(() => null)) ||
159
+ (await context.readFile("ops/goals.md").catch(() => null));
160
+
161
+ if (goalsFile) {
162
+ const updatedMatch = goalsFile.match(/^updated:\s*(.+)$/m);
163
+ if (updatedMatch) {
164
+ const lastUpdated = new Date(updatedMatch[1]);
165
+ const daysSince = Math.floor(
166
+ (Date.now() - lastUpdated.getTime()) / (1000 * 60 * 60 * 24)
167
+ );
168
+ if (daysSince > 14) {
169
+ signals.push(`Goals last updated ${daysSince} days ago`);
170
+ actions.push(
171
+ "Consider reviewing and updating goals to reflect current priorities."
172
+ );
173
+ }
174
+ }
175
+ }
176
+
177
+ // ─────────────────────────────────────────────
178
+ // 7. Report (only if signals exist)
179
+ // ─────────────────────────────────────────────
180
+ // The heartbeat is silent when everything is healthy.
181
+ // Only surfaces information when conditions are violated.
182
+
183
+ if (signals.length > 0) {
184
+ const report = [
185
+ "## Maintenance Signals (heartbeat)\n",
186
+ ...signals.map((s: string) => `- ${s}`),
187
+ "",
188
+ "### Suggested Actions\n",
189
+ ...actions.map((a: string) => `- ${a}`),
190
+ ].join("\n");
191
+
192
+ context.notify(report);
193
+ }
194
+ }
195
+
196
+ // ─────────────────────────────────────────────
197
+ // Helper: Count files matching a status in YAML frontmatter
198
+ // ─────────────────────────────────────────────
199
+
200
+ async function countByStatus(
201
+ context: HeartbeatContext,
202
+ files: string[],
203
+ status: string
204
+ ): Promise<number> {
205
+ let count = 0;
206
+ for (const file of files) {
207
+ const content = await context.readFile(file).catch(() => "");
208
+ const statusMatch = content.match(/^status:\s*(.+)$/m);
209
+ if (statusMatch && statusMatch[1].trim() === status) {
210
+ count++;
211
+ }
212
+ }
213
+ return count;
214
+ }
@@ -0,0 +1,70 @@
1
+ # shared/features/ -- Canonical Feature Blocks
2
+
3
+ The 16 canonical feature blocks live at `generators/features/`. They are composable context file fragments that the derivation engine selects, transforms with domain vocabulary, and composes into a coherent system document.
4
+
5
+ This directory does not duplicate those files. It exists to document the shared feature layer from a distribution perspective.
6
+
7
+ ## Canonical Source
8
+
9
+ All feature block files: `generators/features/`
10
+
11
+ ## The 16 Feature Blocks
12
+
13
+ | # | Block | Included When | What It Adds |
14
+ |---|-------|---------------|--------------|
15
+ | 1 | `atomic-notes.md` | Granularity = atomic or moderate | Atomicity principles, composability test, split signals |
16
+ | 2 | `wiki-links.md` | Always | Link philosophy, inline vs footer patterns, propositional semantics |
17
+ | 3 | `mocs.md` | Navigation depth >= 2-tier | MOC types, lifecycle, maintenance protocol, health thresholds |
18
+ | 4 | `processing-pipeline.md` | Always | Phase skeleton, skill invocation rules, quality gates, processing depth config |
19
+ | 5 | `semantic-search.md` | qmd opted in during onboarding | Search strategy, semantic vs keyword, query patterns, fallback |
20
+ | 6 | `schema.md` | Always | Field definitions, query patterns, evolution rules, validation |
21
+ | 7 | `maintenance.md` | Always | Health checks, reweaving triggers, condition-based maintenance |
22
+ | 8 | `self-evolution.md` | Always | Architect advice, /remember-driven adoption, reseed lifecycle |
23
+ | 9 | `personality.md` | When personality is derived | Voice instructions, identity generation, anti-patterns |
24
+ | 10 | `session-rhythm.md` | Always | Orient, work, persist phases, handoff protocol, session capture |
25
+ | 11 | `templates.md` | When templates are generated | Template usage instructions, schema references |
26
+ | 12 | `multi-domain.md` | Multiple domains detected | Cross-domain linking, shared graph, domain-specific templates |
27
+ | 13 | `ethical-guardrails.md` | Always | Privacy, transparency, emotional safety, autonomy encouragement |
28
+ | 14 | `self-space.md` | Optional (off for research, on for personal assistant) | Agent identity, memory, reflections, goals |
29
+ | 15 | `helper-functions.md` | Always | Safe rename, graph maintenance, utility scripts |
30
+ | 16 | `graph-analysis.md` | Always | Graph traversal, topology analysis, synthesis detection, domain-adapted queries |
31
+
32
+ ## Always-Included Blocks
33
+
34
+ Ten blocks are non-negotiable and present in every generated system regardless of configuration:
35
+
36
+ - `wiki-links.md` (2)
37
+ - `processing-pipeline.md` (4)
38
+ - `schema.md` (6)
39
+ - `maintenance.md` (7)
40
+ - `self-evolution.md` (8)
41
+ - `session-rhythm.md` (10)
42
+ - `templates.md` (11)
43
+ - `ethical-guardrails.md` (13)
44
+ - `helper-functions.md` (15)
45
+ - `graph-analysis.md` (16)
46
+
47
+ ## Architecture
48
+
49
+ Each block has a defined layer, dependencies, and platform requirements:
50
+
51
+ | # | Block | Layer | Dependencies |
52
+ |---|-------|-------|-------------|
53
+ | 1 | `atomic-notes.md` | Convention | wiki-links |
54
+ | 2 | `wiki-links.md` | Foundation+Convention | None |
55
+ | 3 | `mocs.md` | Convention | wiki-links |
56
+ | 4 | `processing-pipeline.md` | Convention+Automation | atomic-notes, wiki-links, mocs |
57
+ | 5 | `semantic-search.md` | Automation | None |
58
+ | 6 | `schema.md` | Convention+Automation | templates |
59
+ | 7 | `maintenance.md` | Convention | mocs, wiki-links |
60
+ | 8 | `self-evolution.md` | Convention | maintenance |
61
+ | 9 | `personality.md` | Convention | None |
62
+ | 10 | `session-rhythm.md` | Convention | None |
63
+ | 11 | `templates.md` | Convention | None |
64
+ | 12 | `multi-domain.md` | Convention | mocs, templates |
65
+ | 13 | `ethical-guardrails.md` | Convention | None |
66
+ | 14 | `self-space.md` | Convention | None |
67
+ | 15 | `helper-functions.md` | Automation | None |
68
+ | 16 | `graph-analysis.md` | Automation | wiki-links, schema |
69
+
70
+ Feature blocks are platform-agnostic. Both Claude Code and OpenClaw use the same blocks -- the difference is how they are composed into the platform's context file format (CLAUDE.md vs AGENTS.md).