@gcunharodrigues/wrxn 0.2.0 → 0.2.1

package/payload/.claude/skills/synapse/references/brackets.md

@@ -1,100 +1,74 @@
-# SYNAPSE Context Brackets Reference
+# SYNAPSE token budget & handoff
 
-## Overview
+*(This reference covers the flat token-budget governor and the non-blocking handoff directive — the
+two controls SYNAPSE applies after it assembles the layer sections.)*
 
-Context brackets control how much content SYNAPSE injects per prompt based on how much context window remains. As the conversation progresses and context fills up, SYNAPSE adapts by changing which layers are active and how many tokens it injects.
+## The flat token budget
 
-The bracket system is implemented in `.aiox-core/core/synapse/context/context-tracker.js`.
+Everything except the constitution is trimmable. SYNAPSE applies ONE flat budget — there are no
+per-tier or per-window budgets.
 
-## The 4 Brackets
-
-| Bracket | Context Remaining | Token Budget | Behavior |
-|---------|-------------------|-------------|----------|
-| **FRESH** | 60-100% | ~800 tokens | Lean injection — essentials only |
-| **MODERATE** | 40-60% | ~1500 tokens | Standard injection — all layers active |
-| **DEPLETED** | 25-40% | ~2000 tokens | Reinforcement — reinforce critical rules, memory hints enabled |
-| **CRITICAL** | <25% | ~2500 tokens | Handoff warning — recommend session handoff, document state |
-
-## How Brackets Are Calculated
-
-The context tracker estimates remaining context using:
+- **Budget:** `RULES_BUDGET_TOKENS` in `.synapse/manifest` (default `600`), overridable per session
+  with the `WRXN_RULES_BUDGET` env var.
+- **Estimate:** a section's token cost is estimated as `ceil(characters / 4)`.
+- **Exempt:** the constitution (L0) sits outside the budget and is always kept.
+- **How it trims:** the trimmable sections keep manifest order. While the kept set is over budget,
+  whole sections are dropped from the END of that order first — the last-declared domain goes first,
+  so earlier-declared domains have higher priority. Sections are dropped whole, never partially.
+- **What it records:** if anything was dropped, a line is appended naming the dropped domains:
 
 ```
-contextPercent = 100 - ((promptCount * avgTokensPerPrompt) / maxContext * 100)
+[SYNAPSE-RULES-TRIM] ROUTING dropped over the 600-token rules budget
 ```
 
-**Default values:**
-- `avgTokensPerPrompt`: 1500
-- `maxContext`: 200000 (Claude's context window)
-
-**Bracket assignment:**
-- `contextPercent >= 60` → FRESH
-- `contextPercent >= 40` → MODERATE
-- `contextPercent >= 25` → DEPLETED
-- `contextPercent < 25` → CRITICAL
-
-Invalid or NaN input defaults to CRITICAL (fail-safe).
-
-## Layer Activation per Bracket
+## The handoff directive
 
-| Bracket | Active Layers | Memory Hints | Handoff Warning |
-|---------|---------------|-------------|-----------------|
-| **FRESH** | L0, L1, L2, L7 | No | No |
-| **MODERATE** | L0-L7 (all) | No | No |
-| **DEPLETED** | L0-L7 (all) | Yes | No |
-| **CRITICAL** | L0-L7 (all) | Yes | Yes |
+When the real consumed context reaches the handoff threshold, SYNAPSE appends a **non-blocking**
+`[HANDOFF REQUIRED]` directive. It never refuses work — it orders a clean wrap-up:
 
-**Key behavior:**
-- **FRESH**: Only core layers (Constitution, Global, Agent, Star-Commands) — saves tokens early
-- **MODERATE**: Full layer stack activated — normal operation
-- **DEPLETED**: Memory hints from MIS enabled (when pro available) to reinforce context
-- **CRITICAL**: Handoff warning injected, recommending session continuation in new window
-
-## Bracket-Specific Rules
+```
+[HANDOFF REQUIRED]
+  Context is at ~42% of the model window (>= the 40% handoff threshold). NON-BLOCKING — do NOT stop work:
+  1. Finish the current request.
+  2. Run the handoff skill to write the baton (a compact handoff document).
+  3. Tell the operator to /clear and open a fresh session, where the baton injects on resume.
+```
 
-The `.synapse/context` domain file contains rules that vary by bracket:
+Like the constitution, the handoff directive is outside the budget — it is never trimmed.
 
-### FRESH Rules
-- Minimize injected rules to essentials only
-- Avoid redundant context — agent has full conversation history
-- Full layer stack available but lean injection
+### The threshold
 
-### MODERATE Rules
-- All layers active at normal priority
-- Monitor token usage — consider summarizing long outputs
-- Prefer concise code examples over verbose explanations
+`consumed = resident_tokens / model_window`. The directive fires when `consumed >=` the threshold.
+The threshold is resolved as: `WRXN_HANDOFF_PCT` env var > `HANDOFF_PCT` in the manifest > `0.40`.
 
-### DEPLETED Rules
-- Reinforce critical rules and constraints
-- Prefer concise responses to save tokens
-- Skip optional layers (L6 keyword domains) to conserve
-- Summarize progress before each action
+### Resident tokens
 
-### CRITICAL Rules
-- Recommend session handoff
-- Summarize current state for new session continuation
-- Only inject L0 Constitution and L1 Global rules — skip other layers
-- Document incomplete work in story file
+The real tokens currently resident in context: the last assistant turn's
+`input_tokens + cache_read_input_tokens + cache_creation_input_tokens` read from the session
+transcript (output tokens are excluded — they are not resident in the next prompt). If the transcript
+is unreadable, the handoff math is skipped silently.
 
-## Token Budget Enforcement
+### The model window
 
-The output formatter (`.aiox-core/core/synapse/output/formatter.js`) enforces token budgets:
+The window is resolved by an explicit precedence, so the math is correct on both 200k and 1M sessions
+instead of assuming a fixed window:
 
-1. Each bracket has a max token budget (800 / 1500 / 2000 / 2500)
-2. Sections are rendered in priority order (CONSTITUTION first, SUMMARY last)
-3. When budget is exceeded, sections are truncated from the end (lowest priority first)
+1. `WRXN_CONTEXT_WINDOW` env var (a positive number wins unconditionally).
+2. The live statusline sidecar for the session (tracks a mid-session model switch).
+3. `CONTEXT_WINDOW` in `.synapse/manifest`.
+4. `~/.claude.json` — a model id tagged `[1m]` ⇒ 1,000,000.
+5. Self-correcting net: resident already past 200,000 ⇒ the window must be larger (1,000,000).
+6. Fallback: 200,000.
 
-**Truncation order** (last removed first):
-```
-SUMMARY → KEYWORD → SQUAD → TASK → WORKFLOW → AGENT → CONSTITUTION
-```
+## Why a flat budget
 
-Constitution (L0) is never truncated.
+An earlier engine varied the budget by an estimate of how much window remained. This engine does not:
+one flat budget keeps assembly cheap and predictable, and the handoff directive — driven by real
+token usage — covers the "running low" case directly instead of through tiered injection.
 
-## Source Files
+## Source
 
 | File | Purpose |
 |------|---------|
-| `.aiox-core/core/synapse/context/context-tracker.js` | Bracket calculation, token budgets, layer configs |
-| `.synapse/context` | Bracket-specific context rules (L1) |
-| `.aiox-core/core/synapse/output/formatter.js` | Token budget enforcement + truncation |
+| `.claude/hooks/synapse-engine.cjs` | `applyBudget`, `estimateTokens`, `resolveBudget`; `readResidentTokens`, `modelWindow`, `resolveHandoffPct`, `handoffDirective`. |
+| `.synapse/manifest` | `RULES_BUDGET_TOKENS`, `HANDOFF_PCT`, `CONTEXT_WINDOW`. |

package/payload/.claude/skills/synapse/references/commands.md

@@ -1,118 +1,61 @@
-# SYNAPSE Commands Reference
+# SYNAPSE invocation & configuration
 
-## Overview
+## SYNAPSE has no interactive commands
 
-SYNAPSE provides three categories of commands:
-1. **Mode star-commands** — Switch response behavior (`*brief`, `*dev`, etc.)
-2. **`*synapse` sub-commands** — Query and manage engine state
-3. **CRUD operations** — Create, modify, and manage domains and rules
+SYNAPSE is not something you call. It is a hook that runs automatically on every prompt. There are no
+mode toggles and no management sub-commands — you change its behavior by editing its files or by
+setting environment variables. (The legacy engine's interactive command surface was removed.)
 
-## Mode Star-Commands (L7)
+## How it is invoked
 
-These commands switch the response mode for the current session. They are detected by L7 (Star-Command processor) and inject mode-specific rules.
+SYNAPSE is wired as a `UserPromptSubmit` hook in the install's `.claude/settings.json`:
 
-| Command | Behavior |
-|---------|----------|
-| `*brief` | Bullet points only, max 5 items, no code blocks unless requested, skip preamble |
-| `*dev` | Code over explanation, minimal changes, follow existing patterns, skip docs unless needed |
-| `*review` | Check code quality and patterns, identify bugs/security issues, suggest improvements with rationale |
-| `*plan` | Outline approach before implementation, list files to modify, identify risks, estimate complexity |
-| `*discuss` | Explore trade-offs and alternatives, ask clarifying questions, present pros/cons, recommend with reasoning |
-| `*debug` | Analyze error messages and stack traces, check common failure patterns, suggest targeted fixes |
-| `*explain` | Explain in teaching detail, use analogies, show examples with code, build from basics to advanced |
-
-**Usage:** Type the command anywhere in your prompt. The mode persists for that response.
-
-**Source:** `.synapse/commands` (KEY=VALUE format, `COMMANDS_RULE_{MODE}_{INDEX}`)
-
-## `*synapse` Sub-Commands
-
-These commands query or control the SYNAPSE engine state.
-
-| Command | What it does |
-|---------|-------------|
-| `*synapse help` | Show available synapse commands and their descriptions |
-| `*synapse status` | Display current state: active domains, layers, session info |
-| `*synapse debug` | Show detailed debug info: manifest parse results, domain load times, rule counts |
-| `*synapse domains` | List all registered domains with their state and trigger conditions |
-| `*synapse session` | Show current session context: active agent, workflow, bracket level |
-| `*synapse reload` | Force reload of manifest and all domain files from disk |
-
-**Note:** These are read-only operations handled by the L7 star-command processor in the hook. They do not modify any files.
-
-## CRUD Operations
-
-These commands modify domain files and the manifest. They are implemented as Claude Code slash commands in `.claude/commands/synapse/`.
-
-### Router
-
-All CRUD operations go through the manager: `.claude/commands/synapse/manager.md`
-
-The manager parses the sub-command and dispatches to the appropriate task file.
-
-### Available Operations
-
-| Command | Task File | Purpose |
-|---------|-----------|---------|
-| `*synapse create` | `tasks/create-domain.md` | Create new domain file + manifest entry |
-| `*synapse add` | `tasks/add-rule.md` | Add a new rule to an existing domain |
-| `*synapse edit` | `tasks/edit-rule.md` | Edit or remove a rule by index |
-| `*synapse toggle` | `tasks/toggle-domain.md` | Toggle domain STATE between active/inactive |
-| `*synapse command` | `tasks/create-command.md` | Create a new star-command definition |
-| `*synapse suggest` | `tasks/suggest-domain.md` | Suggest the best domain for a given rule |
-
-### Usage Examples
-
-**Create a new domain:**
-```
-*synapse create
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/synapse-engine.cjs\"" } ] }
+    ]
+  }
+}
 ```
-Prompts for: domain name, layer, description, initial rules.
 
-**Add a rule to an existing domain:**
-```
-*synapse add global "Always prefer functional patterns over imperative"
-```
+On each prompt Claude Code passes the event JSON on stdin; the engine returns an envelope whose
+`additionalContext` is the `<synapse-rules>` block (or `{}` to inject nothing). It is fail-open: any
+fault injects nothing and never blocks the prompt.
 
-**Toggle a domain off:**
-```
-*synapse toggle agent-dev
-```
+## Configuration
 
-**Edit a specific rule:**
-```
-*synapse edit global 3
-```
-Opens rule at index 3 in `global` domain for editing.
+| Knob | Where | Effect |
+|------|-------|--------|
+| `RULES_BUDGET_TOKENS` | `.synapse/manifest` | Token ceiling on the trimmable sections (default 600). |
+| `HANDOFF_PCT` | `.synapse/manifest` | Handoff threshold as a window fraction (default 0.40). |
+| `CONTEXT_WINDOW` | `.synapse/manifest` | Pin the model window (tokens) for the handoff math. |
+| `WRXN_RULES_BUDGET` | env | Overrides the rules budget for the session. |
+| `WRXN_HANDOFF_PCT` | env | Overrides the handoff threshold for the session. |
+| `WRXN_CONTEXT_WINDOW` | env | Forces the model window for the session. |
 
-**Create a new star-command:**
-```
-*synapse command
-```
-Prompts for: command name, behavior rules.
+To add or change the injected rules, edit the domain files and the registry — see
+[domains & rule files](domains.md) and [the manifest format](manifest.md).
 
-**Get domain suggestion for a rule:**
-```
-*synapse suggest "Use TypeScript strict mode"
-```
-Analyzes the rule content and suggests the best-fit domain.
+## Inspecting it
 
-## Command Categories Summary
+Run the engine by hand with a sample event to see exactly what it would inject:
 
+```sh
+echo '{"prompt":"please deploy","cwd":"'"$PWD"'"}' \
+  | node .claude/hooks/synapse-engine.cjs
 ```
-Automatic per-event     -> HOOK   (synapse-engine.js, UserPromptSubmit)
-User guidance/learning  -> SKILL  (synapse/SKILL.md + references)
-User-invoked CRUD       -> COMMAND (synapse/manager.md + 6 tasks)
-Read-state star-cmds    -> HOOK L7 (*synapse status, *synapse debug, *brief, *dev)
-Write-file star-cmds    -> COMMAND (*synapse create, *synapse add, *synapse toggle)
-```
 
-## Source Files
+- An empty `{}` means nothing was injected — check that you are inside a wrxn install (a
+  `wrxn.install.json` receipt exists at or above `cwd`) and that domains are `active` in the manifest.
+- A `<synapse-rules>` block shows the assembled layers; a recall domain (e.g. `routing`) appears only
+  when the prompt contains one of its trigger words (the sample above includes `deploy`).
+
+## Source
 
 | File | Purpose |
 |------|---------|
-| `.synapse/commands` | Star-command rule definitions (L7) |
-| `.claude/commands/synapse/manager.md` | CRUD command router |
-| `.claude/commands/synapse/tasks/*.md` | Individual CRUD task workflows |
-| `.claude/commands/synapse/templates/` | Domain and manifest templates |
-| `.claude/commands/synapse/utils/manifest-parser-reference.md` | Parser format reference |
+| `.claude/hooks/synapse-engine.cjs` | The engine entry point (`main`) + `compose`. |
+| `.claude/settings.json` | Wires the `UserPromptSubmit` hook. |
+| `.synapse/manifest` | The budget/handoff scalars. |

package/payload/.claude/skills/synapse/references/domains.md

@@ -1,126 +1,62 @@
-# SYNAPSE Domains Reference
+# SYNAPSE domains & rule files
 
-## What is a Domain?
+A domain is a small `KEY=VALUE` file of rules that SYNAPSE injects into prompts. Each domain is
+registered in `.synapse/manifest` and its rules live in a sibling file `.synapse/<domain>` (the
+lowercased prefix). The engine reads them on every `UserPromptSubmit`.
 
-A domain is a text file containing KEY=VALUE rules that SYNAPSE injects into prompts. Each domain maps to a specific layer (L0-L7) and is registered in the manifest file (`.synapse/manifest`).
+## The kinds of domain
 
-Domains live in `.synapse/` and use a simple KEY=VALUE format with comments.
+| Kind | How it fires | Manifest | Seeded example |
+|------|--------------|----------|----------------|
+| Constitution | always; never trimmed | `CONSTITUTION_STATE=active`, `_ALWAYS_ON=true` | sourced from `.claude/constitution.md` |
+| Always-on (L1) | every prompt | `<DOMAIN>_STATE=active`, `_ALWAYS_ON=true` | `global`, `pipeline` |
+| Keyword-recall (L6) | when a trigger word is in the prompt | `<DOMAIN>_STATE=active`, `_RECALL=word,...` | `routing` |
 
-## Domain Types by Layer
+The constitution is the one special case: it has no `.synapse/` file — its body is rendered from
+`.claude/constitution.md`.
 
-| Layer | Type | Trigger | Example Files |
-|-------|------|---------|---------------|
-| L0 | Constitution | Always active (`ALWAYS_ON=true`, `NON_NEGOTIABLE=true`) | `constitution` |
-| L1 | Global | Always active (`ALWAYS_ON=true`) | `global`, `context` |
-| L2 | Agent-scoped | Active agent matches `AGENT_TRIGGER` | `agent-dev`, `agent-qa`, `agent-architect` |
-| L3 | Workflow-scoped | Active workflow matches `WORKFLOW_TRIGGER` | `workflow-sdc`, `workflow-qa-loop` |
-| L4 | Task context | Active task detected in session | (injected dynamically) |
-| L5 | Squad discovery | Squad is active in session | (squad domains) |
-| L6 | Keyword (RECALL) | User prompt contains keyword from `RECALL` field | (keyword-triggered domains) |
-| L7 | Star-commands | User types `*command` in prompt | `commands` |
+## Rule-file format
 
-## KEY=VALUE Format
+Rules are `<DOMAIN>_RULE_<N>=text` lines, where `<DOMAIN>` is the uppercase prefix and `<N>` orders
+the rules ascending. Blank lines and `#` comments are ignored.
 
-### Syntax Rules
-
-```
-# Comments start with #
-# Empty lines are ignored
-
-# Keys use SCREAMING_SNAKE_CASE with domain prefix
-DOMAINPREFIX_RULE_0=First rule text
-DOMAINPREFIX_RULE_1=Second rule text
-
-# Grouped comments describe rule sections
-# [section-name] COMMAND:
-#   0. First behavior
-#   1. Second behavior
-```
-
-### Key Naming Convention
-
-```
-{DOMAIN_KEY}_RULE_{INDEX}={RULE_TEXT}
-```
-
-- `DOMAIN_KEY`: Unique prefix matching manifest registration (e.g., `CONSTITUTION`, `GLOBAL`, `AGENT_DEV`)
-- `RULE`: Literal word `RULE` (or `STATE`, `ALWAYS_ON`, etc. for manifest keys)
-- `INDEX`: Zero-based integer or descriptive suffix
-- `RULE_TEXT`: Plain text rule content
-
-### Example: Agent Domain
-
-```
-# SYNAPSE Agent Domain: @dev (L2)
-# Agent-scoped rules for developer agent
-# Source: .aiox-core/development/agents/dev.md
-
-AGENT_DEV_RULE_0=Follow story tasks sequentially — read task, implement, test, mark [x]
-AGENT_DEV_RULE_1=ONLY update Dev Agent Record sections in story files
-AGENT_DEV_RULE_2=Run CodeRabbit pre-commit review before marking story complete
 ```
-
-### Example: Workflow Domain
-
+# .synapse/global  (always-on, L1)
+GLOBAL_RULE_0=git push, PR creation, and release tags are deliberate acts held behind a confirmation flag (anti-accidental-push) — `devops` is a dispatch-phase label, not an authority.
+GLOBAL_RULE_1=The unit of work is an issue with explicit acceptance criteria.
+GLOBAL_RULE_2=Before building, apply the decision hierarchy: REUSE > ADAPT > CREATE.
 ```
-# SYNAPSE Workflow Domain: Story Development (L3)
-
-WORKFLOW_SDC_RULE_0=Follow SDC phases: Create → Validate → Implement → QA Gate
-WORKFLOW_SDC_RULE_1=Update story checkboxes as tasks complete
-```
-
-## Manifest Registration
-
-Every domain must be registered in `.synapse/manifest`. The manifest uses the same KEY=VALUE format:
 
-### Required Manifest Keys
+At assembly the rules render as a numbered section headed by the domain — `[GLOBAL]` for an
+always-on domain, `[RECALL: routing]` for a recall domain.
 
-| Key | Purpose | Example |
-|-----|---------|---------|
-| `{PREFIX}_STATE` | Domain active state (`active` or `inactive`) | `AGENT_DEV_STATE=active` |
+## The seeded domains
 
-### Optional Manifest Keys
+| File | Kind | What it carries |
+|------|------|-----------------|
+| `.synapse/global` | always-on | WRXN operational invariants (devops-only push, issue-driven work, the decision hierarchy, conventional commits, the green-suite push gate). |
+| `.synapse/pipeline` | always-on | The unified-dev build route and how to scale it to the task. |
+| `.synapse/routing` | keyword-recall | Representative recall rules (worktrees, deploys, the unit of work). |
 
-| Key | Purpose | Example |
-|-----|---------|---------|
-| `{PREFIX}_ALWAYS_ON` | Domain always loaded (L0, L1) | `CONSTITUTION_ALWAYS_ON=true` |
-| `{PREFIX}_NON_NEGOTIABLE` | Cannot be overridden (L0 only) | `CONSTITUTION_NON_NEGOTIABLE=true` |
-| `{PREFIX}_AGENT_TRIGGER` | Activate when agent matches (L2) | `AGENT_DEV_AGENT_TRIGGER=dev` |
-| `{PREFIX}_WORKFLOW_TRIGGER` | Activate when workflow matches (L3) | `WORKFLOW_SDC_WORKFLOW_TRIGGER=sdc` |
-| `{PREFIX}_RECALL` | Keywords that trigger domain (L6) | `MYLIB_RECALL=react,hooks` |
-| `{PREFIX}_EXCLUDE` | Agents/contexts to exclude from | `MYLIB_EXCLUDE=qa` |
+`global` and `pipeline` are managed (kernel-owned, overwritten on `wrxn update`). `routing` is seeded
+— operator-owned, created once at init and never overwritten on update. Edit `routing` freely; add
+your own recall rules there.
 
-### Current Manifest Domains
-
-The manifest at `.synapse/manifest` registers:
-- 1 Constitution domain (L0, NON_NEGOTIABLE, ALWAYS_ON)
-- 2 Global domains (L1, ALWAYS_ON): `global`, `context`
-- 1 Commands domain (L7): `commands`
-- 12 Agent domains (L2): one per core agent (`agent-dev`, `agent-qa`, etc.)
-- 4 Workflow domains (L3): `sdc`, `qa-loop`, `spec`, `brownfield` (triggers; keys `WORKFLOW_SDC`, `WORKFLOW_QA_LOOP`, `WORKFLOW_SPEC`, `WORKFLOW_BROWNFIELD`)
-
-## Creating Custom Domains
-
-Use the CRUD command to create a new domain:
-
-```
-*synapse create
-```
+## Adding a domain
 
-This will:
-1. Ask for domain name, layer, and description
-2. Create the domain file in `.synapse/`
-3. Add the manifest entry to `.synapse/manifest`
-4. Validate the format is parseable by domain-loader
+There is no interactive creator — add a domain by editing two files:
 
-For the domain file template, see: `.claude/commands/synapse/templates/domain-template`
+1. Create `.synapse/<name>` with `<NAME>_RULE_0=...` lines.
+2. Register it in `.synapse/manifest`:
+   - always-on: `<NAME>_STATE=active` and `<NAME>_ALWAYS_ON=true`.
+   - keyword-recall: `<NAME>_STATE=active` and `<NAME>_RECALL=word1,word2`.
 
-For the manifest entry template, see: `.claude/commands/synapse/templates/manifest-entry-template`
+See [the manifest format](manifest.md) and the [templates](../assets/README.md).
 
-## Source Files
+## Source
 
 | File | Purpose |
 |------|---------|
-| `.synapse/manifest` | Central domain registry |
-| `.synapse/*` | Domain content files |
-| `.aiox-core/core/synapse/domain/domain-loader.js` | Domain parser (SYN-1) |
+| `.synapse/manifest` | Domain registry. |
+| `.synapse/<domain>` | The rule files. |
+| `.claude/hooks/synapse-engine.cjs` | `domainRules` / `renderRulesSection` read + render them. |