@caupulican/pi-adaptative 0.90.12 → 0.91.2

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [0.91.2] - 2026-08-15
+
+## [0.91.1] - 2026-08-15
+
+### Added
+
+- Host-owned `pipeline` tool walks numbered folder stages (ICM): status is `output/` files, increment completes the current stage then starts the next. `task_steps advance` and `goal increment` share that complete-current-then-start-next verb. Goal complete refuses an active pipeline; pipeline increment refuses linked open task_steps and running `tool_task`s. Current-stage context is injected as a GC-managed `<pipeline_context>` page. Workers and lean models cannot activate `pipeline`. The bundled `icm-architect` skill is the authoring method for building a workspace; the runtime does not name it from the tool.
+
+## [0.91.0] - 2026-08-14
+
+### Breaking Changes
+
+- Omitted worker `forkTurns` now defaults to self-contained birth context (`none`) even for same-provider/model root workers. Set `forkTurns` to `all` or a positive turn count to inherit sanitized parent turns.
+- Repository `AGENTS.md`/`CLAUDE.md`/`GEMINI.md` stay off until a settings layer sets `projectContextFiles` to `"on-demand"`, which lists paths only. They are not injected. Global `~/.pi/agent` context files remain mandatory. `--no-context-files` no longer disables the global file.
+
+### Changed
+
+- Packed tool output and truncated bash/python model previews now keep a head+tail window so first hits and terminal errors both survive. Live TUI preview stays tail-only. Full output is still saved to the artifact or managed file.
+- Repository `AGENTS.md` loading is opt-in per directory. Default is global `~/.pi/agent` files only. `/settings` → Project AGENTS.md enables listing this project's files or keeps global-only; save per directory, project, or all projects.
+- Collapsed file edits no longer dump the full diff. Consecutive edit/write calls group into a count, a 2–3 file snippet, and the last successful action; `Ctrl+O` expands the full list. Thinking blocks are hidden by default (`hideThinkingBlock`, `Ctrl+T` to show).
+- Collapsed tool groups use human nouns: Task Step(s), Skill(s), Worker(s). Skill, Skillify, and Skill Audit share one skills group.
+- Worker terminals that need parent review no longer interrupt the owner with Review now / Keep blocked. The parent agent wakes on the existing terminal handoff and decides via `delegate` status/review. The human stays on the edge: no blocking owner question is queued.
+- `Ctrl+O` only expands or collapses tool output. Deferred session history loads on `Ctrl+Shift+H` (`app.history.load`) so an expand never remounts the transcript.
+- Exported `loadProjectContextFiles()` now matches the live loader: default is global files only; `includeProject: true` lists project paths without injecting their bodies.
+- Long-term memory retrieval now consults a local durable graph when one is present on disk, so graph recall happens automatically on the next turn.
+- Wired built-in `memory`, `skillify`, `skill_audit`, and `improvement_loop` onto the default capable-session tool surface so they activate when the model/session can use them. Session create now initializes the bundled memory providers, so SDK sessions that never bind extensions still get the `memory` tool when the grant allows it. A `memory` write of a repeatable procedure now triggers reflection, and a clean `promote_skill` lands as a loadable skill under stock policy. An owner who enabled auto-apply and omitted `skill` still keeps that ceiling. Workers still cannot take the write/self-adaptation tools.
+- Goal, `task_steps`, and `tool_task` now share a live join: a still-running background tool cannot verify goal evidence, agent complete refuses while linked checklist steps or cited tool tasks remain open, and continuation waits on those running tasks.
+- A just-written or archived skill refreshes the live catalog, so `skill` search/load can use it in the same session without `/reload`.
+
+### Fixed
+
+- Goal start authority now accepts owner speech such as `this is a goal, use it` while still rejecting `goal-oriented` compounds and ordinary task text.
+- Failed goal actions, including unauthorized start, now return `isError` so tool-failure recovery can block unchanged retries in the same turn.
+- Failed `delegate` validation, API-correction, and start-skip results now return `isError` so unchanged retries are blocked instead of burning another worker turn.
+- Worker `delegate list` now marks which session peers the caller can control. Nested-limit guidance tells the model to reuse only `controllable=true` descendants, not siblings.
+- Nested worker start is rejected at admission when the tree already holds its `maxAttempts` ceiling, instead of returning started and dying before the first provider token.
+- Corrected the `delegate` `forkTurns` parameter description so omitted starts document `none`, matching the runtime default.
+- A worker tool denial for an exhausted token/cost/wall/tool budget now terminals the lane instead of blocking one call and letting the model retry other paths.
+
 ## [0.90.12] - 2026-08-14
 
 ### Fixed

package/README.md

@@ -238,8 +238,9 @@ See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`.
 | Ctrl+L | Open model selector |
 | Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |
 | Shift+Tab | Cycle thinking level |
-| Ctrl+O | Collapse/expand tool output |
-| Ctrl+T | Collapse/expand thinking blocks |
+| Ctrl+O | Expand or collapse tool output (edits stay as a count + short file list until then) |
+| Ctrl+Shift+H | Load deferred session history into the chat |
+| Ctrl+T | Show or hide thinking blocks (hidden by default) |
 
 ### Message Queue
 
@@ -329,14 +330,11 @@ Runtime orchestration, recovery, and learning telemetry stays local. See [docs/t
 
 ## Context Files
 
-Pi Adaptative discovers `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` context files at startup from:
-- `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` in `~/.pi/agent/` (global)
-- Parent directories (walking up from cwd)
-- Current directory
+Pi Adaptative discovers `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` context files from:
+- `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` in `~/.pi/agent/` (global) — always loaded into the system prompt
+- Parent directories and the current directory — listed by path after opt-in (`/settings` → Project AGENTS.md), then read on demand, not injected at startup
 
-Use these files for project instructions, conventions, common commands, and safety rules. Their contents are injected into the startup system prompt so every session starts with the active project context.
-
-Disable context file discovery with `--no-context-files` (or `-nc`).
+Use the global file for standing instructions. A repo `AGENTS.md` is off until you opt in for that directory: `/settings` → **Project AGENTS.md**. Then the agent sees the path and can read it. Set Load to **global-only** to keep only `~/.pi/agent`. `--no-context-files` (`-nc`) skips project files for that session. The global file always loads.
 
 ### System Prompt
 
@@ -602,7 +600,7 @@ Available built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
 | `--no-prompt-templates` | Disable prompt template discovery |
 | `--theme <path>` | Load theme (repeatable) |
 | `--no-themes` | Disable theme discovery |
-| `--no-context-files`, `-nc` | Disable AGENTS.md, CLAUDE.md, and GEMINI.md context file discovery |
+| `--no-context-files`, `-nc` | Skip project `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`; global `~/.pi/agent` files still load |
 
 Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-extensions -e ./my-ext.ts`).
 

package/dist/bundled-resources/skills/icm-architect/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake Van Clief
+
+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/dist/bundled-resources/skills/icm-architect/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: icm-architect
+description: Design any process, idea, problem, or body of knowledge into an ICM (Interpretable Context Methodology) workspace — folder structure as agent architecture — or restructure an existing folder, repo, or vault into one. Use when the user wants to (1) turn a recurring workflow into an agent-runnable folder pipeline, (2) organize scattered notes, files, or knowledge into a library one AI agent can walk, (3) map a team or company as connected context ("context map", "second brain", "team brain", "knowledge base for AI"), (4) audit a codebase or mixed folder into a walkable edit map (objects, processes, change-impact) so later agents can change it without slurping the tree, (5) audit or restructure an existing workspace to ICM conventions, or (6) says "make this an ICM", "ICM this", "map this repo", "audit this folder", "what would a change hit", "build me a workspace", or "structure this for agents".
+---
+
+# ICM Architect
+
+Build workspaces where the folder structure does the orchestration. One agent, reading the right files at the right moment, replaces a multi-agent framework: numbered folders carry sequencing, hierarchy carries context scoping, plain markdown files carry state. A human can open any folder and see exactly what state the system is in, because state is just files.
+
+Think of the workspace as a library. The routing files are the catalog: small, stable, they point at everything and store almost nothing. The content lives on the shelves (stage folders, node files, reference material). One librarian — one model — walks the building, and the question decides which shelf gets walked to. Nobody photocopies the library into a backpack; that is what context-stuffing is. The catalog is small on purpose.
+
+Method: Interpretable Context Methodology (Van Clief & McDermott, arXiv:2603.16021, MIT-licensed).
+
+On Pi Adaptative, L0 is `AGENTS.md` (CLAUDE.md is accepted). After a workspace exists, drive a run with the host `pipeline` tool (`start` / `increment` / `status`). Increment completes the current stage when `output/` has files, then starts the next — it is not a Review-now latch. Concurrent or branching work still uses `delegate`.
+
+## The invariants
+
+Every ICM, whatever its form, obeys these. When building or restructuring, enforce all ten:
+
+1. **One folder, one job.** Each folder does a single step or holds a single kind of thing, and states its own purpose in a file inside itself. The structure is the documentation.
+2. **A small, stable entry file.** `CLAUDE.md` (or `AGENTS.md`) at the root answers "where am I, where does everything live, where do I go for task X" — and nothing else. Target under ~60 lines. It routes; it never holds content.
+3. **Numbering encodes order.** `01_`, `02_`, … where sequence matters. Renaming folders reorders the pipeline — that is the point.
+4. **Every folder-level contract is explicit.** A `CONTEXT.md` per working folder: what it reads (inputs), what it does (process), what it writes (outputs), what a human checks. See [assets/templates/stage-CONTEXT.md](assets/templates/stage-CONTEXT.md).
+5. **Factory vs. product.** Reference material (rules, voice, schemas, templates — stable across runs) lives structurally apart from working artifacts (outputs, drafts — new every run). Configure the factory once; the product is what each run emits.
+6. **Every output is an edit surface.** Intermediate outputs are plain files a human can open, edit, and save before the next step reads them. Nothing moves forward until a person has read the last output.
+7. **Load only what the step needs.** An agent executing a step reads its contract, its references, and its inputs — not the whole workspace. 2,000–8,000 tokens per step is the healthy range.
+8. **Plain text, linkable, queryable.** Markdown + YAML frontmatter. Links (`[[wikilinks]]` or relative paths) make it a graph; frontmatter labels make it queryable. One home per fact — a link beats a copy.
+9. **The filesystem is the state machine.** "Status" is derivable by scanning what exists in output folders. Generated indexes (file maps, logs) are rebuilt by script, never hand-edited.
+10. **Instantiate by copying.** New unit of work = copy a template folder, not a blank page. Keep templates in a `_templates/` or `_system/` folder.
+
+## Choose a mode
+
+- **Building from a described process, idea, or problem** → Build mode.
+- **An existing folder, repo, or vault that needs ICM structure** → Restructure mode.
+- **A body of work later agents must edit** (code, markdown, or mixed) → System map form. Read [references/system-map.md](references/system-map.md) after picking the form.
+
+## Build mode
+
+**1. Extract the structure from dialogue.** The structure is already in how the person describes the work — don't impose a shape, surface theirs. Ask (a few at a time, not all at once):
+
+- What is the repeating unit of work? (an episode, a client, a report, a person, a team?)
+- Walk me through one run, start to finish. Where do you stop and check something before continuing?
+- What stays the same every run (voice, rules, brand, schema) vs. what is new every run?
+- What does "done" look like — what artifact leaves the workspace?
+- Who else touches this, and what do they need to find without asking you?
+
+Their pauses become stage boundaries. Their "I always check X before Y" become human gates. Their "it always has to sound like / follow Z" becomes factory reference material.
+
+**2. Pick the form.** Read [references/forms.md](references/forms.md) and choose:
+
+| Form | Reach for it when |
+|---|---|
+| **Pipeline** | The same sequence runs repeatedly, producing a deliverable each run |
+| **Umbrella** | Several distinct pipelines share one brand/voice/reference layer |
+| **Record library** | The unit is a record (person, client, session) that accumulates, not a run |
+| **Knowledge bundle** | The product is navigable knowledge itself (a brain, a wiki, a model of something) |
+| **Context map** | The subject is an organization — teams, processes, data, and the links between them |
+| **System map** | A folder later agents will edit — nouns, movements, and what a change hits. Method: [references/system-map.md](references/system-map.md) |
+
+Real workspaces mix forms (a record library whose records are mini knowledge bundles; a pipeline that emits into a record library). Compose freely — the invariants hold at every level, recursively.
+
+**3. Scaffold the smallest structure that carries the work.** Copy starters from [assets/templates/](assets/templates/) and fill them in. Do not create folders for stages that don't exist yet, empty "misc" buckets, or speculative depth. Three real stages beat seven imagined ones. If the whole job fits in one saved prompt, say so and don't build a workspace at all.
+
+**4. Write the contracts.** Root `CLAUDE.md` (identity + routing table), root `CONTEXT.md` (the pipeline or schema definition), one `CONTEXT.md` per stage/hub folder, `setup/questionnaire.md` if the factory needs configuring per user. Write inputs as explicit file paths, split into working (this run) and reference (every run).
+
+**5. Validate with the walk test** (below).
+
+## Restructure mode
+
+**1. Inventory before touching.** List the tree. For each area note: what it is, when last touched, what refers to it. Never delete or move in this pass.
+
+**2. Find the hidden form.** Ask the owner (or infer and confirm): what is the repeating unit here? Where does work enter and leave? The mess usually contains a real pipeline, library, or map that grew without a skeleton — extract it, don't replace it. Interview the folder the way you'd interview the person.
+
+**3. Classify every file** into one of five roles:
+- **Catalog** — identity/routing (becomes or feeds `CLAUDE.md` / index files)
+- **Contract** — describes how a step works (becomes a `CONTEXT.md`)
+- **Factory** — stable reference (→ `_shared/`, `_system/`, or `references/`)
+- **Product** — run-specific artifacts (→ stage `output/` or record folders)
+- **Dead** — stale, duplicated, or superseded (→ propose `_archive/`, never silently delete)
+
+**4. Propose before moving.** Present the target tree and a migration map (old path → new path → role). Get approval. This is a human gate in a method built on human gates — honor it.
+
+**5. Migrate.** Move files, write the entry file and contracts, de-duplicate toward one-home-per-fact (leave a link where the copy lived if anything might reference it). Separate method from instance: if the structure will be reused elsewhere, the blank template lives apart from this filled-in deployment.
+
+**6. Validate with the walk test.**
+
+## The walk test
+
+Validate any ICM — new or restructured — by walking it cold, as an agent with no memory:
+
+- Open the root. Can you answer *where am I* and *where do I go for the current task* within the entry file plus at most two more reads?
+- Pick any stage/node. Does its contract name exact input paths, the job, the output, and the human check?
+- Can you state pipeline status purely by scanning what exists in `output/` folders (or node frontmatter)?
+- Is any routing file carrying content payload? Move the payload to a shelf; leave a pointer.
+- Is any fact stored in two places? Pick one home; link from the other.
+- Token check: entry file + one contract + its inputs should land in roughly 2k–8k tokens.
+- System map only: can a cold agent answer *what is X* and *what else moves if I change X* from `map/CLAUDE.md` plus one card? Extra checks are in [references/system-map.md](references/system-map.md).
+
+If a step fails, fix the structure — not by explaining more, but by moving or splitting files until the walk works.
+
+## Guardrails
+
+- **Don't over-structure.** The ladder runs: chat → saved prompt/skill → folders + one agent. Only climb when the rung below is genuinely automated and repeating. A workspace for a thing done twice is scaffolding, not architecture.
+- **Know where ICM loses.** Real-time multi-agent collaboration, high-concurrency multi-user serving, and automated mid-pipeline branching genuinely need framework code. ICM is for sequential, human-reviewed, repeatable work — which is most knowledge work, but not all of it.
+- **Anti-patterns seen in the wild:** duplicated entry files that drift (generate one from the other, or make one a pointer); schema documents that mandate names the actual files stopped using (update the schema or the files — pick one); hand-edits to generated indexes; workshop sessions that produce slides instead of structured data (every working session should end in an artifact the structure can hold); patterns declared top-down (one team complaining is a gripe — the same shape appearing three independent times is structure).
+
+## References
+
+- [references/core.md](references/core.md) — the five design principles, the five-layer context hierarchy, naming conventions, token discipline. Read when writing contracts or when a structural call is contested.
+- [references/forms.md](references/forms.md) — the six forms in depth: skeletons, moves, failure modes. Read at step 2 of Build mode or step 2 of Restructure mode.
+- [references/system-map.md](references/system-map.md) — audit pipeline for the System map form. Read when that form is chosen.
+- [assets/templates/](assets/templates/) — copyable starters: `CLAUDE.md`, workspace `CONTEXT.md`, `stage-CONTEXT.md`, `node.md`, `object.md`, `process.md`, `schema.md`, `questionnaire.md`.

package/dist/bundled-resources/skills/icm-architect/assets/templates/CLAUDE.md

@@ -0,0 +1,27 @@
+# {Workspace name}
+
+{One sentence: what this workspace is and what leaves it.}
+
+Built on ICM: folders carry sequencing, hierarchy carries context, files carry state. The structure is the documentation — if something needs explaining, the explanation goes in that folder's CONTEXT.md, not in your head.
+
+## Where things live
+
+| Folder | What it holds |
+|---|---|
+| `stages/` | the pipeline, in execution order |
+| `_shared/` | factory: rules and reference that never change per run |
+| `_templates/` | blank starters — new work is a copy, not a blank page |
+| `setup/` | one-time factory configuration |
+
+## Route by what just happened
+
+| If | Go to | Then stop at |
+|---|---|---|
+| starting a new run | `stages/01_.../CONTEXT.md` | human reads the output |
+| {previous stage} output approved | next numbered stage | human reads the output |
+| asked for status | scan `stages/*/output/` | report what exists |
+| setting up for a new user | `setup/questionnaire.md` | answers written to `_shared/` |
+
+## The one rule
+
+Nothing moves to the next stage until a person has read the output of the last one.

package/dist/bundled-resources/skills/icm-architect/assets/templates/CONTEXT.md

@@ -0,0 +1,14 @@
+# {Workspace name} — the pipeline
+
+The flow in one line: {plan it, make it, check it, ship it — in your workspace's words}.
+
+| Stage | Job | Input | Output | Human check |
+|---|---|---|---|---|
+| `01_{name}` | {five words} | {what it reads} | `output/{file}` | {what a person verifies} |
+| `02_{name}` | {five words} | 01's output | `output/{file}` | {what a person verifies} |
+| `03_{name}` | {five words} | 02's output | `output/{file}` | {what a person verifies} |
+
+Factory (stable, every run): `_shared/{voice.md, rules.md, …}`
+Product (new each run): each stage's `output/`
+
+Status is whatever exists: a stage is COMPLETE when its `output/` holds files other than `.gitkeep`.

package/dist/bundled-resources/skills/icm-architect/assets/templates/node.md

@@ -0,0 +1,29 @@
+---
+type: process
+team: {team-slug}
+owner: {name}
+ai-level: L0   # L0 manual · L1 copy-paste · L2 structured · L3 integrated
+frequency: {daily|weekly|monthly|ad-hoc}
+value: 3       # 1–5, to the business
+pain: 3        # 1–5, to the people doing it
+consumes: ["[[data-{input-asset}]]"]
+produces: ["[[data-{output-asset}]]"]
+governance: internal   # internal · sensitive · external
+---
+
+# {Process name}
+
+## Input → Movement → Output
+{What comes in, what the team does to it, what goes out. Three sentences.}
+
+## Now
+{How it actually runs today, at the ai-level declared above.}
+
+## What is working / not working
+{Honest, from the people who run it.}
+
+## If we structure this
+{What the AI-assisted version looks like — left as a stub until it's real.}
+
+## What the human keeps checking
+{The judgment that stays with a person no matter how automated this gets.}

package/dist/bundled-resources/skills/icm-architect/assets/templates/object.md

@@ -0,0 +1,43 @@
+---
+type: object
+cluster: {cluster}
+universe: live
+status: stub
+entity: {path to the owning file}
+---
+
+# {Name}
+
+{One sentence. If the product word and the file/type name differ, say both.}
+
+## Why this shape
+
+{The load-bearing why, not a field tour.}
+
+## Shape
+
+- {keys, constraints, or owning files}
+
+Citations: `{path}:{line}`
+
+## Connected to
+
+- **owns:**
+- **owned-by:**
+- **joins:**
+- **looks-like-but-is-not:**
+
+## If you change this
+
+- **Hits:**
+- **Does not hit:**
+
+## Surfaces
+
+| Surface | Role |
+|---|---|
+| {who} | {reads / writes / none} |
+
+## See
+
+- Source: `{path}`

package/dist/bundled-resources/skills/icm-architect/assets/templates/process.md

@@ -0,0 +1,38 @@
+---
+type: process
+status: stub
+consumes: []
+produces: []
+---
+
+# {process-name}
+
+{One sentence: the movement, not the nouns.}
+
+## Input → Movement → Output
+
+{Three sentences.}
+
+## Why this shape
+
+{What would break if the obvious shortcut existed.}
+
+## Steps
+
+1. {Cite `{path}:{line}`.}
+
+## If you change this
+
+- **Hits:**
+- **Does not hit:**
+
+## Surfaces
+
+| Surface | Role |
+|---|---|
+| {who} | {role} |
+
+## See
+
+- Objects: {links}
+- Source: `{path}`

package/dist/bundled-resources/skills/icm-architect/assets/templates/questionnaire.md

@@ -0,0 +1,9 @@
+# Setup questionnaire — configure the factory once
+
+Answers get written into `_shared/` as reference files. Every future run reads them; no run should ever re-ask them.
+
+1. Who is this workspace for, and what should a finished deliverable look like? (becomes `_shared/definition-of-done.md`)
+2. Voice and tone: paste two examples of past work that sound right, and one that sounds wrong. (becomes `_shared/voice.md`)
+3. Hard constraints that never bend: length, format, brand rules, compliance. (becomes `_shared/rules.md`)
+4. What does the human always check before anything ships? (becomes each stage's Human check line)
+5. What already exists that runs should reuse — templates, examples, data sources? (linked from `_shared/`, one home per fact)

package/dist/bundled-resources/skills/icm-architect/assets/templates/schema.md

@@ -0,0 +1,24 @@
+# Schema — the rules of this workspace
+
+The closed set of note types, the labels they carry, and the naming they follow. When practice and this file disagree, reconcile the same day — schema drift is how structures rot.
+
+## Node types
+
+| `type:` | Lives at | Carries |
+|---|---|---|
+| team | `teams/<slug>/{Team Name}.md` | In / Movement / Out / Edges |
+| process | `teams/<slug>/processes/<slug>.md` | full scoring frontmatter (see node template) |
+| job | `teams/<slug>/jobs/<slug>.md` | the outcome, who owns it |
+| data-asset | `teams/<slug>/data/data-<thing>.md` | source of truth, shape, sensitivity |
+| governance | `teams/<slug>/governance.md` | what may not be automated, and why |
+| pattern | `patterns/<slug>.md` | only after 3+ independent occurrences |
+
+## Labels that make it queryable
+
+`type`, `team`, `owner`, `ai-level` (L0–L3), `value` (1–5), `pain` (1–5), `governance` (internal / sensitive / external). `consumes:` and `produces:` are wikilinks to data assets — the links draw the map on their own. value + pain ≥ 8 flags a pilot candidate.
+
+## Naming
+
+- Slugs: kebab-case. Data assets always `data-<thing>.md`.
+- Human-browsed cards may use Title Case filenames — but declare that choice here and hold it everywhere.
+- `_meta/` holds the rules (this file). Generated indexes are rebuilt by script, never hand-edited.

package/dist/bundled-resources/skills/icm-architect/assets/templates/stage-CONTEXT.md

@@ -0,0 +1,21 @@
+# {NN}_{stage-name} — {the job in five words}
+
+One job: {the single thing this stage does}.
+
+## Inputs
+- Working (this run): ../{NN-1}_{prev-stage}/output/{file}
+- Reference (every run): ../../_shared/{rules-file}.md
+- Reference (every run): references/{stage-specific-guide}.md
+
+Do NOT load: {anything an eager agent would wrongly pull in — other stages' references, prior runs, the whole _shared folder}.
+
+## Process
+1. {Read the inputs.}
+2. {Transform, following the reference constraints.}
+3. {Hard limits worth restating: length, count, format.}
+
+## Outputs
+- {artifact}.md → output/
+
+## Human check
+{One concrete act: read it aloud / verify the numbers against X / confirm the order survived. Edit the output in place — the next stage reads whatever is here.}

package/dist/bundled-resources/skills/icm-architect/references/core.md

@@ -0,0 +1,92 @@
+# ICM Core
+
+The canon, distilled from the ICM paper (arXiv:2603.16021) and production workspaces. Read this when writing contracts, arguing a structural call, or checking a workspace against the method.
+
+Contents: Five principles · Five-layer hierarchy · Stage contract format · Naming conventions · Library rules · Token discipline · Where ICM loses
+
+## The five design principles
+
+Each is borrowed from fifty-year-old, still-standing engineering practice:
+
+1. **One stage, one job** (Unix / Parnas). Each stage handles a single step and writes to its own folder. A stage that fetches does not also filter; a stage that filters does not also format.
+2. **Plain text as the interface** (Kernighan & Pike). Stages communicate through markdown and JSON. No binary formats, no databases in the loop, no proprietary serialization. Any human with a text editor can inspect or modify any artifact.
+3. **Layered context loading.** Agents load only what the current stage needs — prevention, not compression. Within content, reference material (internalize as constraints) is kept structurally separate from working artifacts (process as input), because they ask different things of the model.
+4. **Every output is an edit surface** (Horvitz / Shneiderman). Each intermediate output is a file a human can open, edit, and save before the next stage runs. The next stage reads whatever the human left there.
+5. **Configure the factory, not the product** (continuous delivery). Set up preferences, brand, style, and structure once; every run emits a new deliverable from the same configuration.
+
+The consequence, stated once: *stage sequencing is the folder numbering; context scoping is the folder hierarchy; state management is the files on disk; coordination is one folder's output being another folder's input.* The filesystem does the work a framework would do in code.
+
+## The five-layer context hierarchy
+
+| Layer | Typical file | Question it answers | Role | Size |
+|---|---|---|---|---|
+| L0 | `CLAUDE.md` | Where am I? | routing | 300–800 tokens |
+| L1 | root `CONTEXT.md` | Where do I go? | routing | 200–500 tokens |
+| L2 | stage `CONTEXT.md` | What do I do? | **the control point** | 200–500 tokens |
+| L3 | `references/`, `_shared/` | What rules apply? | factory (stable) | 500–2k tokens |
+| L4 | `output/`, run artifacts | What am I working with? | product (per-run) | varies |
+
+- L0–L2 are the catalog: small, stable, no content payload.
+- L2 is the control surface of the whole system — its Inputs section is what makes context selection explicit, editable, and auditable instead of left to agent judgment.
+- L3 vs L4 is the factory/product split. L3 = the recipe (voice.md, design-system.md, schema.md). L4 = the ingredients and the dish (research-output.md, draft.md).
+- Large L3 collections get their own internal `CONTEXT.md` router — the L1 routing pattern applied recursively. The hierarchy is self-similar at every depth; apply it inside any folder that grows past easy scanning.
+
+## Stage contract format
+
+Every working folder carries a `CONTEXT.md` shaped like this (copy from `assets/templates/stage-CONTEXT.md`):
+
+```markdown
+# 02_script — turn research into a script
+
+One job: write the script from the research output.
+
+## Inputs
+- Working (this run): ../01_research/output/research.md
+- Reference (every run): ../../_shared/voice.md
+- Reference (every run): references/structure.md
+
+## Process
+1. Read the research output.
+2. Draft to the structure in structure.md, in the tone of voice.md.
+3. Keep under 90 seconds spoken.
+
+## Outputs
+- script_draft.md → output/
+
+## Human check
+Read the draft aloud. Verify the argument order survived from research. Edit in place; the next stage reads whatever is here.
+```
+
+Rules: inputs are exact paths, split working vs reference. The process is numbered and short — constraints live in L3 files, not restated here. Exactly one human check, stated as something a person does, not a vague "review."
+
+## Naming conventions
+
+- Stage folders: `NN_kebab-name` (`01_research`). Ordinal-only prefixes (`00-tracker.md`) for ordered files inside a folder.
+- Meta/system folders get an underscore prefix and sort to the top: `_meta/`, `_system/`, `_shared/`, `_config/`, `_templates/`, `_index/`, `_archive/`. Underscore = "about the workspace, not of the work."
+- Records and nodes: kebab-case slugs for machine-facing files, or human-readable Title Case where a person browses daily (an Obsidian vault). Pick one per workspace and write the choice into the schema — drift between schema and files is the most common decay.
+- Typed content files may prefix their type: `data-customer-list.md`.
+- Entry file: `CLAUDE.md` for Claude Code, `AGENTS.md` for other agents. If both exist, one is generated from the other or is a one-line pointer — never two hand-maintained copies.
+- Templates are blank, named for what they produce, and live together: `_templates/pilot-brief.md`.
+
+## Library rules
+
+- **The catalog holds no books.** Routing files point at everything and store almost nothing. When a routing file grows, it is absorbing payload — move the payload to a shelf.
+- **One home per fact; a link beats a copy.** Duplication is how structures rot.
+- **Generated indexes are never hand-edited.** A file map built from frontmatter by a script cannot drift; a hand-curated one always does. If an index matters, script it and schedule the rebuild.
+- **The structure is the documentation.** If something needs explaining, the explanation goes in that folder's `CONTEXT.md`, not in a wiki elsewhere and not in anyone's head. A new collaborator should understand the whole pipeline by reading the CONTEXT files top to bottom, without running anything.
+- **Method and instance live apart.** The blank, reusable template of a structure is a different artifact from any filled-in deployment of it. When a structure proves out, extract the template before it tangles with the data.
+- **Working sessions end in artifacts.** A workshop, interview, or planning call that produces only slides or vibes has failed the structure; it should end with files the structure can shelve.
+
+## Token discipline
+
+A stage's full context — entry + contract + references + inputs — should land around 2,000–8,000 tokens. That keeps the model in the range where it performs best and keeps every load auditable. A monolithic everything-prompt for the same pipeline typically runs 30k–50k tokens, most of it irrelevant to the current step; ICM never loads those tokens rather than compressing them later. If a stage's context balloons: split the stage, tighten the Inputs list, or push detail down into an L3 file the contract points at but doesn't inline.
+
+## Where ICM loses
+
+Name these honestly rather than overclaiming:
+
+- **Real-time multi-agent collaboration** — agents responding to each other in tight loops need message-passing infrastructure; file handoffs are too slow.
+- **High concurrency** — many users hitting one pipeline needs queueing, state isolation, deployment. ICM is local-first by design.
+- **Automated mid-pipeline branching** — a human choosing stage 3a vs 3b between stages is natural; the *system* branching on AI output mid-run pushes ICM toward becoming the framework it replaced.
+
+The claim is not that ICM replaces frameworks everywhere. The claim is that for sequential, human-reviewed, repeatable workflows — most knowledge work — the framework is more complexity than the problem requires, and that complexity costs opacity, fragility, and developer dependency.