arscontexta 0.6.0

package/platforms/claude-code/hooks/session-orient.sh.template

@@ -0,0 +1,189 @@
+#!/bin/bash
+# Ars Contexta — Session Orientation Hook (Claude Code)
+# Event: SessionStart
+# Purpose: Inject workspace structure, identity, methodology, and maintenance
+#          signals at session start so the agent always knows what exists,
+#          what it was working on, and where to pick up.
+#
+# This is a TEMPLATE. During /init, {{VARIABLE}} markers are replaced
+# with values from the derivation manifest. The generator also conditionally
+# includes sections based on enabled features.
+
+# ─────────────────────────────────────────────
+# 1. Persistent Working Memory (goals)
+# ─────────────────────────────────────────────
+# Goals orient the agent to what matters before anything else.
+# Check both self/ and ops/ locations for the goals file.
+
+if [ -f self/goals.md ]; then
+  echo "## Current Goals"
+  echo ""
+  cat self/goals.md
+  echo ""
+elif [ -f ops/goals.md ]; then
+  echo "## Current Goals"
+  echo ""
+  cat ops/goals.md
+  echo ""
+fi
+
+# ─────────────────────────────────────────────
+# 2. Learned Behavioral Patterns (methodology)
+# ─────────────────────────────────────────────
+# Load the 5 most recent methodology notes (titles only).
+# These are behavioral learnings from /remember that the
+# agent should be aware of without reading full content.
+
+METH_FILES=$(ls -t ops/methodology/*.md 2>/dev/null | head -5)
+if [ -n "$METH_FILES" ]; then
+  echo "## Recent Methodology Learnings"
+  echo ""
+  for f in $METH_FILES; do
+    # Extract title from first heading
+    TITLE=$(grep '^# ' "$f" 2>/dev/null | head -1 | sed 's/^# //')
+    if [ -n "$TITLE" ]; then
+      echo "- $TITLE"
+    fi
+  done
+  echo ""
+fi
+
+# ─────────────────────────────────────────────
+# 3. Previous Session State (continuity)
+# ─────────────────────────────────────────────
+# If a previous session's state was captured, load it
+# so the agent can resume where it left off.
+
+if [ -f ops/sessions/current.json ]; then
+  echo "## Previous Session Context"
+  echo ""
+  cat ops/sessions/current.json
+  echo ""
+fi
+
+# ─────────────────────────────────────────────
+# 4. Workspace Tree (structural orientation)
+# ─────────────────────────────────────────────
+# Show the workspace structure up to 3 levels deep.
+# This gives the agent a map of all files without reading any.
+
+echo "## Workspace Structure"
+echo ""
+
+if command -v tree &> /dev/null; then
+  tree -L 3 --charset ascii -I '.git|node_modules|.claude' -P '*.md|*.yaml|*.json' . 2>/dev/null
+else
+  # Fallback: find-based tree listing
+  find . -name "*.md" -not -path "./.git/*" -not -path "*/node_modules/*" \
+    -not -path "./ops/sessions/*" -maxdepth 3 2>/dev/null | sort | \
+    while read -r file; do
+      depth=$(echo "$file" | tr -cd '/' | wc -c)
+      indent=$(printf '%*s' "$((depth * 2))" '')
+      basename=$(basename "$file")
+      echo "${indent}${basename}"
+    done
+fi
+
+echo ""
+
+# ─────────────────────────────────────────────
+# 5. Identity (self space — conditional)
+# ─────────────────────────────────────────────
+# {{IF_SELF_SPACE}}
+# If self/ space is enabled, load identity and methodology
+# so the agent remembers who it is across sessions.
+
+if [ -f self/identity.md ]; then
+  echo "## Identity"
+  echo ""
+  cat self/identity.md
+  echo ""
+fi
+
+if [ -f self/methodology.md ]; then
+  cat self/methodology.md
+  echo ""
+fi
+# {{END_IF_SELF_SPACE}}
+
+# ─────────────────────────────────────────────
+# 6. Condition-Based Maintenance Signals
+# ─────────────────────────────────────────────
+# Check vault state against thresholds. These are not
+# time-based triggers but measurements of actual state.
+# Fires only when a condition is violated.
+
+SIGNALS=""
+
+# Observation accumulation threshold (default: 10)
+OBS_COUNT=$(grep -rl '^status: pending' ops/observations/ 2>/dev/null | wc -l | tr -d ' ')
+if [ "$OBS_COUNT" -ge {{OBS_THRESHOLD:-10}} ]; then
+  SIGNALS="${SIGNALS}CONDITION: ${OBS_COUNT} pending observations. Consider /{DOMAIN:rethink}.\n"
+fi
+
+# Tension accumulation threshold (default: 5)
+TENS_COUNT=$(grep -rl '^status: pending\|^status: open' ops/tensions/ 2>/dev/null | wc -l | tr -d ' ')
+if [ "$TENS_COUNT" -ge {{TENSION_THRESHOLD:-5}} ]; then
+  SIGNALS="${SIGNALS}CONDITION: ${TENS_COUNT} unresolved tensions. Consider /{DOMAIN:rethink}.\n"
+fi
+
+# Unprocessed sessions threshold (default: 5)
+SESS_COUNT=$(find ops/sessions/ -name "*.json" -not -name "current.json" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$SESS_COUNT" -ge 5 ]; then
+  SIGNALS="${SIGNALS}CONDITION: ${SESS_COUNT} unprocessed sessions. Consider /remember --mine-sessions.\n"
+fi
+
+# Inbox pressure (default: 3 items)
+INBOX_COUNT=$(find {{INBOX_DIR:-inbox}}/ -name "*.md" -maxdepth 2 2>/dev/null | wc -l | tr -d ' ')
+if [ "$INBOX_COUNT" -ge 3 ]; then
+  SIGNALS="${SIGNALS}CONDITION: ${INBOX_COUNT} items in {{INBOX_DIR:-inbox}}/. Consider /{DOMAIN:reduce} or /pipeline.\n"
+fi
+
+# Orphan notes (any is a signal)
+NOTES_DIR="{{NOTES_DIR:-notes}}"
+ORPHAN_COUNT=0
+if [ -d "$NOTES_DIR" ]; then
+  for f in "$NOTES_DIR"/*.md; do
+    [ -f "$f" ] || continue
+    title=$(basename "$f" .md)
+    hits=$(grep -rl "\[\[$title\]\]" "$NOTES_DIR"/ 2>/dev/null | wc -l | tr -d ' ')
+    [ "$hits" -eq 0 ] && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
+  done
+  if [ "$ORPHAN_COUNT" -gt 0 ]; then
+    SIGNALS="${SIGNALS}CONDITION: ${ORPHAN_COUNT} orphan notes (no incoming links). Consider /{DOMAIN:reflect}.\n"
+  fi
+fi
+
+# Tutorial resume check
+if [ -f ops/tutorial-state.yaml ]; then
+  STEP=$(grep '^current_step:' ops/tutorial-state.yaml 2>/dev/null | awk '{print $2}')
+  if [ -n "$STEP" ] && [ "$STEP" -le 5 ] 2>/dev/null; then
+    SIGNALS="${SIGNALS}NOTE: Unfinished tutorial (step ${STEP} of 5). Resume with /tutorial.\n"
+  fi
+fi
+
+if [ -n "$SIGNALS" ]; then
+  echo "## Maintenance Signals"
+  echo ""
+  printf "$SIGNALS"
+  echo ""
+fi
+
+# ─────────────────────────────────────────────
+# 7. Queue Summary (pipeline + maintenance)
+# ─────────────────────────────────────────────
+# Show pending task counts from the unified queue.
+# Full reconciliation happens in /next, not here.
+# The hook's job is context injection, not queue management.
+
+if [ -f ops/queue/queue.json ]; then
+  PIPELINE_PENDING=$(jq '[.tasks[] | select(.type != "maintenance" and .status == "pending")] | length' ops/queue/queue.json 2>/dev/null || echo "0")
+  MAINT_PENDING=$(jq '[.tasks[] | select(.type == "maintenance" and .status == "pending")] | length' ops/queue/queue.json 2>/dev/null || echo "0")
+  if [ "$PIPELINE_PENDING" -gt 0 ] || [ "$MAINT_PENDING" -gt 0 ]; then
+    echo "## Queue"
+    echo ""
+    echo "  Pipeline: ${PIPELINE_PENDING} pending | Maintenance: ${MAINT_PENDING} pending"
+    echo "  Run /next for recommendations."
+    echo ""
+  fi
+fi

package/platforms/claude-code/hooks/write-validate.sh.template

@@ -0,0 +1,106 @@
+#!/bin/bash
+# Ars Contexta — Write Validation Hook (Claude Code)
+# Event: PostToolUse (Write)
+# Purpose: Validate YAML frontmatter and required fields on every note write.
+#          Schema enforcement is an INVARIANT — active from day one.
+#
+# This is a TEMPLATE. During /init, {{VARIABLE}} markers are replaced
+# with values from the derivation manifest.
+#
+# This hook WARNS but does not BLOCK. Capture speed matters more than
+# perfection at the moment of creation. Warnings guide the agent to
+# fix issues immediately while context is fresh.
+
+# The written file path comes from the hook context
+FILE="${TOOL_INPUT_PATH:-$1}"
+
+# ─────────────────────────────────────────────
+# Only validate notes in the knowledge space
+# ─────────────────────────────────────────────
+# Skip validation for operational files (ops/), inbox captures,
+# session files, and configuration. Only notes in the knowledge
+# space need schema enforcement.
+
+case "$FILE" in
+  {{NOTES_DIR:-notes}}/*|*thinking/*)
+    # This is a knowledge note — validate it
+    ;;
+  *)
+    # Not a knowledge note — skip validation
+    exit 0
+    ;;
+esac
+
+# ─────────────────────────────────────────────
+# 1. YAML Frontmatter Existence
+# ─────────────────────────────────────────────
+if ! head -1 "$FILE" 2>/dev/null | grep -q "^---$"; then
+  echo "SCHEMA WARN: Missing YAML frontmatter in $(basename "$FILE")"
+  echo "  Every {{DOMAIN:note}} needs frontmatter with at least description and topics."
+  exit 0
+fi
+
+# ─────────────────────────────────────────────
+# 2. Required Field: description
+# ─────────────────────────────────────────────
+if ! head -20 "$FILE" 2>/dev/null | grep -q "^description:"; then
+  echo "SCHEMA WARN: Missing 'description' field in $(basename "$FILE")"
+  echo "  Description enables filtering and progressive disclosure."
+  echo "  Add: description: [one sentence adding context beyond the title]"
+fi
+
+# ─────────────────────────────────────────────
+# 3. Required Field: topics
+# ─────────────────────────────────────────────
+# Check both YAML frontmatter and markdown footer format
+HAS_TOPICS=false
+if head -20 "$FILE" 2>/dev/null | grep -q "^topics:"; then
+  HAS_TOPICS=true
+fi
+if grep -q "^Topics:" "$FILE" 2>/dev/null; then
+  HAS_TOPICS=true
+fi
+
+if [ "$HAS_TOPICS" = false ]; then
+  echo "SCHEMA WARN: Missing 'topics' field in $(basename "$FILE")"
+  echo "  Every {{DOMAIN:note}} must belong to at least one {{DOMAIN:topic_map}}."
+  echo "  Add: topics: [\"[[index]]\"]"
+fi
+
+# ─────────────────────────────────────────────
+# 4. Description Quality Check
+# ─────────────────────────────────────────────
+# Warn if description is suspiciously short (likely placeholder)
+DESC=$(head -20 "$FILE" 2>/dev/null | grep "^description:" | sed 's/^description: *//')
+if [ -n "$DESC" ]; then
+  DESC_LEN=${#DESC}
+  if [ "$DESC_LEN" -lt 20 ]; then
+    echo "SCHEMA WARN: Description seems too short in $(basename "$FILE")"
+    echo "  Description should add context beyond the title (~100-200 chars)."
+  fi
+fi
+
+# ─────────────────────────────────────────────
+# 5. Title Format Check
+# ─────────────────────────────────────────────
+# Check that the first heading matches prose-as-title pattern
+TITLE=$(grep '^# ' "$FILE" 2>/dev/null | head -1 | sed 's/^# //')
+if [ -n "$TITLE" ]; then
+  # Warn on title-case or ALL-CAPS (should be lowercase sentence)
+  if echo "$TITLE" | grep -qE '^[A-Z][A-Z]'; then
+    echo "SCHEMA NOTE: Title may not follow prose-as-title convention in $(basename "$FILE")"
+    echo "  Titles should be lowercase propositions (e.g., 'claims must be specific enough to be wrong')"
+  fi
+fi
+
+# ─────────────────────────────────────────────
+# 6. Discovery Nudge (optional)
+# ─────────────────────────────────────────────
+# {{IF_DISCOVERY_NUDGE}}
+# Remind the agent to check for connections after creating a note.
+# This is a nudge, not enforcement — the pipeline handles it systematically.
+LINK_COUNT=$(grep -o '\[\[' "$FILE" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$LINK_COUNT" -eq 0 ]; then
+  echo "NOTE: $(basename "$FILE") has no wiki links. Consider running /{DOMAIN:reflect} to find connections."
+fi
+# {{END_IF_DISCOVERY_NUDGE}}

package/platforms/openclaw/generator.md

@@ -0,0 +1,82 @@
+# OpenClaw Platform -- Generation Reference
+
+## Generator Sources
+
+OpenClaw generation uses two generator templates:
+
+- `generators/agents-md.md` -- AGENTS.md generation (operational guide)
+- `generators/soul-md.md` -- SOUL.md generation (identity and personality)
+
+Together these produce the split context that OpenClaw auto-loads at session start: SOUL.md (who the bot is) and AGENTS.md (how the bot works).
+
+## What OpenClaw Platform Generates
+
+An OpenClaw deployment produces:
+
+### 1. SOUL.md (Identity File)
+
+The bot's identity and personality. Auto-loaded at session start alongside AGENTS.md and USER.md. This is personal and warm -- a letter from the human to the bot explaining who it is, why it matters, and what the relationship means.
+
+Contains:
+
+- Personalized greeting and purpose
+- Why persistent memory matters
+- Identity and voice characteristics
+- Relationship context with the human
+
+Generated by: `generators/soul-md.md`
+
+### 2. AGENTS.md (Operational Guide)
+
+The bot's operational methodology. Contains the same intellectual content as CLAUDE.md but structured for the OpenClaw messaging context -- shorter (target 80-120 lines), conversation-oriented, single-agent focus.
+
+Contains:
+
+- Philosophy and operating principles
+- Traversal instructions (WORKSPACE-MAP.md loading, link following)
+- Note design patterns
+- Processing workflow (adapted from feature blocks)
+- Session rhythm
+- Ethical guardrails
+
+Generated by: `generators/agents-md.md`
+
+### 3. MEMORY.md (Memory Bootstrap)
+
+Orientation file for the bot's personal memory space (self/). Explains the memory structure, what persists between sessions, and how to use atomic notes and MOCs for personal knowledge.
+
+### 4. hooks/ (TypeScript)
+
+Hook scripts in TypeScript format for the OpenClaw platform. See `platforms/openclaw/hooks/` for hook template documentation.
+
+- `command:new` -- Capture hook for incoming content
+- `agent:bootstrap` -- Session start orientation (tree injection, self/ loading)
+
+### 5. Processing Skills (OpenClaw Format)
+
+Processing skills adapted to OpenClaw's skill format. Unlike Claude Code where skills are inherited from the plugin, OpenClaw skills are packaged within the ClawHub skill manifest. Skills use the same runtime vocabulary transformation via `ops/derivation-manifest.md`.
+
+The `knowledge-` prefix convention is retained for namespace hygiene in shared marketplaces.
+
+## Platform Characteristics
+
+| Aspect | Detail |
+|--------|--------|
+| Context loading | SOUL.md + AGENTS.md + USER.md auto-loaded by OpenClaw |
+| Hook language | TypeScript |
+| Hook events | command:new, agent:bootstrap |
+| Skill format | OpenClaw skill format (skills/*.md) |
+| Agent format | Single-agent (the bot itself) |
+| File access | Via OpenClaw messaging gateway |
+| MCP support | Via OpenClaw MCP integration |
+
+## Key Differences from Claude Code
+
+| Aspect | Claude Code | OpenClaw |
+|--------|-------------|----------|
+| Context files | Single CLAUDE.md | Split: SOUL.md + AGENTS.md |
+| Identity | Embedded in CLAUDE.md | Separate SOUL.md (personal, warm) |
+| Target length | Unbounded (full methodology) | AGENTS.md: 80-120 lines |
+| Interaction model | CLI with filesystem | Messaging gateway |
+| Skill inheritance | From plugin (not copied) | Packaged in ClawHub skill |
+| Multi-agent | Subagents via Task tool | Single agent per bot |

package/platforms/openclaw/hooks/README.md

@@ -0,0 +1,89 @@
+# OpenClaw Hook Templates
+
+Hook templates for the OpenClaw platform. Hooks are TypeScript functions triggered by OpenClaw events. They run at command boundaries to enforce methodology automatically.
+
+## Hook Events
+
+OpenClaw supports two hook events relevant to generated vaults:
+
+### command:new -- Capture
+
+**What it does:** Triggers when new content arrives through the messaging gateway. Handles incoming captures with minimal friction so nothing is lost.
+
+**Template behavior:**
+
+1. **Inbox routing** -- Route incoming content to the appropriate inbox subdirectory based on content type or channel.
+
+2. **Timestamp injection** -- Add a `created` timestamp to incoming content if not already present.
+
+3. **Format normalization** -- Ensure captured content has minimal YAML frontmatter (at least a description field) so it is queryable from the moment it enters the vault.
+
+**The principle:** Capture speed beats capture precision. The hook adds just enough structure to make content findable without slowing down the human's ability to dump thoughts quickly.
+
+### agent:bootstrap -- Session Orientation
+
+**What it does:** Triggers when the bot starts a new session. Loads workspace context so the bot knows what exists and can orient to current priorities.
+
+**Template behavior:**
+
+1. **Tree injection** -- Load WORKSPACE-MAP.md (or generate a tree listing) so the bot has a map of all files. Unlike Claude Code where the tree is injected via shell output, OpenClaw loads the map file directly.
+
+2. **self/ loading** -- Load the bot's memory orientation file (self/README.md or MEMORY.md) so it remembers who it is, what it cares about, and what it was working on.
+
+3. **Goal surfacing** -- If a goals file exists in self/, load current priorities to orient the session.
+
+**Generated as:** TypeScript hook files in the bot's hooks/ directory, registered in the OpenClaw hook configuration.
+
+## Generation Notes
+
+The derivation engine generates hook scripts based on enabled features:
+
+| Feature Block | Hook Impact |
+|---------------|-------------|
+| `session-rhythm.md` | Enables agent:bootstrap hook with tree + self/ loading |
+| `schema.md` | Adds validation nudge to command:new hook |
+| `light-processing.md` | command:new adds capture-and-connect reminder |
+| `personality.md` | agent:bootstrap loads identity context |
+
+Hooks are generated once during /setup. Unlike Claude Code's bash scripts, OpenClaw hooks are TypeScript and integrate with OpenClaw's event system directly.
+
+## Key Differences from Claude Code Hooks
+
+| Aspect | Claude Code | OpenClaw |
+|--------|-------------|----------|
+| Language | Bash scripts | TypeScript |
+| Session start | SessionStart event | agent:bootstrap event |
+| Write validation | PostToolUse (Write) | No direct equivalent -- validation runs in command flow |
+| Session end | Stop event | No direct equivalent -- bot sessions end via messaging idle |
+| Capture | No capture hook (CLI input) | command:new for incoming messages |
+| Tree source | Shell `find` or `tree` command | WORKSPACE-MAP.md file loading |
+
+## OpenClaw Hook Registration
+
+OpenClaw hooks are registered in the bot's configuration. The exact format depends on the OpenClaw version, but the pattern is:
+
+```typescript
+// hooks/bootstrap.ts
+export default async function bootstrap(context: AgentContext) {
+  // Load workspace map
+  const tree = await context.readFile('WORKSPACE-MAP.md');
+  context.inject(tree);
+
+  // Load self/ orientation
+  const memory = await context.readFile('self/README.md');
+  context.inject(memory);
+
+  // Surface current goals
+  const goals = await context.readFile('self/goals.md');
+  if (goals) context.inject(goals);
+}
+```
+
+```typescript
+// hooks/capture.ts
+export default async function onNewCommand(content: string, context: AgentContext) {
+  const timestamp = new Date().toISOString();
+  const formatted = addFrontmatter(content, { created: timestamp });
+  await context.writeFile(`inbox/${generateFilename(content)}`, formatted);
+}
+```