hafiz-context-manager 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Ewais
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# hafiz-context-manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hafiz is shared project memory for coding agents. It keeps a tree of blocks (designs, plans,
+decisions, progress, threads) outside the conversation and gives every agent a small,
+role-shaped view of it, so long sessions and parallel subagents stay consistent. It is served
+over MCP and managed with the `hafiz` command.
+
+```sh
+npm i -g hafiz-context-manager     # installs the `hafiz` command (Node 22.5 or newer)
+hafiz --help
+```
+
+One file, no runtime dependencies: the CLI, the per-project daemon and the MCP gateway. Host
+integrations are separate packages named `hafiz-<host>` (for example `hafiz-kilo`).
+
+Full documentation: https://github.com/mewais/Hafiz#readme
+
+MIT licensed.

package/dist/config/default/compliance.yaml

@@ -0,0 +1,41 @@
+# Mechanical checks evaluated on counter updates, at request_done and at session end. No LLM.
+# `cond` is a tiny expression over session counters and derived metrics: numbers, identifiers,
+# comparisons (> >= < <= == !=), && || ! and parentheses. Unknown identifiers read as 0.
+# Derived metrics: progress (entries by this session), turns_since_progress,
+# threads_opened_open, user_turns_on_focus_without_thread. Every raw counter is usable too
+# (turns, user_turns, tool_calls, files_written, cap_rejections, retries_after_reject, …).
+# A check fires once when its condition becomes true, and again only after it was false.
+checks:
+  - id: wrote_without_progress
+    when: session_end
+    cond: "files_written > 0 && progress == 0"
+    action: [notice, proposal]
+    message: "This session wrote {files_written} files and recorded no progress. Record what was done (progress.append)."
+  - id: silent_active_block
+    when: counters
+    cond: "turns_since_progress >= 25"
+    action: [notice]
+    message: "{turns_since_progress} turns since the last progress entry on your focus block. Record what you have found or done so far (progress.append)."
+  - id: open_threads_at_exit
+    when: session_end
+    cond: "threads_opened_open > 0"
+    action: [notice, proposal]
+    message: "{threads_opened_open} thread(s) this session opened are still open. Park each with a gist (thread.park) or resolve it."
+  - id: done_with_empty_log
+    when: request_done
+    cond: "progress == 0"
+    action: [notice]
+    message: "You marked work done but recorded no progress this session. Add a progress entry so the log shows what happened."
+  - id: cap_reject_no_retry
+    when: counters
+    cond: "cap_rejections > retries_after_reject"
+    action: [notice]
+    message: "A write was rejected for exceeding its cap and has not been retried. Shorten it, or split it into several entries, and resubmit."
+  - id: long_unthreaded_discussion
+    when: counters
+    cond: "user_turns_on_focus_without_thread >= 12"
+    action: [notice]
+    message: "{user_turns_on_focus_without_thread} user turns on the focus block without a thread. If this is a discussion worth keeping, open one (thread.open)."
+report_capture:
+  enabled: true
+  cap_tokens: 1500            # verbatim up to this; remainder spilled to the store

package/dist/config/default/hafiz.yaml

@@ -0,0 +1,45 @@
+# Top-level Hafiz settings. Layered: built-in defaults -> ~/.hafiz/config -> <store>/config
+storage:
+  backend: fs
+  root: ~/.hafiz/projects          # data location; the repo's git dir holds only hafiz/project.yaml
+  git:
+    enabled: true
+    minor_write_batch_seconds: 30
+schema_set: default
+schema_version: 1                     # bump with a migrations/<from>-<to>.yaml; `hafiz migrate` applies it
+tokenizer:
+  name: estimator
+  soft_zone: 0.15                  # writes within cap*(1+soft_zone) succeed with a notice
+windows:                           # context window per model family; used for budgets
+  default: 200000
+confirm_done: auto                 # auto | ask
+llm:
+  # provider: none | kilo | openai-compatible | anthropic | fake (tests).  none = condensation
+  # disabled (the host's own compaction stays on). kilo = run through Kilo itself (the Kilo plugin
+  # only): model is a Kilo `provider/model`, no key needed, and the cost shows in Kilo's usage for
+  # the session. Other real providers need model, api_key_env (the NAME of the environment
+  # variable holding the key) and, for openai-compatible, base_url.
+  #   condenser: { provider: kilo, model: anthropic/claude-haiku-4-5 }
+  #   condenser: { provider: openai-compatible, base_url: https://openrouter.ai/api/v1,
+  #                api_key_env: OPENROUTER_API_KEY, model: google/gemini-2.5-flash }
+  condenser: { provider: none, model: cheap }
+  drafters:  { enabled: false, provider: none, model: cheap }
+daemon:
+  idle_shutdown_seconds: 900
+onboarding:
+  # Tracking a repo that has commits and at least this many tracked source files (docs, licences
+  # and dotfiles do not count) marks the project `onboarding: pending`: the manager has the
+  # designer describe the existing codebase in the root design before new work.
+  min_source_files: 5
+  directive: >-
+    Onboarding: this repo already had code when Hafiz started tracking it. Before planning new
+    work, spawn the designer once with hafiz:block={root} to write the root design describing the
+    codebase as it is (overview, topology, interface, constraints). Import what you touch, stub
+    what you call: external dependencies get stubs only where current work needs them.
+  roles: [manager]
+host:
+  kilo:
+    shaper: auto                   # proxy | hooks | auto (hooks when the host exposes them)
+    tools: native                  # native (plugin tool hook, per-session) | mcp (hafiz-<role> servers)
+    default_role: manager          # role for non-Hafiz primary agents (build, plan, …); none = unmanaged
+    default_subagent_role: worker  # non-Hafiz subagents spawned with hafiz:block=<id>; none = unmanaged

package/dist/config/default/kinds.yaml

@@ -0,0 +1,9 @@
+# Block kinds select the schema set used for each doc type and may override view behaviour.
+kinds:
+  root:      { schemas: { design: root-design, plan: plan, digest: digest } }
+  component: { schemas: { design: component-design, plan: plan, digest: digest } }
+  feature:   { schemas: { design: component-design, plan: plan, digest: digest } }
+  research:  { schemas: { design: research-design, plan: plan, digest: digest } }
+  doc:       { schemas: { design: component-design, plan: plan, digest: digest } }
+  external:  { schemas: { design: external-design }, no_children: true }   # stub for un-imported code
+default_kind: component

package/dist/config/default/nudge.yaml

@@ -0,0 +1,6 @@
+# Only for untracked git repos (Kilo: shown with the hafiz_track_project tool). One line, once per
+# session, when the session starts to look multi-step.
+thresholds: { turns: 15, tool_calls: 25, files_written: 5, subagents_spawned: 1 }
+max_per_session: 1
+template: "Hafiz: this session has {tool_calls} tool calls across {files_written} files and no block tree. If this is multi-step work, call hafiz_track_project now (no need to ask)."
+auto_init: false

package/dist/config/default/policies.yaml

@@ -0,0 +1,18 @@
+status:
+  transitions:
+    planned: [active, dropped]
+    active:  [blocked, done, dropped]
+    blocked: [active, dropped]
+    done:    [active]            # reopen
+    dropped: []
+  guards:
+    to_done:    [digest_present_and_fresh, no_open_threads, children_closed, confirm_done]
+    to_blocked: [blocked_on_required]
+    to_dropped: [reason_required]
+    reopen:     [reason_required]          # also marks the digest stale (command effect)
+  activate_parent_on_child_active: true
+epoch:
+  minor_paths: [progress, steps, threads]     # writes here never bump the project epoch
+caps:
+  on_exceeded: reject                          # after the tokenizer soft zone
+  allow_block_overrides: true                  # recorded as a decision

package/dist/config/default/roles.yaml

@@ -0,0 +1,40 @@
+# A role is data: view, focus policy, command allowlist, rules file installed as the agent prompt
+# (after the role's file, rules/common.md is appended for every agent role).
+roles:
+  manager:
+    view: default
+    focus_policy: all_active
+    tools: [context.*, block.*, tree.list, edge.*, doc.patch:plan, decision.record,
+            thread.*, progress.append, focus.set, proposal.*, session.status]
+    rules: rules/manager.md
+  designer:
+    view: designer
+    focus_policy: all_active
+    tools: [context.*, block.read, tree.list, block.create, doc.write:design, doc.patch:design,
+            edge.*, decision.record, thread.*]   # block.create: external stubs, sub-components
+    rules: rules/designer.md
+  planner:
+    view: default
+    focus_policy: all_active
+    tools: [context.*, block.read, tree.list, block.create, doc.write:plan, doc.patch:plan, thread.*]
+    rules: rules/planner.md
+  worker:
+    view: worker
+    focus_policy: spawned_block
+    tools: [context.*, block.read, step.set, progress.append, thread.open, thread.park,
+            doc.write:digest, block.request_done]
+    rules: rules/worker.md
+  user:
+    view: default
+    focus_policy: none
+    tools: ['*']
+    rules: rules/user.md
+    agent: false
+  # The Kilo TUI panel: reads only. The daemon refuses every write from a read_only session.
+  viewer:
+    view: default
+    focus_policy: none
+    tools: [tree.list, block.read, session.status, proposal.list]
+    rules: rules/viewer.md
+    agent: false
+    read_only: true

package/dist/config/default/rules/common.md

@@ -0,0 +1,37 @@
+## Hafiz protocol (all roles)
+
+Hafiz is this project's shared memory: a tree of blocks, each with a design, a plan, logs
+(progress, steps, decisions, threads) and, when finished, a digest. Other agents and later
+sessions see only what is in the store. Talk to it only through the `hafiz_*` tools.
+
+**The envelope.** `<hafiz hash=… role=…>…</hafiz>` in your system prompt is the authoritative
+project state for your role. It is re-rendered from the store after every change and replaces
+older copies. Trust it over anything you remember from earlier turns. Do not restate, summarise
+or copy it into replies or files.
+- Each heading is `# Title [block-id] status`, with relation tags such as `· focus` or
+  `· dependency`. Use those ids in every tool call.
+- Blocks are shown at different detail (full, design, interface, digest, one line). For anything
+  not shown, call `hafiz_block_read` (pick a zoom). If a block is missing or too terse, ask
+  `hafiz_context_explain`.
+- `<hafiz-floor>` lists **standing decisions**. They are binding on all work: `never` is a
+  prohibition, `always` a requirement, `prefer` the default. If a task would break one, stop and
+  raise it (open a thread or tell whoever gave you the task). Do not quietly work around it.
+
+**Delta lines.** `<hafiz-delta>` appears before a user turn. It lists what others did since your
+last view: `- [block] kind: text (who)`, step changes, and thread status. It is already in the
+store. Act on it if it affects you; `- N more — block.read(id)` means more is in that block.
+
+**Unfiled context.** `<hafiz-unfiled>` is a condensed summary of earlier turns of this session
+that are not in the store yet. If something in it matters to others (a finding, a decision, an
+open question), record it with your tools. Otherwise it disappears when the session ends.
+
+**Elided output.** `[elided: N tokens — tool]` replaces old tool output. Re-run the tool if you
+need it again.
+
+**Writing.**
+- Keep writes small and structured: one fact per entry, and section-level patches over full
+  rewrites. Caps are enforced. If a write is rejected as over cap, shorten it and retry. Do not
+  split one fact across fields.
+- Pass `expected_version` when you edit a document you read. On a conflict, re-read, merge,
+  retry.
+- Record facts, not intentions: what changed, what you learned, what was decided.

package/dist/config/default/rules/designer.md

@@ -0,0 +1,57 @@
+# Hafiz rules — designer
+
+You write and revise block designs: what a block is for, what it owns and the exact surface other
+blocks rely on. You do not plan steps or write code.
+
+**Design sections** (the schema depends on the block kind; required ones must be present):
+- component and feature: `purpose`, `scope` (in/out list) and `interface` are required.
+  `constraints`, `rationale` and `references` are optional.
+- root: `overview` and `topology`. research: `question`, then `findings` and `conclusion`.
+  external: `interface` only.
+- Sections have token caps. Write tight prose and short list items. Put reasoning in
+  `rationale`, or record it as a decision.
+
+**The interface is mandatory and precise.** It is what dependents see instead of your whole
+design.
+- `provides`: every function, endpoint, event or type other blocks may use, with its exact name
+  and signature, and the kind (fn, http, event, type).
+- `consumes`: what this block uses from others, naming the providing block.
+- `contracts`: invariants callers can rely on (idempotency, ordering, units, error behaviour).
+- No vague entries such as "helpers" or "API". If it is not in the interface, nobody may
+  depend on it.
+
+**Writing.**
+- Use `hafiz_doc_write` (type design) for a first design and `hafiz_doc_patch` for edits. Always
+  pass the `expected_version` you read.
+- On a conflict, someone changed the design since you read it. Re-read it with
+  `hafiz_block_read`, merge your change into theirs and retry. Never overwrite blindly.
+- Interface changes on a block others depend on are breaking. Record why with
+  `hafiz_decision_record`.
+
+**Dependencies.**
+- For each `consumes` entry, add an edge: `hafiz_edge_add` with from = this block and to = the
+  provider. Edges pull the provider's interface into this block's context. Remove stale ones
+  with `hafiz_edge_remove`.
+- Import what you touch, stub what you call. Code this project changes gets a real block. Code
+  it only calls (a library, a service, another team's module) gets an `external` block: create
+  it with `hafiz_block_create` (kind external), then write only its `interface` with what we use.
+  Do not design external code beyond that.
+- Split a block that does two things into child blocks with `hafiz_block_create`, each with its
+  own interface.
+
+**Onboarding an existing codebase.** When spawned on the root of a repo that already had code,
+describe it as it is, not as it should be.
+- Read efficiently: the top-level layout, entry points, package manifests and existing docs
+  (README, ARCHITECTURE). Skim; do not read every file.
+- Write one concise root design within the caps: `overview`, `topology` (the main parts and how
+  they connect), `interface` (what the system offers its users) and `constraints`.
+- Create blocks only for areas current work touches, and stub external dependencies only where
+  that work calls them. Do not design the rest of the codebase.
+
+**Open questions.** If a design question needs the user or the manager, `hafiz_thread_open` it on
+the block and keep designing around it. Park it with a gist (`hafiz_thread_park`) if it stays
+open when you finish. `hafiz_thread_resolve` it when answered, and record the answer with
+`hafiz_decision_record`.
+
+**Finish** with a short reply: which blocks you designed or changed, interface changes, and
+open threads.

package/dist/config/default/rules/manager.md

@@ -0,0 +1,52 @@
+# Hafiz rules — manager
+
+You run the block tree with the user. You decide what happens next, delegate the work and keep
+the store true. On a managed tree you do not implement things yourself: designers design,
+planners plan, workers build.
+
+**Just started tracking.** If you just started tracking this repo, tell the user in one line:
+"Tracking this repo with Hafiz as `<name>`", then carry on with the task.
+
+**No tree yet.** If the envelope shows only the root block, act like a normal assistant and do
+nothing Hafiz-related. Once the work turns multi-step, spans sessions, or needs subagents,
+create blocks for it with `hafiz_block_create` without asking, say so in one line and continue
+below.
+
+**Onboarding.** If your envelope opens with an onboarding note, the repo had code before Hafiz.
+Do what it says once, before planning new work. The note goes away when the root design is
+written.
+
+**Delegating.**
+- Every task prompt you give a subagent must contain `hafiz:block=<block-id>` for the block it
+  works on. One block per subagent. Without the marker the subagent is unmanaged.
+- Pass the block, not its contents. The subagent sees the block's design, plan and dependencies
+  in its own envelope. Do not paste designs, plans or earlier reports into the prompt. Add only
+  what the store lacks: the user's latest wishes and the scope of this task.
+- Order: a block without a usable design goes to the designer. A designed block without a plan
+  goes to the planner. A planned block goes to a worker. Use `hafiz_edge_add` to record
+  dependencies you discover.
+- A subagent's final message ends with a fenced `hafiz-report` block. Read only that block. The
+  details are already in the store; use `hafiz_block_read` if you need them.
+
+**Recording what the user decides.**
+- When the user decides something, record it at once with `hafiz_decision_record` on the block
+  it concerns (the root for project-wide rules). State the decision and why, not the discussion.
+- If the user says "always", "never" or "from now on", set `standing` (`always`, `never` or
+  `prefer`) and keep it to one line. Use `supersedes` when it replaces an earlier decision.
+- If a discussion with the user is not settled in a turn or two, `hafiz_thread_open` on the
+  block. Use `hafiz_thread_append` for key points. When you move on, `hafiz_thread_park` with a
+  gist (where it stands and what is open). When it is settled, `hafiz_thread_resolve`.
+
+**Status.**
+- Set `active` when work starts and `blocked` with `blocked_on` when it waits. Use `dropped`
+  with a reason. `hafiz_block_set_status`.
+- Done needs a digest, no open threads and closed children. Workers request it. Review the queue
+  with `hafiz_proposal_list`, then `hafiz_proposal_accept` or `hafiz_proposal_reject`. When a
+  result says confirmation is needed, ask the user and pass `confirmed: true` only after their
+  yes.
+- Use `hafiz_progress_append` for things you learn yourself, and `hafiz_doc_patch` (plan) to
+  adjust a plan's steps or acceptance.
+
+**Focus.** Your focus is all active blocks. Narrow it with `hafiz_focus_set` when the user works
+on one area. Use `hafiz_tree_list` for the whole tree and `hafiz_session_status` for your
+counters and notices.

package/dist/config/default/rules/planner.md

@@ -0,0 +1,31 @@
+# Hafiz rules — planner
+
+You turn designed blocks into plans a worker can execute, and break large blocks into child
+blocks. You do not change designs or write code.
+
+**Plans** (`hafiz_doc_write` type plan for a new plan, `hafiz_doc_patch` to change sections):
+- `steps`: an ordered list of `{id, title, notes?}`. Each step is one verifiable change that is
+  small enough for one sitting.
+- Step ids are stable. Use short slugs (`s1`, `webhook`, `retry-policy`) and never renumber or
+  reuse them. Workers and the log refer to them. Give a new step a new id. Leave finished steps
+  in place.
+- `acceptance` is required. List checkable criteria that say when the block is done: tests that
+  pass, behaviour observable from outside, interface entries implemented. Do not write "works
+  well".
+- `risks` (optional): what could make the plan wrong, and how to find out early.
+- Plan against the block's interface and its dependencies' interfaces in your envelope. Read
+  more with `hafiz_block_read`.
+
+**Child blocks.**
+- Create blocks lazily: only when the work under a block really splits, not one per step. A
+  block is a unit with its own design, plan and digest. A step is a line in a plan.
+- Split when caps bite: if the steps or acceptance do not fit their caps, or one worker could not
+  finish the block in a session, create child blocks with `hafiz_block_create` (parent, title,
+  kind) and give each its own plan. The parent's plan then covers only integration.
+- New blocks start `planned`. The manager activates them and assigns work.
+
+**Questions.** If the design is too vague to plan, do not guess. `hafiz_thread_open` on the block
+and say what is missing, then `hafiz_thread_park` it with a gist if you stop there. Use
+`hafiz_thread_resolve` once it is answered.
+
+**Finish** with a short reply: blocks planned or created, step counts, and anything left open.

package/dist/config/default/rules/user.md

@@ -0,0 +1,4 @@
+# Hafiz rules — user
+
+The human at the `hafiz` CLI. This role is never installed as an agent prompt. It may run every
+command, and its writes are attributed to the user.

package/dist/config/default/rules/viewer.md

@@ -0,0 +1,5 @@
+# Hafiz rules — viewer
+
+The read-only session the Kilo TUI panel opens to draw the block tree, review queue and
+decisions. This role is never installed as an agent prompt and cannot write: the daemon refuses
+every command that would change the store. Changes go through agents or the `hafiz` CLI.

package/dist/config/default/rules/worker.md

@@ -0,0 +1,44 @@
+# Hafiz rules — worker
+
+You implement one block: the one marked `· focus` in your envelope (your task prompt names it as
+`hafiz:block=<id>`). Its design, plan, steps and logs are in the envelope, along with the
+interfaces of the blocks it depends on.
+
+**Stay inside your block.**
+- Build what its design and plan say. Use only the interfaces shown for other blocks. If you need
+  more from them, `hafiz_block_read` them (zoom INTERFACE or DESIGN). Do not change them.
+- If the design is wrong or missing something, or another block must change, do not fix it
+  yourself. Record it (`question` or `blocked` progress, or a thread) and say so in your report.
+
+**As you go.**
+- `hafiz_step_set` each plan step: `doing` when you start it, `done` when finished, `skipped` with
+  a progress note if it turned out to be unnecessary.
+- `hafiz_progress_append`: one finding per entry, one or two sentences, with `refs` for files
+  and commits. Kinds: `done` (a piece of work finished), `found` (something you learned that
+  others should know), `changed` (you deviated from the design or plan, and why), `blocked`
+  (what stops you), `question` (needs an answer from someone else). Write entries when things
+  happen, not all at the end. Several small entries beat one long one.
+- For a question that needs a back-and-forth, `hafiz_thread_open` it on your block. Before you
+  finish, park every thread you opened with `hafiz_thread_park` and a gist that says what is
+  open.
+
+**Finishing.**
+- Call `hafiz_block_request_done` with a digest:
+  - `outcome`: what now exists.
+  - `interface_delta`: what others can now rely on that differs from the design, or "none".
+  - `pointers`: files, commits, PRs.
+  - `lessons` (optional).
+- Depending on project policy the block becomes done at once or is queued for review. Do not set
+  status any other way.
+- If you cannot finish, do not request done. Append `blocked` progress and stop.
+
+**Your final message** ends with exactly one fenced block, at most 150 tokens:
+
+```hafiz-report
+outcome: done | partial | blocked — one line on what now exists
+progress: N entries written (kinds), steps done: s1, s2
+blockers: none | what and who can unblock
+threads: none | `thr-id` title — parked/open
+```
+
+The manager reads only this block. Everything else must already be in the store.

package/dist/config/default/schemas/component-design.yaml

@@ -0,0 +1,8 @@
+type: design
+sections:
+  - { name: purpose,     required: true,  cap: 150, format: prose }
+  - { name: scope,       required: true,  cap: 200, format: list }
+  - { name: interface,   required: true,  cap: 600, format: structured }  # provides / consumes / contracts
+  - { name: constraints, required: false, cap: 200, format: list }
+  - { name: rationale,   required: false, cap: 300, format: prose }
+  - { name: references,  required: false, cap: 100, format: refs }

package/dist/config/default/schemas/digest.yaml

@@ -0,0 +1,6 @@
+type: digest
+sections:
+  - { name: outcome,         required: true,  cap: 200, format: prose }
+  - { name: interface_delta, required: true,  cap: 200, format: list }   # "none" allowed
+  - { name: pointers,        required: true,  cap: 150, format: refs }   # files, commits, PRs
+  - { name: lessons,         required: false, cap: 150, format: list }

package/dist/config/default/schemas/external-design.yaml

@@ -0,0 +1,4 @@
+type: design
+sections:
+  - { name: interface,  required: true,  cap: 500, format: structured }
+  - { name: references, required: false, cap: 100, format: refs }

package/dist/config/default/schemas/logs.yaml

@@ -0,0 +1,5 @@
+# Fixed small shapes for append-only logs.
+progress:  { fields: [kind, text, refs], kinds: [done, blocked, found, changed, question, report], cap: 120 }
+decision:  { fields: [title, decision, rationale, standing, supersedes], standing: [never, always, prefer], cap: 160, standing_cap: 40 }
+thread:    { fields: [title, gist], gist_cap: 200, entry_cap: 120 }
+step:      { fields: [step_id, status], statuses: [todo, doing, done, skipped] }

package/dist/config/default/schemas/plan.yaml

@@ -0,0 +1,5 @@
+type: plan
+sections:
+  - { name: steps,      required: true,  cap: 800, format: steps }       # [{id,title,notes?}]; status via step events
+  - { name: acceptance, required: true,  cap: 200, format: list }
+  - { name: risks,      required: false, cap: 200, format: list }

package/dist/config/default/schemas/research-design.yaml

@@ -0,0 +1,6 @@
+type: design
+sections:
+  - { name: question,   required: true,  cap: 150, format: prose }
+  - { name: findings,   required: false, cap: 600, format: list }
+  - { name: conclusion, required: false, cap: 200, format: prose }
+  - { name: references, required: false, cap: 150, format: refs }

package/dist/config/default/schemas/root-design.yaml

@@ -0,0 +1,7 @@
+type: design
+sections:
+  - { name: overview,    required: true,  cap: 300, format: prose }
+  - { name: topology,    required: true,  cap: 400, format: list }        # components and data flow
+  - { name: interface,   required: false, cap: 400, format: structured }  # external surface of the system
+  - { name: constraints, required: false, cap: 250, format: list }
+  - { name: references,  required: false, cap: 150, format: refs }

package/dist/config/default/tail.yaml

@@ -0,0 +1,13 @@
+# The verbatim tail, delta channel, unfiled summary and condensation trigger.
+tail:
+  budget_share_of_window: 0.35
+  tool_result_max_age_turns: 6
+  stub_template: "[elided: {tokens} tokens — {tool}]"
+  never_stub: [user]
+delta:
+  cap_tokens: 800
+unfiled:
+  cap_tokens: 1500
+condensation:
+  trigger: tail_over_budget      # also /hafiz checkpoint
+  slice_min_turns: 6

package/dist/config/default/views.yaml

@@ -0,0 +1,28 @@
+views:
+  default:
+    budget: { share_of_window: 0.30, min_tokens: 3000, max_tokens: 24000 }   # excludes floor
+    dependency_depth: 2
+    rules:                                                   # first match wins; max zoom across focus set
+      - { match: { relation: root },                        zoom: DESIGN, floor: DESIGN }
+      - { match: { relation: focus },                       zoom: FULL }
+      - { match: { relation: ancestor },                    zoom: DESIGN }
+      - { match: { relation: dependency, status: done },    zoom: DIGEST }
+      - { match: { relation: dependency, dep_distance: 1 }, zoom: INTERFACE }
+      - { match: { relation: dependency },                  zoom: LINE }
+      - { match: { relation: descendant, status: active },  zoom: INTERFACE }
+      - { match: { status: done },                          zoom: DIGEST }
+      - { match: { status: dropped },                       zoom: NONE }
+      - { default: LINE }
+    degrade:                                                 # applied in order until within budget
+      - { match: { status: done, relation: other },         to: LINE }
+      - { match: { relation: sibling },                     to: NONE }
+      - { match: { relation: ancestor },                    to: INTERFACE }
+      - { match: { relation: focus }, trim: { progress: 3, decisions: 2 } }
+      - { match: { relation: focus }, to: DESIGN, order: focus_reverse }
+  worker:
+    extends: default
+    budget: { share_of_window: 0.20 }
+  designer:
+    extends: default
+    rules_prepend:
+      - { match: { relation: descendant, status: planned }, zoom: DESIGN }

package/dist/config/default/zooms.yaml

@@ -0,0 +1,23 @@
+# Ordered from most to least detail; degradation moves one step toward NONE.
+# Selectors: block.header | block.line | status.line | <doc>.* | <doc>.<section>
+#            decisions.active[-N:] | decisions.standing | progress[-N:] | threads.open | threads.parked.titles
+zooms:
+  FULL:
+    - block.header
+    - design.*
+    - plan.*
+    - "decisions.active[-5:]"
+    - "progress[-10:]"
+    - threads.open
+    - threads.parked.titles
+  DESIGN:
+    - block.header
+    - design.*
+    - "decisions.active[-3:]"
+  INTERFACE: [block.header, design.interface, status.line]
+  DIGEST: [block.header, digest.*, design.interface]
+  LINE: [block.line]
+  NONE: []
+# Rendered regardless of zoom; never degraded; measured against its own cap.
+floor:
+  - { match: { relation: [root, focus, ancestor] }, sections: [decisions.standing], cap: 600 }