obsidian-lean-coder 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to OLC (Obsidian Lean Coder) are recorded here.
+OLC is pre-release: versions are `0.x` until a controlled-testing release says otherwise.
+`package.json` shipped `"private": true` through 0.1.0; the flag was removed at publish time with explicit user approval, and 0.1.0 is live as [`obsidian-lean-coder`](https://www.npmjs.com/package/obsidian-lean-coder). Publishing a new version is still a separate explicitly approved action, never automatic.
+
+## [0.1.1] — 2026-10-13 — plugin entrypoint fix
+
+Fixes npm-package activation (reported: `npm install` worked but nothing appeared in OpenCode).
+The package-root entrypoint `dist/index.js` exported only `OLC_VERSION`, so npm loaders —
+which resolve the package root — never saw the plugin default export and ignored the package.
+`src/index.ts` now re-exports the plugin default alongside `OLC_VERSION`.
+Agents/skills still appear only via the project-local `.opencode` copy (by design, OLC-012).
+
+- **Verification:** typecheck clean, build OK, mock-ctx plugin load (`id=olc`, correct payload),
+  full suite 140/140 pass, real-loader test (`loading plugin`, zero `failed to load plugin`).
+- **Upgrade:** `npm install obsidian-lean-coder@0.1.1`, then list the package in `opencode.json`
+  `plugins` (see README §2).
+
+## [0.1.0] — 2026-10-13 — MVP pre-release
+
+First usable version for controlled testing. One full user journey is covered by an automated end-to-end test (`tests/e2e.test.ts`, OLC-072).
+
+**What works**
+- Safe, idempotent project init (`initProject`): create-only, `preserved` reporting, `needs-decision` flow, `dryRun` preview.
+- Planning workflow: draft/approve/revise/reject `intent.md` + `plan.md`, approval gate (`assertBuildReady`), scope-change return path.
+- Bounded build frame: `beginTask` (identity + approval gate), `recordDecision`, `completeTask` (out-of-scope changes throw `SCOPE_CHANGED`, nothing completed silently).
+- Evidence-backed verification: real command outcomes, bounded retries, escalation list; completion only on full pass.
+- Safe Git checkpoints (`createCheckpoint`) and history-preserving restore (`restoreCheckpoint`): explicit owned paths only, pathspec commits, race guards; `git add .`/`-A`, plain `git commit`, `reset --hard`, and force-push are banned in OLC flows.
+- Continuity: activity log (secret-scrubbed, append-only), resume context (read-only, confirmation-gated), plain-language Indonesian session summaries with event-mapped claims, progressive memory retrieval with project isolation, user-approved taste rules (`pending`→`active`/`rejected`, never silent).
+- Session validation: `startSession` + `assertContextCurrent` revalidation wired into checkpoint/restore (vault unmounted, registry rewritten, or branch switched between operations blocks with zero writes).
+- Packaging: `npm pack` ships `dist/` (17 modules), `agents/olc-plan.md` + `olc-build.md`, `skills/olc-explore/SKILL.md`, 8 `templates/*.md` (56 files, verified OLC-071). No dev-only dependency at runtime (`typescript` excluded).
+- Docs: `README.md` distinguishes dev install vs plugin activation vs project init, with verified commands, troubleshooting, and security notes.
+
+**Known limitations (not fixed in this release)**
+- npm package name/scope unreserved (DECISIONS.md #1); minimum OpenCode version unpinned — smoke-tested against 2.0.27 only (#3).
+- `dist/index.js` exports only `OLC_VERSION`; npm loaders resolve `dist/index.js`, so npm-package activation cannot work until the entrypoint is wired AND a name is reserved. Verified load path is local-file `.opencode/plugins/<name>/index.js` (README §2).
+- `opencode.json` `plugins`/`plugin` pointing at a package directory produced zero load attempts in this build.
+- `/api/agent` + `/api/skill` returned `[]` for project-local files in this build (OLC-012 evidence did not reproduce); README verifies resource placement by file presence.
+- Tool invocation end-to-end through a live model call not exercised (account billing); OLC-072 journey runs fully offline.
+- Raw `approval`/`planning`/`tasks` vault helpers are ungated by design for MVP — all agent-facing write paths go through validated entry points.
+- Pre-existing unrelated change in the working tree (`D .opencode/goals/...` claim file) is not part of this release and was left untouched.
+
+## [0.0.1] — 2026-10-12 — development baseline
+
+Internal scaffolding milestone: repo skeleton, TypeScript ESM build, plugin entrypoint (`olc_status`), config/identity/vault foundations. Not released.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdhb2
+
+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,154 @@
-# Temporary Holding Version
+# OLC — Obsidian Lean Coder
 
-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.
+OpenCode extension for project-scoped planning, memory, and safe Git checkpoints. On npm as `obsidian-lean-coder` (v0.1.1 fixes plugin activation — see CHANGELOG).
+
+## Three separate steps
+
+Do not confuse these. They are different operations with different commands:
+
+| # | Step | What it does | Command |
+|---|------|--------------|---------|
+| 1 | **Dev install** | Install npm deps to hack on OLC itself | `npm ci && npm run build` |
+| 2 | **Plugin activation** | Load OLC as an OpenCode plugin | `npm i obsidian-lean-coder` + `opencode.json` snippet below |
+| 3 | **Project init** | Register one app repo + vault with OLC (`initProject`, idempotent, create-only) | via the `olc-init` skill in OpenCode (the tested path) |
+
+## 1. Dev install
+
+Requirements: Node >= 18.18, npm, git.
+
+```sh
+git clone <this-repo> olc && cd olc
+npm ci
+npm run build    # tsc -p tsconfig.json → dist/
+npm test         # tsc -p tsconfig.tests.json && node --test "dist-tests/tests/**/*.test.js"
+npm run typecheck
+```
+
+Expected: build clean, typecheck clean. `npm test` runs the full suite (currently 140 tests). `npm pack --dry-run` shows what would ship (`dist/`, `agents/`, `skills/`, `templates/`).
+
+> Published on npm as `obsidian-lean-coder` (MIT). Republishing needs a separate explicit approval — never publish by accident.
+
+## 2. Plugin activation
+
+```sh
+npm install obsidian-lean-coder
+```
+
+Then list it in your project's `opencode.json` (npm loaders resolve the package root `dist/index.js`, which since v0.1.1 carries the plugin default export alongside `OLC_VERSION`):
+
+```json
+{
+  "plugins": ["obsidian-lean-coder"]
+}
+```
+
+Verify it loads (from the consuming project directory; the model call itself will fail without account funds, but plugin loading happens first):
+
+```sh
+OPENCODE_LOG_LEVEL=DEBUG opencode run --standalone "hi" --print-logs 2>&1 | grep -E "loading plugin.*obsidian-lean-coder|failed to load plugin"
+```
+
+Expected: a `loading plugin ... obsidian-lean-coder` line and **zero** `failed to load plugin` lines. (Verified 2026-10-13 via the equivalent local-file shape against the real loader; npm-registry install itself verified in OLC-071.)
+
+> `npm install` alone shows nothing in OpenCode — that is normal. The package must be listed under `plugins`, and agents/skills never auto-appear: they are project-local files you copy yourself (next step). No restart or rebuild needed after editing `opencode.json`.
+
+### Local dev path (this checkout, no npm)
+
+An `index.js` under `.opencode/plugins/<name>/` auto-loads with no install step (proven in OLC-011, re-verified in OLC-071). The plugin entrypoint is `dist/plugin.js` (`src/plugin.ts` → `Plugin.define({ id: "olc" })`, one read-only `olc_status` tool, zero writes on load).
+
+In your consuming project (replace `/home/you/olc` with your OLC checkout):
+
+```sh
+PKG=/home/you/olc   # your OLC checkout — build it first (step 1)
+mkdir -p .opencode/plugins/olc
+printf '%s\n' 'export { default } from "file://'"$PKG"'/dist/plugin.js";' > .opencode/plugins/olc/index.js
+printf '%s\n' '{ "type": "module", "dependencies": { "@opencode/plugin": "2.0.27" } }' > .opencode/plugins/olc/package.json
+```
+
+Verify with the same `grep` as above, expecting `.opencode/plugins/olc/index.js` in the loading line.
+
+Then place the agent/skill resources project-locally (DECISIONS.md #2 — programmatic registration was rejected for MVP):
+
+```sh
+PKG=/home/you/olc   # your OLC checkout
+mkdir -p .opencode/agents .opencode/skills/olc-explore
+cp "$PKG"/agents/olc-plan.md "$PKG"/agents/olc-build.md .opencode/agents/
+cp "$PKG"/skills/olc-explore/SKILL.md .opencode/skills/olc-explore/
+```
+
+Discovery note: `/api/agent` and `/api/skill` returned `[]` for project-local files in this build — even for a minimal probe agent — so API listing is not a valid verification (OLC-012 evidence did not reproduce; TUI-side discovery untested). Verify by file presence instead:
+
+```sh
+ls .opencode/agents/olc-plan.md .opencode/agents/olc-build.md .opencode/skills/olc-explore/SKILL.md
+```
+
+`olc-plan`/`olc-build` agents and the `olc-explore` skill are picked up by OpenCode from these paths. Re-running the `cp` commands is safe as long as you have not customized the destination files — `cp` overwrites; the no-clobber guarantee belongs to `olc-init`, which reports existing files as `preserved` instead of overwriting them.
+
+Supported versions: OpenCode 2.x with the V2 plugin API. OLC pins `@opencode/plugin` 2.0.27 to match the CLI it was smoke-tested against (see OLC-011). Other 2.x versions will likely work; 1.x will not. The exact minimum version is still open (DECISIONS.md #3).
+
+## 3. Project init
+
+`initProject` (`src/init/index.ts`) registers one app repo + vault. It is idempotent and **create-only**: existing files are reported `preserved`, never overwritten. Anything needing a human choice comes back as `status: "needs-decision"` — no prompting inside the module.
+
+Run it via the `olc-init` skill inside OpenCode (recommended — the only tested path for MVP). A programmatic import is not yet wired: the package entrypoint (`dist/index.js`) exports `OLC_VERSION` plus the plugin default, and `initProject` lives in `src/init/index.ts` for internal/agent use.
+
+What it creates (only when missing):
+
+- `<repo>/.olc/config.json` — `{ schemaVersion, projectId, vaultPath }`. No secrets (keys matching `secret|token|password|api-key` are rejected).
+- `<repo>/.olc/AGENTS.md` — stub instructions for agents. Review and customize.
+- `<vault>/OLC/Projects/<project_id>/{index.md, current-state.md, decisions/, tasks/, logs/, memory/, taste/}`
+- `<vault>/OLC/registry.json` — `{ projects: { "<id>": { repoRoot } } }` entry for this repo.
+
+Vault path precedence: explicit `vaultPath` > `OLC_VAULT_PATH` env > existing config. OLC never invents a vault location — missing path returns `needs-decision`, never a silent default.
+
+Re-running init is always safe: run it again after pulling updates; `created` becomes `preserved`. To preview without writing: `initProject({ ..., dryRun: true })`.
+
+## Updating
+
+1. `git pull` the OLC checkout.
+2. `npm ci && npm run build && npm test`.
+3. Re-run init for each consuming project (creates only missing files; your vault notes, checkpoints, and taste rules are untouched).
+
+No migration step exists yet — templates live in the package (`templates/`); old vault documents are never auto-migrated.
+
+## Uninstalling
+
+Per consuming project:
+
+```sh
+# 1. Remove OLC resources from the project
+rm -rf .opencode/agents/olc-plan.md .opencode/agents/olc-build.md \
+       .opencode/skills/olc-explore .olc
+# 2. Remove the plugin entry from opencode.json ("plugin": ["file:///..."])
+# 3. Optionally remove the vault scope (YOUR NOTES — back up first):
+#    rm -rf "$VAULT/OLC/Projects/<project_id>"
+# 4. Optionally remove the registry entry in "$VAULT/OLC/registry.json"
+```
+
+No global state, no daemons, no background processes — nothing else to clean up.
+
+## Security notes
+
+- **Never store secrets in `.olc/config.json`** — credential-looking keys are rejected at parse time. Use env vars or a secret manager.
+- **Memory/log writes are secret-scrubbed** (`src/log/index.ts`): known token/key patterns become `[redacted]` before reaching the vault. The scrub list is documented and minimal — treat it as a safety net, not a vault for secrets.
+- **Git safety**: checkpoints stage only explicit OLC-owned paths (`git add -- <paths>`) and commit with a pathspec. `git add .`/`-A`, plain `git commit`, `reset --hard`, and force-push are banned in OLC flows. Ambiguous ownership aborts and asks you.
+- **Wrong-project protection**: every read/write validates `project_id` → repo-root → vault registration first (`validateIdentity`). Mismatches block with zero writes.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---------|-------------|
+| `project_id "x" is not registered` | Run init for this repo, or you are in the wrong checkout. |
+| `Refusing to touch the wrong project's memory` | `project_id` maps to a different repo root. Use a new `projectId` for this checkout or move to the registered repo. |
+| `No vault path configured` | Pass `vaultPath` or set `OLC_VAULT_PATH`. OLC never guesses. |
+| Plugin not listed by `/api/plugin` | Check the `file://` path in `opencode.json` points at the OLC checkout root (containing `dist/`). Rebuild (`npm run build`) — the entrypoint is compiled output. |
+| Agent/skill not discovered | Files must be at `.opencode/agents/<name>.md` / `.opencode/skills/<id>/SKILL.md` relative to the project dir you pass in `location`. Check frontmatter has `description`. |
+| `Detached HEAD` / `SESSION_DRIFT` | Confirm branch + task before continuing — nothing was switched or closed. |
+| `OWNED_PATH_PRESTAGED` / `FOREIGN_EDIT` on checkpoint | Someone (you or a tool) touched OLC-owned files outside the task. Unstage / reconcile, then retry. |
+
+## Docs map
+
+- `docs/PRD.md` — requirements (source of truth for *what*).
+- `docs/TASKS.md` — task board with verification evidence (source of truth for *status*).
+- `docs/DECISIONS.md` — open technical decisions (#1 name, #3 version pin still open).
+- `AGENTS.md` — working rules for agents in this repo.

package/agents/olc-build.md

@@ -0,0 +1,47 @@
+---
+description: OLC build agent — implements one approved task step at a time with evidence-backed verification
+mode: subagent
+---
+
+You are `olc-build`, the implementation agent of OLC (Obsidian Lean Coder).
+You execute approved plans in small bounded steps. You never expand scope on your own.
+
+## Required reading (do this first, every time)
+
+1. The project root `AGENTS.md` (OLC working rules).
+2. `docs/PRD.md` (product requirements, source of truth).
+3. The current task entry in `docs/TASKS.md` and the APPROVED `intent.md` + `plan.md`.
+4. The consuming project's `.olc/AGENTS.md` (project-specific instructions).
+
+## Preconditions (all must hold, or stop)
+
+- The task has an approved plan with bounded acceptance criteria. Missing
+  approval or a context mismatch blocks implementation — propose, do not perform.
+- Validate project identity (config `project_id` vs. vault registry and actual
+  repo root) before any memory operation. On mismatch, stop with an actionable
+  message.
+- Before any Git-sensitive operation, inspect the actual repository root,
+  current branch, HEAD, working tree, diff, and untracked files.
+
+## Execution rules
+
+- Implement ONE approved modular task at a time, within its acceptance criteria.
+- Load only relevant project context. Small technical decisions and fixes inside
+  the approved scope are allowed.
+- Scope, product behavior, accepted risks, or architecture changes require user
+  approval and a plan revision first. Out-of-scope work is proposed, not performed.
+- Run the smallest meaningful checks (tests, typecheck, lint, build) and record
+  exact results. Never fabricate test claims. Retry a fix a bounded number of
+  times, then stop and report attempts with evidence and options.
+- Git safety: never run destructive operations (`reset --hard`, force checkout,
+  `clean`, branch deletion, force-push) without explicit informed approval. Never
+  use `git add .` / `git add -A` for checkpoints — stage explicit paths only.
+  Never stage, commit, or discard changes that are not clearly part of the
+  current task. If ownership is ambiguous, stop and ask.
+- If blocked, stop, document attempts and evidence, and ask for direction.
+
+## Closeout
+
+End every session with a plain-language summary: what changed, observed result,
+tests/checks run with outcomes, what remains or is blocked, the next suggested
+task, and any checkpoint commit reference.

package/agents/olc-plan.md

@@ -0,0 +1,44 @@
+---
+description: OLC planning agent — investigates a task and writes intent.md + plan.md without touching app source
+mode: subagent
+---
+
+You are `olc-plan`, the planning agent of OLC (Obsidian Lean Coder).
+You extend the default planning behavior: investigate first, write the plan down, never code.
+
+## Required reading (do this first, every time)
+
+1. The project root `AGENTS.md` (OLC working rules).
+2. `docs/PRD.md` (product requirements, source of truth).
+3. The current task entry in `docs/TASKS.md` (goal, scope, acceptance criteria).
+4. The consuming project's `.olc/AGENTS.md` (project-specific instructions).
+
+If any of these is missing or the task scope is unclear, stop and ask one focused
+question instead of guessing.
+
+## Investigation
+
+- Inspect the actual repository source and Git state (`git status`, branch, log)
+  before proposing anything. Cite file paths and evidence.
+- Offer both Explore and direct Plan modes; recommend one based on complexity,
+  but let the user choose.
+
+## Hard boundaries
+
+- You MUST NOT modify application source files. No edits, no new source files,
+  no dependency changes, no migrations. Reading is always allowed.
+- The only files you may write are OLC planning documents inside the configured
+  vault (`intent.md`, `plan.md`, plus an explore report when Explore is used).
+- You MUST validate project identity (config `project_id` vs. vault registry)
+  before reading or writing any memory. On mismatch, stop with an actionable
+  message. Never invent a fallback location.
+- Produce/revise `intent.md` and `plan.md` together. Keep what/why (intent)
+  separate from how (plan).
+
+## Output
+
+- Write `intent.md` and `plan.md` for the task, with modular steps, per-step
+  expected results, acceptance criteria, tests, dependencies, risks, and open
+  questions.
+- Do NOT start coding, and do not hand off to `olc-build`, before the user has
+  explicitly approved both documents.

package/dist/approval/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Planning approval and scope-change return path (OLC-034).
+ *
+ * Combines the OLC-032 document gate (both intent.md and plan.md approved)
+ * with the OLC-033 registry gate (task status allows implementation), and
+ * implements the scope-change loop: an approved task whose scope changes
+ * goes back to draft for re-approval instead of silently continuing.
+ *
+ * - `assertBuildReady`: build gate — registry status must be `approved` or
+ *   `in_progress` AND both docs must be `approved`. Anything else throws.
+ * - `requestScopeChange`: park an approved/in-progress task for revision.
+ *   Registry moves `approved → draft` or `in_progress → review` (both are
+ *   table-legal per OLC-033); docs are revised WITHOUT body changes, so
+ *   statuses flip back to `draft` and re-approval becomes mandatory.
+ *   History records the reason plus a reminder that a safe code checkpoint
+ *   (OLC-051 flow) is required before continuing impacted work.
+ * - `resumeAfterRevision`: explicit re-entry after re-approval — approves
+ *   the docs again and moves the registry `draft → approved` or
+ *   `review → in_progress`. Nothing resumes implicitly.
+ */
+import { type TaskStatus } from "../tasks/index.js";
+export type ApprovalErrorCode = "NOT_APPROVED" | "INVALID_STATE";
+export declare class ApprovalError extends Error {
+    readonly code: ApprovalErrorCode;
+    constructor(code: ApprovalErrorCode, message: string);
+}
+/**
+ * Build gate: throws unless the task is registered with a buildable
+ * registry status AND both planning docs are approved. Call before any
+ * implementation work (this is the cross-check OLC-033 left open).
+ */
+export declare function assertBuildReady(vaultRoot: string, projectId: string, taskId: string): void;
+/**
+ * Park a build-ready task for scope revision. Only `approved` and
+ * `in_progress` tasks can enter the scope-change path; anything else is
+ * an error (there is no approved scope to change). Doc bodies are never
+ * touched — only statuses flip to `draft`, so re-approval is mandatory
+ * and the approved plan cannot be silently replaced.
+ */
+export declare function requestScopeChange(vaultRoot: string, projectId: string, taskId: string, reason: string, date: string): {
+    registryFrom: TaskStatus;
+    registryTo: TaskStatus;
+};
+/**
+ * Explicit re-entry after a scope revision: re-approve both docs and move
+ * the registry forward (`draft → approved`, `review → in_progress`).
+ * Only valid for tasks parked by `requestScopeChange`; anything else is
+ * an error. Never runs implicitly.
+ */
+export declare function resumeAfterRevision(vaultRoot: string, projectId: string, taskId: string, date: string): {
+    registryFrom: TaskStatus;
+    registryTo: TaskStatus;
+};

package/dist/approval/index.js

@@ -0,0 +1,123 @@
+/**
+ * Planning approval and scope-change return path (OLC-034).
+ *
+ * Combines the OLC-032 document gate (both intent.md and plan.md approved)
+ * with the OLC-033 registry gate (task status allows implementation), and
+ * implements the scope-change loop: an approved task whose scope changes
+ * goes back to draft for re-approval instead of silently continuing.
+ *
+ * - `assertBuildReady`: build gate — registry status must be `approved` or
+ *   `in_progress` AND both docs must be `approved`. Anything else throws.
+ * - `requestScopeChange`: park an approved/in-progress task for revision.
+ *   Registry moves `approved → draft` or `in_progress → review` (both are
+ *   table-legal per OLC-033); docs are revised WITHOUT body changes, so
+ *   statuses flip back to `draft` and re-approval becomes mandatory.
+ *   History records the reason plus a reminder that a safe code checkpoint
+ *   (OLC-051 flow) is required before continuing impacted work.
+ * - `resumeAfterRevision`: explicit re-entry after re-approval — approves
+ *   the docs again and moves the registry `draft → approved` or
+ *   `review → in_progress`. Nothing resumes implicitly.
+ */
+import { PlanningError, approveTaskDocs, assertApproved, reviseTaskDocs, } from "../planning/index.js";
+import { TaskRegistryError, getTask, setTaskStatus, } from "../tasks/index.js";
+export class ApprovalError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ApprovalError";
+        this.code = code;
+    }
+}
+/** Registry statuses under which implementation work may proceed (docs permitting). */
+const BUILDABLE_STATUSES = ["approved", "in_progress"];
+/**
+ * Build gate: throws unless the task is registered with a buildable
+ * registry status AND both planning docs are approved. Call before any
+ * implementation work (this is the cross-check OLC-033 left open).
+ */
+export function assertBuildReady(vaultRoot, projectId, taskId) {
+    const entry = getTask(vaultRoot, projectId, taskId);
+    if (!entry) {
+        throw new ApprovalError("NOT_APPROVED", `Task ${taskId} is not registered. Register it, draft intent.md/plan.md, and get them approved before coding.`);
+    }
+    if (!BUILDABLE_STATUSES.includes(entry.status)) {
+        throw new ApprovalError("NOT_APPROVED", `Task ${taskId} is not approved for implementation: registry status is ${entry.status} ` +
+            `(needs approved or in_progress). Move it through the transition table first.`);
+    }
+    try {
+        assertApproved(vaultRoot, projectId, taskId);
+    }
+    catch (error) {
+        if (error instanceof PlanningError) {
+            throw new ApprovalError("NOT_APPROVED", error.message);
+        }
+        throw error;
+    }
+}
+/**
+ * Park a build-ready task for scope revision. Only `approved` and
+ * `in_progress` tasks can enter the scope-change path; anything else is
+ * an error (there is no approved scope to change). Doc bodies are never
+ * touched — only statuses flip to `draft`, so re-approval is mandatory
+ * and the approved plan cannot be silently replaced.
+ */
+export function requestScopeChange(vaultRoot, projectId, taskId, reason, date) {
+    const entry = getTask(vaultRoot, projectId, taskId);
+    if (!entry) {
+        throw new ApprovalError("INVALID_STATE", `Cannot request a scope change for unknown task ${taskId}. Register and approve it first.`);
+    }
+    if (entry.status !== "approved" && entry.status !== "in_progress") {
+        throw new ApprovalError("INVALID_STATE", `Cannot request a scope change for task ${taskId}: registry status is ${entry.status}, ` +
+            "not approved or in_progress. There is no approved scope to change — revise the draft instead.");
+    }
+    // Docs must currently be approved, otherwise the task is already parked.
+    try {
+        assertApproved(vaultRoot, projectId, taskId);
+    }
+    catch (error) {
+        if (error instanceof PlanningError) {
+            throw new ApprovalError("INVALID_STATE", `Task ${taskId} is already parked for revision (${error.message}). Re-approve the docs instead of opening another scope change.`);
+        }
+        throw error;
+    }
+    const registryTo = entry.status === "approved" ? "draft" : "review";
+    try {
+        setTaskStatus(vaultRoot, projectId, taskId, registryTo, date);
+    }
+    catch (error) {
+        if (error instanceof TaskRegistryError) {
+            throw new ApprovalError("INVALID_STATE", error.message);
+        }
+        throw error;
+    }
+    reviseTaskDocs(vaultRoot, projectId, taskId, `SCOPE CHANGE requested: ${reason}\n\nSafe code checkpoint of current progress is required (OLC-051 flow) before continuing impacted work. Re-approval of both documents is mandatory.`, date);
+    return { registryFrom: entry.status, registryTo };
+}
+/**
+ * Explicit re-entry after a scope revision: re-approve both docs and move
+ * the registry forward (`draft → approved`, `review → in_progress`).
+ * Only valid for tasks parked by `requestScopeChange`; anything else is
+ * an error. Never runs implicitly.
+ */
+export function resumeAfterRevision(vaultRoot, projectId, taskId, date) {
+    const entry = getTask(vaultRoot, projectId, taskId);
+    if (!entry) {
+        throw new ApprovalError("INVALID_STATE", `Cannot resume unknown task ${taskId}. Register it first.`);
+    }
+    const registryTo = entry.status === "draft" ? "approved" : entry.status === "review" ? "in_progress" : null;
+    if (registryTo === null) {
+        throw new ApprovalError("INVALID_STATE", `Task ${taskId} is not parked for revision (registry status ${entry.status}). ` +
+            "Only draft (from approved) or review (from in_progress) tasks parked by a scope change can resume here.");
+    }
+    approveTaskDocs(vaultRoot, projectId, taskId, date);
+    try {
+        setTaskStatus(vaultRoot, projectId, taskId, registryTo, date);
+    }
+    catch (error) {
+        if (error instanceof TaskRegistryError) {
+            throw new ApprovalError("INVALID_STATE", error.message);
+        }
+        throw error;
+    }
+    return { registryFrom: entry.status, registryTo };
+}

package/dist/build/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OLC-040 — bounded `olc-build` task execution frame.
+ *
+ * The agent does the coding; this module enforces the bounds:
+ * 1. `beginTask` — identity (OLC-021, via the loaded OLC-020 config) and the
+ *    approval gate (OLC-034) must pass, otherwise implementation is blocked
+ *    before it starts. Returns a frame carrying ONLY the approved task's
+ *    context (intent/plan bodies), never the whole vault. The caller declares
+ *    which repo-relative paths it will touch; the registry task moves
+ *    approved→in_progress.
+ * 2. `recordDecision` — small in-scope technical decisions go to history.md.
+ * 3. `completeTask` — identity re-checked, then the working tree is diffed:
+ *    any change outside the declared paths throws SCOPE_CHANGED (out-of-scope
+ *    work is proposed via the error, not performed). Clean frames move the
+ *    registry task in_progress→review.
+ *
+ * Git access here is deliberately minimal (HEAD sha + porcelain status);
+ * the full inspection module is OLC-051's job and may consolidate these.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+export type BuildErrorCode = "NOT_READY" | "CONTEXT_MISMATCH" | "SCOPE_CHANGED" | "NO_TASK";
+export declare class BuildError extends Error {
+    readonly code: BuildErrorCode;
+    readonly details?: string[];
+    constructor(code: BuildErrorCode, message: string, details?: string[]);
+}
+export interface BeginTaskInput {
+    /** Loaded + vault-resolved project config (OLC-020). */
+    config: ResolvedConfig;
+    taskId: string;
+    /** Repo-relative paths the implementation may touch. Empty = docs-only task. */
+    touchPaths?: string[];
+    /** Directory inside the project repo (identity is checked from here). */
+    startDir?: string;
+    /** Override for today (tests); defaults to current UTC date. */
+    date?: string;
+}
+export interface BuildFrame {
+    taskId: string;
+    intentBody: string;
+    planBody: string;
+    declaredPaths: string[];
+    baseHead: string;
+    startedAt: string;
+}
+/** Repo-relative changed paths (staged + unstaged + untracked) vs current HEAD. */
+export declare function changedPaths(projectRoot: string): string[];
+export declare function beginTask(input: BeginTaskInput): BuildFrame;
+export declare function recordDecision(frame: Pick<BuildFrame, "taskId">, config: ResolvedConfig, text: string, date?: string): void;
+export declare function completeTask(frame: BuildFrame, config: ResolvedConfig, repoRoot: string, date?: string): {
+    changed: string[];
+};