@jenga-ai/agent 1.3.0 → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Jenga AI
+### No agent merges its own code.
 
-**A structured multi-agent development workflow that works with any AI agent or AI-native IDE.** Three specialised AI agents — Scrum Master, Developer, and Tester — collaborate through a shared scrum board, an event-driven trigger queue, and 28 slash-command skills to take a project from idea to verified, committed code — across as many sessions as it takes.
+Jenga AI is an agentic software engineering framework for AI-assisted development: it splits work across three role-bounded agents — a Scrum Master that plans, a Developer that implements in an isolated git worktree, and a Tester that runs your test suite and owns the board status. Work survives session boundaries as Epics, Stories, and Tasks on a Markdown board your agent reads at the start of every session.
 
 [![npm version](https://img.shields.io/npm/v/@jenga-ai/agent.svg)](https://www.npmjs.com/package/@jenga-ai/agent)
 [![license](https://img.shields.io/npm/l/@jenga-ai/agent.svg)](LICENSE)
@@ -9,124 +10,110 @@
 npm install @jenga-ai/agent
 ```
 
-## What You Get
-
-- **Three specialised agents** — Scrum Master, Developer, Tester — each with a distinct role and no self-graded work
-- **A persistent scrum board** — Epics, Stories, and Tasks tracked as Markdown files with structured frontmatter, surviving every session boundary
-- **28 slash-command skills** — from planning (`/pi-plan`, `/todo`) to execution (`/do`, `/dooo`) to review (`/status`, `/reconcile`)
-- **An event-driven trigger queue** — async handoffs between agents with a full audit trail in `project/logs/events.json`
-- **Isolated git worktrees per task** — the Developer never works directly on your main branch
-- **Works with any AI agent or IDE** — Claude Code, GitHub Copilot, Warp, and Codex CLI are all supported today
-
-> 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
-
-## Platform Support
-
-| Agent | Skills & Agents | Root Context File |
-|---|---|---|
-| **Claude Code** | `.claude/` — mirrored automatically on install | `CLAUDE.md` — generated by `/init` today |
-| **GitHub Copilot** | `.agents/` — mirrored automatically on install | `.github/copilot-instructions.md` — bootstrapped at `npm install` time, refined by `jenga init` |
-| **Codex** | `.agents/` — mirrored automatically on install | `AGENTS.md` — generated by `/init` today |
-
-`CLAUDE.md` and `AGENTS.md` are generated unconditionally by `/init` — every agent gets a real, populated root-level context file out of the box, not just a pointer. If either file already exists as a genuine pre-existing user file, Jenga writes its own copy as `J-CLAUDE.md` / `J-AGENTS.md` instead and inserts a short reference into the existing file, leaving it otherwise untouched.
-
-`.github/copilot-instructions.md` follows a different path: `scripts/postinstall.js` writes it unconditionally and non-interactively the moment `npm install` finishes, so Copilot has working `/skill-name` routing instructions even if a consumer's very first action is a Copilot slash command, before the separate `jenga init` CLI wizard has ever run. Running `jenga init` afterward refines the same file using the user's actual chosen skills path — it is never generated by the `/init` skill itself.
+## The Problem It Solves
 
----
+You've had this happen: Claude wrote the feature, said it worked, and the session ended. Next session it had no idea any of it existed. Without a framework like Jenga AI, AI-assisted development has serious structural weaknesses:
 
-## The Problem It Solves
+[![How AI Coding Agents Understand Your Codebase & Developer Tools](https://img.youtube.com/vi/zAe-sau06io/maxresdefault.jpg)](https://www.youtube.com/watch?v=zAe-sau06io)
 
-Without a framework like Jenga AI, AI-assisted development has serious structural weaknesses:
+*"How AI Coding Agents Understand Your Codebase & Developer Tools" — IBM Technology on the same gap in persistent development context and tooling context that Jenga AI's board and agent contracts are built to close.*
 
 | Problem | Reality |
 |---|---|
-| **AI has no session memory** | Every AI agent session starts from scratch — no awareness of open tasks, past decisions, or what was already tested |
+| **No persistent engineering context** | Every AI agent session starts from scratch — no awareness of open tasks, past decisions, or what was already tested |
 | **No role separation** | The AI writes *and* "tests" code in the same context, leading to hallucinated test results and self-affirming bugs |
 | **No structured planning** | Work happens ad-hoc — no Epic → Story → Task hierarchy to organise or track progress |
 | **No handoff protocol** | Switching from implementing to testing means manually re-explaining context every time |
 | **No audit trail** | You can't replay *why* something was built, by which agent, based on which task |
 | **Sessions just end** | Work-in-progress, unresolved problems, and incomplete stories silently vanish |
 
-Jenga AI solves each of these with structure: persistent board state, strict agent roles, typed inter-agent contracts, and session-end hooks that preserve context between sessions.
+Jenga AI solves each of these with structure: persistent engineering context maintained via board state, strict agent roles, typed inter-agent contracts, and session-end hooks that carry that context between sessions.
 
 ---
 
-## Examples
+## What You Get
 
-### Before / After
+- **Three specialised agents** — Scrum Master, Developer, Tester — each with a distinct role and no self-graded work
+- **A persistent, Kanban-style scrum board** — Epics, Stories, and Tasks tracked as Markdown files with structured frontmatter, surviving every session boundary
+- **A coordinated skill pipeline — one agentic workflow, not a command list** — planning skills (`j.pi-plan`, `j.todo`) hand off to execution skills (`j.do`, `j.dooo`), which hand off to review skills (`j.status`, `j.reconcile`), each stage reading and writing the same board state — the old bare `/<name>` form still works everywhere as a permanent alias
+- **An event-driven trigger queue** — async handoffs between agents with a full audit trail in `project/logs/events.json`
+- **Isolated git worktrees per task** — the Developer never works directly on your main branch
+- **Works with any AI coding agent or AI-native IDE** — Claude Code, GitHub Copilot, and Codex CLI are all supported today
 
-**Without Jenga AI:**
-```
-You: "Add user authentication"
-AI agent: [writes auth code, declares it works, session ends]
+> 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
 
-Next session:
-You: "What's the status of auth?"
-AI agent: "I don't have context from the previous session."
-```
+### "Isn't this just an LLM grading another LLM?"
 
-**With Jenga AI:**
-```
-/todo → "Add user authentication" → linked to E01_S02
-/do   → Developer creates worktree E01_S02_T01-auth
-      → implements, commits at milestones
-      → hands off to Tester with sender object
+The Tester doesn't read your code and form an opinion about it. It executes the test suite you configure in `project/configs/test-config.json` and reports pass or fail — in this repo, `bats` for unit and integration, `shellcheck` for SAST. What Jenga guarantees structurally is that the agent that wrote the code is not the agent that decides it's done, and doesn't get to write its own status onto the board. What comes out of that gate depends on what you wire into it — the same as any CI pipeline.
+
+## Platform Support
 
-Tester → runs tests, updates board status to ✅ Passed
-SessionEnd → writes status_review trigger to queue
+| Agent | Skills & Agents | Root Context File |
+|---|---|---|
+| **Claude Code** | `.claude/` — mirrored automatically on install | `CLAUDE.md` — generated by `j.init` today |
+| **GitHub Copilot** | `.agents/` — mirrored automatically on install | `.github/copilot-instructions.md` — bootstrapped at `npm install` time, refined by `jenga init` |
+| **Codex** | `.agents/` — mirrored automatically on install | `AGENTS.md` — generated by `j.init` today |
 
-Next session:
-/status → "E01_S02 ✅ complete — E01_S03 pending"
-```
+`CLAUDE.md` and `AGENTS.md` are generated unconditionally by `j.init` — every agent gets a real, populated root-level context file, not just a pointer. If either file already exists as a genuine pre-existing user file, Jenga leaves it untouched, writes its own copy as `J-CLAUDE.md` / `J-AGENTS.md`, and inserts a short reference line into the original.
+
+`.github/copilot-instructions.md` follows a different path, because Copilot needs it before `j.init` may ever run: `npm install` triggers `scripts/postinstall.js`, which writes it unconditionally and non-interactively, so `j.<name>` routing (the bare `/<name>` form still resolves too, as a permanent alias) works from a consumer's very first Copilot command. A later `jenga init` run refines that same file using the project's actual chosen skills path.
 
 ---
 
-### Real-World Scenario: Building a Feature Across Sessions
+## Examples
 
-Imagine you're building a REST API with auth, rate limiting, and an admin dashboard. Each is a separate Epic. Here's how Jenga AI handles that across multiple days:
+### A Real Session, On This Repo
 
-**Planning**
-```
-/init          → scaffolds project/, board/, workflow.json
-/pi-plan       → Scrum Master helps shape the auth epic into stories
-/todo          → "Add JWT auth" → E01_S01, "Add refresh tokens" → E01_S02
-```
+Not a demo — this is what actually produced the section you're reading.
+
+The conversation starts with a request to align this README's language and content with a positioning plan drafted for this epic (E41):
 
-**Implementation**
 ```
-/do            → Developer picks up E01_S01_T01-jwt-middleware
-               → creates isolated worktree, implements, commits
-               → Tester validates, marks Passed, triggers rollup
-/status        → E01_S01 ✅, E01_S02 Pending
-/continue      → picks up E01_S02 automatically
-/proceed       → resumes project plan from current board state
+j.improve E41: I want to make some adjustments to the README in both
+language as well as content to better match [the E41 positioning plan]
+[...]
 ```
 
-**New idea mid-session**
+That plan already existed, so the copy gets edited directly — no need to re-run a fresh analysis pass just to re-derive it. A few edits later, ten more issues surface, one with an `j.brainstorm` request attached:
+
 ```
-You: "Actually, let's also add API rate limiting while we're at it"
-/btw           → captures "rate limiting" as E02 without losing E01 context
-               → returns focus to E01_S02
-/spinoff       → captures a diverging topic mid-conversation, saves as /todo
-               → returns focus to primary thread
+Then do a j.todo on this, as there are more places that should be
+edited based on that scrutiny rapport:
+* Remove warning banner about Copilot conflict
+[...]
+* Fewer, better and more relatable examples, we should
+  j.brainstorm this so I can send examples from real world usecases
+[...]
+* Should we really display the entire Skill list here?
+[...]
 ```
 
-**Parallel work**
+`j.todo` classifies the ten items into two stories: nine mechanical README fixes (`E41_S10`), and the Examples section you're reading right now (`E41_S11`) — carved out and held back specifically because of that `j.brainstorm` request, since a real example had to come from the user, not be invented.
+
+Once `E41_S10` is on the board, it's picked to run first. The Scrum Master reads the story and decomposes it into seven tasks, executed through `j.do`. Five are small, single-file text fixes deemed `--trivial` — they run inline, smoke-tested and committed directly, no worktree needed. Two need an editorial call — one of them being which skills are "foundational" enough to stay inline — those escalate to a real git worktree with a Developer and a Tester. The Tester independently re-verifies the diff, catches one file the Developer missed, fixes it, and queues the story for rollup. The Scrum Master processes that queue next: `E41_S10` → `Passed`. Epic `E41` stays `In Progress` — three other stories are still open.
+
+Then, circling back to the deferred request:
+
 ```
-/jenga         → interactive board orchestrator: pick or scope, confirm, then execute (`/jenga *` for the original fully automated, no-prompts run)
-/dooo          → orchestrates E01_S02 and E02_S01 in parallel sub-agents
-/reconcile     → syncs board with actual git history after parallel merges
+Jenga AI: [...] Remaining open thread from this session: E41_S11
+(Examples rework) is on the board but not started — it's gated on
+a j.brainstorm session where you supply real-world use cases. Want
+to do that now, or leave it queued?
+
+You: do it now
 ```
 
-The board, the audit log, and `PROJECT_SUMMARY.md` survive every session boundary. You never re-explain context.
+`j.brainstorm` opens for the gated story — the session you're reading right now, working out what this example should even say.
+
+Nobody hand-wrote this task breakdown. The board did it, the routing rules decided what needed a real worktree versus what could run inline, and the Tester — not the agent that made the edits — decided when each piece was actually done. The board entries are real: `E41_S10` and `E41_S11`.
 
 ---
 
-## How It Works
+## How Jenga AI's Agentic Workflow Works
 
 ```
-/init → /pi-plan → /todo → /do
-                           │
+j.init → j.pi-plan → j.todo → j.do
+                              │
                      Developer agent
                      (isolated worktree, commits)
                            │
@@ -166,8 +153,7 @@ Each agent is defined in `.agents/agents/`. They communicate exclusively through
 
 **Prerequisites:** An AI agent or AI-native IDE. Supported platforms include:
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- GitHub Copilot (VS Code extension or CLI)
-- [Warp](https://www.warp.dev/)
+- [GitHub Copilot](https://github.com/features/copilot) (VS Code extension or CLI)
 - Codex CLI
 
 **Install from npm:**
@@ -177,13 +163,13 @@ npm install -g @jenga-ai/agent
 
 Or clone directly:
 
-1. **Clone or copy this repo** into your project's `.agents/` directory (or wherever you keep project tooling).
-2. **Run `/init`** — scaffolds `project/`, creates `workflow.json`, `PROJECT_SUMMARY.md`, and makes an initial commit.
-3. **Run `/pi-plan`** — define your project goals and initial epics.
-4. **Run `/todo`** — describe features to implement; they're linked to the board automatically.
-5. **Run `/do`** — picks the first task and drives the full implement → test → commit loop.
+1. **Clone or copy this repo** into your project's root.
+2. **Run `j.init`** — scaffolds `project/`, creates `workflow.json`, `PROJECT_SUMMARY.md`, and makes an initial commit.
+3. **Run `j.pi-plan`** — define your project goals and initial epics.
+4. **Run `j.todo`** — describe features to implement; they're linked to the board automatically.
+5. **Run `j.do`** — picks the first task and drives the full implement → test → commit loop.
 
-Run `/status` at any time to see where the project stands.
+Run `j.status` at any time to see where the project stands.
 
 ---
 
@@ -195,7 +181,6 @@ Jenga AI has been tested with:
 |---|---|
 | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | AI coding agent |
 | [GitHub Copilot](https://github.com/features/copilot) | AI coding assistant |
-| [Warp](https://www.warp.dev/) | AI-native terminal |
 | Codex CLI | AI coding agent |
 
 The framework is platform-agnostic by design — any AI agent that can read Markdown files and execute slash commands can use it.
@@ -204,188 +189,40 @@ The framework is platform-agnostic by design — any AI agent that can read Mark
 
 ## Skills (Slash Commands)
 
-Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `/<name>` in your AI agent or IDE's command interface.
-
-### Setup & Planning
-
-| Command | Description |
-|---|---|
-| `/init` | Scaffold project directories, `workflow.json`, `PROJECT_SUMMARY.md`, initial git commit |
-| `/jbp` | Scaffold using the [JengaBasePlate](https://github.com/samwelmunga/JengaBasePlate.git) boilerplate |
-| `/jenga` | Interactive-by-default board orchestrator — bare shows a picker + confirmation tree, `<ids>` scopes and confirms, `*` runs fully automated with no prompts |
-| `/pi-plan` | Define or expand Epics in `PROJECT_SUMMARY.md` — use at start or when adding major new work |
-| `/brainstorm` | Focused planning session with the Scrum Master before committing anything to the board |
-| `/deep-dive` | Multi-phase investigation — gathers info, brainstorms, scrutinises, and produces a refined output |
-| `/uncharted` | Entry point for code with no board provenance — `segment` (a file or directory), `import` (an external source), `onboard` (a whole pre-existing codebase) |
-| `/todo` | Add missions to `project/todo.md` linked to epics and stories |
-| `/btw` | Capture a mid-flow idea, classify it into epic/story structure, implement now or defer |
-| `/spinoff` | Capture a diverging topic without losing your current thread |
-
-### Execution
-
-| Command | Description |
-|---|---|
-| `/do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
-| `/dooo` | Parallel execution orchestrator — runs multiple tasks simultaneously via sub-agents |
-| `/redo` | Rework a previous implementation by commit SHA or Epic/Story number |
-| `/publish` | Configure, validate, and orchestrate scaffolded release workflows — `setup`, `deploy`, `stage` (npm/npm-ci pre-approval staged publishing), `history`, `release-notes` |
-| `/error` | Guided troubleshooting — gathers context, investigates, and drives a fix |
-| `/train` | Scaffold and run ML training jobs (new job from template or run existing) |
-
-### Status & Review
-
-| Command | Description |
-|---|---|
-| `/status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
-| `/jenga-permission-level` | Report or switch the current session's 5-tier permission level (Locked/Guarded/Standard/Elevated/Unrestricted) without hand-editing settings.json |
-| `/continue` | Check project status and pick up the next incomplete item |
-| `/proceed` | Review progress and resume executing the project plan |
-| `/reconcile` | Sync the board with actual git history — fixes drift, merges orphaned worktrees |
-| `/reconcile-origin` | Sync the current or specified branch with origin via rebase. Presents conflict reports with resolution options. |
+Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your AI agent or IDE's command interface — the old bare `/<name>` form also keeps working permanently as an alias. A handful of the most foundational commands:
 
-### Committing & Maintenance
+> ⚠️ **Command collision with a host tool?** Some host tools ship their own built-in command that can
+> shadow one of Jenga's — e.g. GitHub Copilot's own built-in `/init`, which could silently shadow
+> Jenga's `/init` skill. Every skill (except `init`, already handled) has a collision-safe `/j-<name>`
+> directory-twin form — e.g. `/j-init` — that always resolves to the genuine Jenga skill regardless of
+> what else is installed. This is separate from the `j.<name>` prefix form above: it's a real duplicate
+> directory under a distinct name, not a routing alias, generated and kept in sync via
+> `scripts/generate-j-alias.sh`. If a `j.<name>` or bare `/<name>` command isn't behaving as
+> documented, try its `/j-<name>` form instead.
 
 | Command | Description |
 |---|---|
-| `/commit` | Commit completed work using the EST naming convention |
-| `/lgtm` | Approve current work, commit, and continue — chains `/commit` + `/continue` |
-| `/distribute` | Propagate workflow changes to all registered consumer projects |
-| `/doc` | Generate or update a documentation file from codebase evidence |
-| `/doc-sync` | Compare project state with documentation and update stale docs |
-| `/skillify` | Refactor a skill — extract assets, offload scripts, clean up the body |
-| `/route` | Intelligently route a prompt to the best-matching skill |
-| `/improve` | Analyse a codebase and produce a structured improvement plan |
-| `/evaluate` | Analyse example files against a target goal and produce an evaluation rapport |
-| `/examplify` | Explain a concept, feature, or pattern with grounded examples |
-| `/help` | List all available skills with descriptions |
-| `/customize-cloud-agent` | Configure the Copilot cloud agent environment (`copilot-setup-steps.yml`, preinstalls, runners) |
-
----
-
-## Distributing the Workflow
-
-Jenga AI can propagate its workflow files to other projects on your machine via `/distribute`.
-
-1. **Register consumer projects** — add each consuming project to `distribute.config.json` at the repo root (or pass a path directly: `/distribute /path/to/project`).
-2. **Run `/distribute`** — choose `major`, `minor`, `patch`, or `amend` release type; the skill handles versioning, dry-run preview, file copy, and a version bump commit.
-
-Each consuming project holds a `jenga.config.json` tracking the distributed version, last distribution date, and source. To exclude specific files per consumer project, add a `.jenga_ignore` at the consumer root (never overwritten by distribute).
-
----
+| `j.init` | Scaffold project directories, `workflow.json`, `PROJECT_SUMMARY.md`, initial git commit |
+| `j.jenga` | Interactive-by-default board orchestrator — bare shows a picker + confirmation tree, `<ids>` scopes and confirms, `*` runs fully automated with no prompts |
+| `j.todo` | Add missions to `project/todo.md` linked to epics and stories |
+| `j.do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
+| `j.status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
 
-## Directory Structure
-
-```
-.agents/                   ← Workflow root (place this in your project)
-├── agents/
-│   ├── scrum-master.md
-│   ├── developer.md
-│   └── tester.md
-├── hooks/
-│   └── on_session_end.sh
-├── mcp/
-│   ├── help/
-│   └── execute-ticket/
-├── skills/
-│   ├── brainstorm/
-│   ├── btw/
-│   ├── commit/
-│   ├── continue/
-│   ├── deep-dive/
-│   ├── distribute/
-│   ├── do/
-│   ├── doc/
-│   ├── doc-sync/
-│   ├── dooo/
-│   ├── error/
-│   ├── evaluate/
-│   ├── examplify/
-│   ├── help/
-│   ├── improve/
-│   ├── init/
-│   ├── pi-plan/
-│   ├── jbp/
-│   ├── jenga/
-│   ├── lgtm/
-│   ├── proceed/
-│   ├── reconcile/
-│   ├── redo/
-│   ├── route/
-│   ├── skillify/
-│   ├── spinoff/
-│   ├── status/
-│   ├── todo/
-│   └── train/
-├── templates/
-│   ├── SCRUM_BOARD_SCHEMA.md
-│   ├── PROBLEM_RAPPORT_TEMPLATE.md
-│   └── JENGA_CONFIG_TEMPLATE.json
-├── settings.json
-├── jenga.config.json       ← Workflow version source
-├── .jenga_paths            ← Machine-local consumer paths (git-ignored)
-└── RELEASE_NOTE.md
-
-project/                   ← Created by /init inside your software project
-├── board/
-│   ├── epics/             ← E##_<slug>.md
-│   ├── stories/           ← E##_S##_<slug>.md
-│   └── tasks/             ← E##_S##_T##_<slug>.md
-├── configs/
-│   ├── workflow.json      ← Shared constants (statuses, paths, agents)
-│   └── test-config.json   ← Test tool stack (owned by Tester, user-approved)
-├── data/
-│   └── baselines.json     ← Analytics baselines (owned by Tester)
-├── documentation/
-│   ├── plans/             ← Pre-execution plans by Developer
-│   └── summaries/         ← Post-execution summaries by Developer
-├── queue/
-│   ├── scrum_triggers.jsonl
-│   ├── developer_triggers.jsonl
-│   ├── tester_triggers.jsonl
-│   └── project_summary_updates.jsonl
-├── rapports/
-│   ├── problems/          ← Problem rapports (Developer + Tester)
-│   └── analysis/          ← Analysis rapports (Tester)
-├── logs/
-│   └── events.json        ← Append-only inter-agent event log
-└── PROJECT_SUMMARY.md     ← Project source of truth (owned by Scrum Master)
-
-CHANGELOG.md                ← Created by /init at the project's repo root; maintained by /publish
-```
-
----
-
-## Agent Communication Contract
-
-Every inter-agent call passes a typed **sender object**:
-
-```json
-{
-  "sender": {
-    "agent": "<scrum-master | developer | tester | orchestrator>",
-    "session_id": "<session id>",
-    "task_id": "<E##_S##_T##>",
-    "story_id": "<E##_S##>",
-    "epic_id": "<E##>",
-    "date": "<ISO 8601 UTC>",
-    "paths": ["<commit SHA>", "..."],
-    "worktree": "<absolute path to worktree>"
-  }
-}
-```
-
-All agents log every incoming sender object to `project/logs/events.json` as their **first action** on every invocation.
+> 📖 **Full skill list** (planning, review, committing & maintenance commands): [project/.wiki/documentation.md](project/.wiki/documentation.md#skills)
 
 ---
 
 ## When to Use Jenga AI
 
 **Use it when:**
-- You're building a non-trivial project across multiple sessions
-- You want reliable test separation — the Tester never trusts the Developer's self-assessment
+- You're building a non-trivial project across multiple sessions and need persistent engineering context instead of re-explaining it every time
+- You want an agentic development workflow with separate planning, coding, testing, and review agents — not one model self-grading its own work
 - You need traceability — who did what, when, on which task
-- You want to reuse and propagate your AI workflow across multiple projects
+- You're working across more than one AI coding agent or AI-native IDE and want one workflow, not a separate setup per tool
+- You want to reuse and propagate the same agentic workflow across multiple projects (`j.distribute`)
 
 **You might not need it when:**
 - You're doing a quick one-off script or single-session experiment
 - Your project has no meaningful test surface
+
+📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md)

package/agents/developer.md

@@ -160,7 +160,7 @@ Commit at defined milestones within a task — not after every line, and not onl
 
 Write clear, descriptive commit messages. Your commit messages serve as a guide for the tester — they should communicate what changed and why, not just what files were touched.
 
-Use the `/commit` skill to commit.
+Use the `j.commit` skill to commit.
 
 ### Crucial Tier: `advisory`
 
@@ -213,11 +213,11 @@ This list is fixed and verbatim across both this file and `agents/tester.md` —
 
 **Trigger.** The task you are implementing — or its parent story — carries `crucial_level: locked` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
 
-**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `/jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note explaining the correction. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03).
+**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j.jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note explaining the correction. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03).
 
-**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `/jenga` story-batch execution, regardless of what its `execution_scope` value currently reads. This is enforced at two separate points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)**, which disqualifies any story containing a `locked` task from the bundle path before dispatch, and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**, which forces the inline execution path (no worktree, no developer subagent) at the point of dispatch even if `execution_scope` somehow still reads something other than `inline`.
+**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of what its `execution_scope` value currently reads. This is enforced at two separate points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)**, which disqualifies any story containing a `locked` task from the bundle path before dispatch, and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**, which forces the inline execution path (no worktree, no developer subagent) at the point of dispatch even if `execution_scope` somehow still reads something other than `inline`.
 
-**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit you must remember to keep up) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you at all. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `/do` guards above) before you ever begin work on the task — there is no step in this tier that depends on you noticing or remembering anything. Your only obligation is to recognize that a `locked` task will always run in the current foreground session, and to never manually route around that guarantee — for example, do not spin up your own background subagent or a separate worktree-isolated session to "help" with a `locked` task, even if it seems more efficient. If a locked task ever reaches you already running in a background or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to quietly work through.
+**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit you must remember to keep up) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you at all. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j.do` guards above) before you ever begin work on the task — there is no step in this tier that depends on you noticing or remembering anything. Your only obligation is to recognize that a `locked` task will always run in the current foreground session, and to never manually route around that guarantee — for example, do not spin up your own background subagent or a separate worktree-isolated session to "help" with a `locked` task, even if it seems more efficient. If a locked task ever reaches you already running in a background or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to quietly work through.
 
 ---
 
@@ -225,7 +225,7 @@ This list is fixed and verbatim across both this file and `agents/tester.md` —
 
 You do not run tests. Before calling the tester agent, **write an execution summary** to `project/documentation/summaries/<E##_S##_T##>-summary.md` using `templates/EXECUTION_SUMMARY_TEMPLATE.md`. Fill in all sections — what was implemented, files changed, commit SHAs, acceptance criteria coverage, and any concerns for the tester. This step is mandatory before every tester invocation.
 
-When you reach a meaningful milestone within a task where verification is appropriate — or when the task is complete — call the tester agent. Always pass the following sender object when invoking the tester:
+When you reach a meaningful milestone within a task where verification is appropriate — or when the task is complete — call the tester agent. Before invoking the tester, compose a short `resolved_context` digest of what you already resolved during implementation — which files you touched and why, which acceptance criteria map to which changes, any conventions or precedent you followed — and persist it by calling `scripts/write-context-digest.sh --agent developer --session-id <session_id> --task-id <task_id>` with that content (stays under the ~100-line/few-hundred-token cap defined in `templates/SCRUM_BOARD_SCHEMA.md`'s `resolved_context` subsection; the script rejects oversized input rather than truncating it). Place the script's returned path in the sender object's `resolved_context` field. Always pass the following sender object when invoking the tester:
 
 ```json
 {
@@ -237,12 +237,13 @@ When you reach a meaningful milestone within a task where verification is approp
     "epic_id": "<E##>",
     "date": "<ISO 8601 UTC timestamp>",
     "paths": ["<list of commit SHAs for this work>"],
-    "worktree": "<absolute path to the worktree>"
+    "worktree": "<absolute path to the worktree>",
+    "resolved_context": "<path returned by scripts/write-context-digest.sh, or omit if no digest was written>"
   }
 }
 ```
 
-All fields must be present. In addition to the sender object, include a short plain-text implementation summary: what was implemented, which files changed, and any known edge cases or concerns. Reference the execution summary at `project/documentation/summaries/<E##_S##_T##>-summary.md` for full detail.
+All fields must be present except `resolved_context`, which is optional. This digest is a starting point only, never a restriction: the tester may and should still read the full execution summary, the diff itself, or any other source file when the digest doesn't cover what it needs. In addition to the sender object, include a short plain-text implementation summary: what was implemented, which files changed, and any known edge cases or concerns. Reference the execution summary at `project/documentation/summaries/<E##_S##_T##>-summary.md` for full detail.
 
 Wait for the tester's response before continuing. If the tester returns `"failed"` or `"error"`, address the findings before proceeding.
 
@@ -289,7 +290,7 @@ See `templates/PROBLEM_RAPPORT_TEMPLATE.md` for the required format. Commit the
 
 ## Investigative Mode
 
-**Trigger.** You are sometimes dispatched not to implement a task, but purely to build understanding of existing code — e.g. by the scrum-master during `/uncharted`'s conversational architecture elicitation, when it needs to know what a named flow or target actually does before proposing graph nodes or asking the user to confirm/correct an understanding. This is a distinct dispatch mode from the standard Task Intake flow above, and it is recognized by the request itself (you are asked to *trace* or *investigate*, not to *implement*), not by any board field.
+**Trigger.** You are sometimes dispatched not to implement a task, but purely to build understanding of existing code — e.g. by the scrum-master during `j.uncharted`'s conversational architecture elicitation, when it needs to know what a named flow or target actually does before proposing graph nodes or asking the user to confirm/correct an understanding. This is a distinct dispatch mode from the standard Task Intake flow above, and it is recognized by the request itself (you are asked to *trace* or *investigate*, not to *implement*), not by any board field.
 
 **Hard constraints.** Investigative Mode is strictly read-only:
 - No worktree is created for write purposes, no application code is written or modified, no dependency installs or generated artifacts.