npm - @opellen/opengoal - Versions diffs - 1.0.2 → 1.0.3 - Mend

@opellen/opengoal 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.ja.md +4 -2
package/README.ko.md +4 -2
package/README.md +417 -415
package/README.zh-CN.md +4 -2
package/package.json +1 -1
package/templates/commands/context.md +1 -1
package/templates/commands/goal.md +4 -2
package/templates/commands/verify.md +1 -0
package/templates/skills/opengoal-flow/SKILL.md +13 -3

package/README.ja.md CHANGED Viewed

@@ -83,7 +83,8 @@ docs/
 ├── DESIGN.md        ← Implementation design (as needed)
 ├── PLAN.md          ← Implementation plan (auto-generated for complex tasks)
 ├── ROADMAP.md       ← Milestone-based overall plan
-├── BACKLOG.md       ← Deferred out-of-scope discoveries
+├── BACKLOG.md       ← 優先度キュー (最大3行、ゴールアーカイブ時に整理)
+├── backlog/          ← 詳細な発見事項(open/)およびドロップ/アーカイブ履歴(archive/)
 ├── OVERVIEW.md      ← Full project overview (as needed)
 └── suspended/       ← Suspended goals and parked sub-goals
 ```
@@ -96,7 +97,8 @@ docs/
 | `DESIGN.md` | どう実装するか? | ゴール達成まで |
 | `PLAN.md` | このタスクをどう実装するか? | 自動生成 → 自動アーカイブ |
 | `ROADMAP.md` | 全体の中で今どこにいるか? | プロジェクトの存続期間 |
-| `BACKLOG.md` | 発見したが後回しにしたことは何か? | プロジェクトの存続期間 |
+| `BACKLOG.md` | 発見したが後回しにしたことは何か? | ゴールアーカイブ時に整理 |
+| `backlog/` | 詳細な分析とドロップ履歴はどこにあるか? | 恒久保存 / アーカイブ |
 | `OVERVIEW.md` | プロジェクト全体はどんな姿か? | プロジェクトの存続期間 |
 `GOAL.md`だけから始めて`ROADMAP.md`へ広げていくのでも、`ROADMAP.md`で全体像を描いてから`GOAL.md`へ落とし込んでいくのでも構いません。どちらの進め方でも、OpenGoalは「今何をすべきか」をMarkdown上に見える状態に保ちます。

package/README.ko.md CHANGED Viewed

@@ -80,7 +80,8 @@ docs/
 ├── DESIGN.md        ← 구현 설계 (필요 시)
 ├── PLAN.md          ← 구현 계획 (복잡한 태스크에서 자동 생성)
 ├── ROADMAP.md       ← 마일스톤 단위 전체 계획
-├── BACKLOG.md       ← 범위 밖 발견 사항 보관
+├── BACKLOG.md       ← 우선순위 큐 (최대 3줄, 목표 아카이브 시 정리)
+├── backlog/          ← 상세 분석(open/) 및 드롭/아카이브 이력(archive/)
 ├── OVERVIEW.md      ← 프로젝트 전체 조망 (필요 시)
 └── suspended/       ← 중단된 목표 및 대기 중인 서브골
 ```
@@ -93,7 +94,8 @@ docs/
 | `DESIGN.md` | 어떻게 구현하지? | 목표 달성까지 |
 | `PLAN.md` | 이 작업을 어떻게 구현하지? | 자동 생성 → 자동 아카이브 |
 | `ROADMAP.md` | 큰 그림에서 지금 어디쯤에 있지? | 프로젝트 전체 |
-| `BACKLOG.md` | 발견했지만 미뤄둔 건 뭐지? | 프로젝트 전체 |
+| `BACKLOG.md` | 발견했지만 미뤄둔 건 뭐지? | 목표 아카이브 시 스윕 |
+| `backlog/` | 상세 분석과 드롭된 이력은 어디 있지? | 영구 보관 / 아카이브 |
 | `OVERVIEW.md` | 프로젝트 전체를 한눈에 조망하면? | 프로젝트 전체 |
 `GOAL.md` 하나로 작게 시작해서 `ROADMAP.md`로 확장해도 되고, `ROADMAP.md`에서 큰 그림을 그리고 `GOAL.md`로 내려와도 됩니다. 어느 방향으로 가든 OpenGoal은 '지금 당장 해야 할 일'을 마크다운으로 한 눈에 보이게 유지합니다.

package/README.md CHANGED Viewed

@@ -1,415 +1,417 @@
-<div align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/opengoal-banner-light.webp">
-    <img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/opengoal-banner-dark.webp" alt="OpenGoal — goal-centric AI harness"/>
-  </picture>
-  <p>One question, one file — <code>CONTEXT.md</code>, <code>GOAL.md</code>, <code>ROADMAP.md</code></p>
-  <p>
-    Open <code>GOAL.md</code> and see <b>what to do now</b>.<br/>
-    Open <code>CONTEXT.md</code> and see <b>the current context</b>.<br/>
-    Open <code>ROADMAP.md</code> and see <b>the current big picture</b>.
-  </p>
-  <p><strong>English</strong> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a></p>
-</div>
-## What is it?
-OpenGoal keeps the current goal visible, in plain markdown, for both you and your AI agent.
-One npx command installs markdown slash-commands and agent skills into your project. After that
-there is no runtime — no CLI in the loop, no hooks intercepting your actions, no MCP server
-holding tool definitions open. What is left on disk is markdown your agent reads and you can
-edit in any editor.
-## What does it solve?
-**What you need to do right now isn't visible.**
-The current goal ends up scattered across state files, task lists, and design documents.
-You can't open one file and immediately see what to do next — and neither can your agent,
-which is worse, because it will confidently proceed from whichever fragment it read last.
-In OpenGoal, one question maps to one file.
-```text
-ROADMAP.md  ─────────  where am I in the big picture?
-     CONTEXT.md  ──────  what is this project?
-            ● GOAL.md  ──  what do I do now?
-```
-**Keeping context shouldn't cost more than the context.**
-Frameworks that maintain state across sessions tend to reach for CLIs, hooks, and MCP servers.
-Light exploration triggers a CLI run, hooks intercept every action, and a configured MCP server
-spends tokens on tool definitions in sessions that never call them. Persistence is worth paying
-for; that price isn't.
-## Quick start
-```bash
-npx @opellen/opengoal init
-```
-Markdown commands are installed in your project. No CLI needed after this.
-```
-/opgl:scout          # Start session — just remember this
-```
-Whether it's a new project or an existing codebase, scout reads the current state and guides you to the next step.
-Got existing code? It starts with context setup (`/opgl:context`). Empty project? It starts by exploring your idea through conversation.
-Most commands auto-run `init` on first use — `/opgl:goal "my goal"` works immediately without typing `init`.
-### Options
-```bash
-opengoal init --docs .planning      # Use a different path instead of docs/
-opengoal init --codebase src        # Point templates at a sub-directory codebase (default: .)
-opengoal init --tools cursor        # Install for a specific tool
-opengoal init --tools cursor,windsurf  # Multiple tools
-opengoal init --no-subagent         # Disable subagent delegation (enabled by default)
-opengoal init --root path/to/proj   # Install into a different project directory
-opengoal init --force               # Overwrite existing files
-opengoal init --dry-run             # Preview files to install
-opengoal init --prefix <name>       # Slash-command prefix (default: opgl)
-opengoal init --from-prefix <name>  # Clean up command files left by a previous prefix
-```
-`--tools` targets `Claude Code`, `Cursor`, `Windsurf`, and [20+ others](docs/supported-tools.md).
-## Document structure
-```
-docs/
-├── CONTEXT.md       ← Project context, principles, workflow
-├── GOAL.md          ← Current objective and checklist
-├── CHECKPOINT.md    ← Last session progress
-├── DESIGN.md        ← Implementation design (as needed)
-├── PLAN.md          ← Implementation plan (auto-generated for complex tasks)
-├── ROADMAP.md       ← Milestone-based overall plan
-├── BACKLOG.md       ← Deferred out-of-scope discoveries
-├── OVERVIEW.md      ← Full project overview (as needed)
-└── suspended/       ← Suspended goals and parked sub-goals
-```
-| Document | Question it answers | Lifespan |
-|----------|-------------------|----------|
-| `CONTEXT.md` | What is this project and how do I work on it? | Project lifetime |
-| `GOAL.md` | What should I do right now? | Until goal is achieved |
-| `CHECKPOINT.md` | Where did the last session leave off? | Per session (overwritten) |
-| `DESIGN.md` | How do I implement this? | Until goal is achieved |
-| `PLAN.md` | How do I implement this task? | Auto-generated → auto-archived |
-| `ROADMAP.md` | Where am I in the big picture? | Project lifetime |
-| `BACKLOG.md` | What did I discover but defer? | Project lifetime |
-| `OVERVIEW.md` | What does this whole project look like? | Project lifetime |
-Start with just `GOAL.md` and expand to `ROADMAP.md`, or lay out the big picture in `ROADMAP.md` and drill down to `GOAL.md`. Either way, OpenGoal keeps "what to do now" visible on markdown.
-<details>
-<summary>GOAL.md example</summary>
-```markdown
----
-id: session-auth
-goal: Migrate auth from JWT to session-based
-status: in-progress
-started: 2026-04-04
----
-## Tasks
-- [x] 1. Set up session store
-- [ ] 2. Replace middleware — Step 1/2 (session middleware in progress)
-  - [x] 2.1. Implement session middleware
-  - [ ] 2.2. Remove legacy JWT code
-- [ ] 3. DB schema migration
-- [ ] 4. Integration tests
-```
-</details>
-<details>
-<summary>CONTEXT.md example</summary>
-```markdown
-# Project Overview
-Express + PostgreSQL REST API server.
-Auth migration from JWT to session-based in progress.
-# Architecture
-- src/server/ — HTTP routing (Express)
-- src/auth/ — Auth middleware
-- src/db/ — Database access layer
-# Principles
-- Zero downtime during migration
-- Backward compatibility with existing clients
-# Resources
-- DB: PostgreSQL 14, migrations via prisma
-- Auth: express-session + connect-pg-simple
-```
-</details>
-<details>
-<summary>ROADMAP.md example</summary>
-```markdown
----
-id: api-v2
-title: API v2 migration
-status: active
-started: 2026-03-01
----
-- [x] **M1: Auth migration**
-- [ ] **M2: Rate limiting**
-- [ ] **M3: API versioning**
-```
-</details>
-## Commands
-| | Command | Description |
-|---|---------|-------------|
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-scout-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-scout.webp" alt="" width="20"/></picture> | `/opgl:scout` | Start session — read docs, assess current state, suggest next action |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-go-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-go.webp" alt="" width="20"/></picture> | `/opgl:go` | Execute goal — proceed through `GOAL.md` tasks in order |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-context-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-context.webp" alt="" width="20"/></picture> | `/opgl:context` | Create and sync `CONTEXT.md` |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-goal-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-goal.webp" alt="" width="20"/></picture> | `/opgl:goal` | `GOAL.md` management (init, breakdown, checkpoint, suspend, resume, subgoal, archive) |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-design-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-design.webp" alt="" width="20"/></picture> | `/opgl:design` | `DESIGN.md` management (init, sync, archive) |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-roadmap-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-roadmap.webp" alt="" width="20"/></picture> | `/opgl:roadmap` | `ROADMAP.md` milestone management (init, add, archive) |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-overview-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-overview.webp" alt="" width="20"/></picture> | `/opgl:overview` | `OVERVIEW.md` full project overview |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-verify-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-verify.webp" alt="" width="20"/></picture> | `/opgl:verify` | Verify consistency across goal, design, and implementation |
-| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-recap-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-recap.webp" alt="" width="20"/></picture> | `/opgl:recap` | Session wrap-up — sync decisions into living documents |
-Two skills install alongside them — `opengoal-flow` (when to document, when to checkpoint,
-and when a discovery becomes a goal of its own) and `opengoal-subagent` (how work is split,
-and what the main agent never hands off). You never invoke a skill directly; the commands
-load them when they need them.
-### Invocation
-You don't always need to type `/opgl:` — when intent is clear from context, natural language works too.
-| Path | `/opgl` required? | Example |
-|------|-------------------|---------|
-| **Explicit invocation** | Yes | `/opgl goal init`, `/opgl:goal init & design init` |
-| **Confirming a recent recommendation** | No | AI: "Recommend `/opgl:goal init`" → User: "ok" / "go" |
-| **Continuation in active flow** | No | (after goal init) User: "breakdown now" |
-| **Task-execution intent** | No | "proceed with task 6" → `/opgl:go`, "save progress" → `/opgl:goal checkpoint` |
-With clear context, natural language alone triggers execution. `/opgl` serves as an escape hatch when context is ambiguous.
-## Usage flow
-### Applying to an existing project
-```
-You: /opgl:scout
-AI:  Found an existing codebase. No CONTEXT.md yet.
-     Set up project context with `/opgl:context`?
-You: /opgl:context init
-AI:  ✓ docs/CONTEXT.md created
-     To set a goal: `/opgl:goal init`
-You: /opgl:goal Migrate auth module from JWT to session-based
-AI:  ✓ docs/GOAL.md created (5 tasks)
-     Recommend `/opgl:design init` — implementation task with file-level decisions.
-You: /opgl:design init
-AI:  ✓ docs/DESIGN.md created
-     Session store selection, migration strategy, rollback plan included
-You: /opgl:go
-AI:  Task 1/5: Set up session store... ✓ done
-     Task 2/5: Replace middleware... ✓ done
-     Task 3/5 requires DB schema changes. Proceed?
-```
-### New project
-```
-You: /opgl:scout Let's discuss building a real-time collaborative editor
-AI:  (Discovery Mode — exploring tech stack, requirements, constraints)
-     ...
-     ✓ docs/CONTEXT.md created
-You: /opgl:roadmap init
-AI:  ✓ docs/ROADMAP.md created
-     ├── M1: Core editor engine
-     ├── M2: Real-time sync (CRDT)
-     └── M3: Deployment & infrastructure
-You: /opgl:goal
-AI:  Selecting M1 from ROADMAP.md.
-     ✓ docs/GOAL.md created
-You: /opgl:goal breakdown
-AI:  Decomposed into 7 subtasks
-You: /opgl:goal breakdown 3
-AI:  Decomposed Task 3 into 4 subtasks (3.1–3.4)
-You: /opgl:go
-AI:  Task 1/7: Project initialization... ✓ done
-     Task 2/7: Editor core implementation... ✓ done
-     Task 3/7: CRDT sync engine... ✓ done
-You: /opgl:goal checkpoint
-AI:  ✓ docs/CHECKPOINT.md saved
-     (If the session drops, the next one picks up where you left off)
-     ... (continue in next session, all tasks complete)
-You: /opgl:goal archive
-AI:  ✓ Archived 4 files to docs/archive/goals/2026-04-04-editor-core/
-     (GOAL.md, DESIGN.md, PLAN.md, CHECKPOINT.md)
-     Marked M1 done in ROADMAP.md.
-```
-### Resuming work
-```
-You: /opgl:scout
-AI:  CONTEXT.md ✓ | GOAL.md ✓ (3/5 complete)
-     You were working on API endpoints in the previous session.
-     Resume with `/opgl:go`?
-```
-### After a context compaction
-When the conversation gets compacted mid-work, just re-invoke the command:
-```
-You: /opgl:go
-AI:  GOAL.md ✓ (3/7 complete) — Task 4, Step 2/3
-     Resuming: conflict resolution in the CRDT sync engine.
-```
-One command brings everything back — `GOAL.md`, and the checkpoint if you made one — and work continues from the `— Step N/M` annotation instead of starting over. Use `/opgl:scout` if you want a state report first.
-### Handling blockers
-When something comes up mid-goal that must be fixed first:
-```
-You: (during Goal A) Let's fix this dependency bug first.
-AI:  Suggest: /opgl:goal suspend + /opgl:goal init "Fix dependency bug"
-You: ok
-AI:  ✓ Goal A suspended to docs/suspended/goal-a/
-     ✓ New GOAL.md created for the blocker.
-     ... (work through the blocker, archive when done)
-You: /opgl:goal resume
-AI:  Resumed: Goal A. Continue with /opgl:go?
-```
-Nested blockers follow the same pattern — suspend stacks, resume presents a list when multiple goals are paused. If a sub-goal is active, park it first with `/opgl:goal subgoal pause` — `suspend` and `init` are refused while one is active.
-### Handling sub-goals
-Sometimes what comes up isn't a blocker — the goal can still move forward — but it's bigger than a task, needed now, and a different kind of work than the goal itself, so it can't just wait in `BACKLOG.md` either:
-```
-You: (during Goal A: job-application pipeline) I need a YAML→PDF portfolio builder for this — it needs its own architecture decisions first.
-AI:  Doesn't block Goal A, but it's too big to just do inline. Suggest: /opgl:goal subgoal init "Portfolio PDF builder"
-You: ok
-AI:  ✓ Goal A parked to docs/suspended/job-application-pipeline/
-     ✓ New GOAL.md created, linked to Goal A.
-     ... (design and build the portfolio tool, archive when done)
-AI:  ✓ Sub-goal archived. Back on Goal A — pointer task checked off.
-```
-If the goal can't proceed without it, park it as a blocker instead — see above.
-## In the field
-The same goal documents carry a multi-year application build and a weekend plugin.
-That range is the point.
-**Long-horizon builds**
-- [Planura](https://github.com/opellen/Planura) — a native direct-modeling 3D application
-  (C++20 / Qt 6 / OpenGL): half-edge geometry kernel, CSG solid modeling, inference-driven
-  drawing, on [Ordo](https://github.com/opellen/Ordo), its purpose-built application framework.
-- [Ordo](https://github.com/opellen/Ordo) — a typed-event application framework for C++20, extracted from
-  Planura. An event is a plain struct: the type is the identity, the fields are the payload.
-- Reverse-engineering campaigns — the domain OpenGoal was designed in, where the goal is
-  large, the path is unknown, and progress depends on splitting it finely.
-**Applications & tools**
-- [SeedNote](https://github.com/opellen/Seed-Note) — a structured block editor for Android (Kotlin / Jetpack Compose)
-- [ScreenUse](https://github.com/opellen/Screen-Use) — a scenario-driven UI replay and verification tool that drives a real app and records it
-- [OpenIllust](https://github.com/opellen/OpenIllust) — campaign-driven AI vector asset production for Claude Code and
-  Codex; the logo set in this repository was produced with it
-**Focused tools**
-- [Hilo](https://github.com/opellen/Hilo) — an Obsidian highlighting plugin
-- [Loft](https://github.com/opellen/Loft) — an Obsidian image upload plugin
-## From the **gap**
-> **It didn't start with application development.**
->
-> OpenGoal was built for work where the goal is large, the path is unknown, and progress
-> only comes from splitting the unknown into small, verifiable steps that a human and an
-> agent can hand back and forth over a long horizon — long reverse-engineering campaigns,
-> in the original case. Everything else it is used for inherited that shape.
->
-> **Heavy workflows weren't always necessary.**
->
-> All I wanted was a small fix — did I really need all this?
-> Exhaustive discussions with question bombardment and airtight specifications weren't always necessary.
-> Thorough processes are appealing. But AI kept absorbing more and more,
-> and I started to think that maybe the safety nets we want to lean on were, in many cases, becoming excessive shackles.
-> Yet context needed to persist.
->
-> **I wanted to focus on the present.**
->
-> I wanted to pull the "current goal" out from under specs and task lists.
-> I wanted to create a "present" that both I and AI could immediately understand and focus on.
-> Whether you grow from small to large, or descend from the big picture —
-> either direction, I wanted a structure where "what to do now" is immediately visible.
->
-> **I wanted to fill the gap.**
->
-> I sometimes start with OpenSpec and cross over to OpenGoal, and vice versa.
-> Sometimes I equip Superpowers.
-> What works well should still be used well.
-> I needed something that could sit in front of — or between — completeness and power.
-## Notation
-OpenGoal's commands and skills aren't written as plain prose. They follow a small markdown notation — `## Constraints`, `(condition) => action` dispatch rules, `for each`, `loop until`.
-The form follows published work on pseudocode prompting. CodeAgents (2025) reported that describing agent workflows as pseudocode rather than prose cut token usage by 55–87% while improving task performance by 3–36 points.
-The syntax and priority rules are documented in [docs/NOTATION.md](docs/NOTATION.md) — useful if you tweak the installed commands in your own project. For the rationale and research background behind the notation, see [docs/notation-guide.md](docs/notation-guide.md).
-## Contributing
-Issues are welcome — bugs, questions, ideas, disagreements.
-Pull requests are accepted for platform adapters (`src/platforms/`); I maintain the
-prompt templates myself. See [CONTRIBUTING.md](CONTRIBUTING.md).
-### Development
-```bash
-git clone https://github.com/opellen/OpenGoal.git
-cd OpenGoal
-npm install
-npm run build
-npm test
-```
-## License
-MIT License — see [LICENSE](LICENSE) for details.
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/opengoal-banner-light.webp">
+    <img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/opengoal-banner-dark.webp" alt="OpenGoal — goal-centric AI harness"/>
+  </picture>
+  <p>One question, one file — <code>CONTEXT.md</code>, <code>GOAL.md</code>, <code>ROADMAP.md</code></p>
+  <p>
+    Open <code>GOAL.md</code> and see <b>what to do now</b>.<br/>
+    Open <code>CONTEXT.md</code> and see <b>the current context</b>.<br/>
+    Open <code>ROADMAP.md</code> and see <b>the current big picture</b>.
+  </p>
+  <p><strong>English</strong> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a></p>
+</div>
+## What is it?
+OpenGoal keeps the current goal visible, in plain markdown, for both you and your AI agent.
+One npx command installs markdown slash-commands and agent skills into your project. After that
+there is no runtime — no CLI in the loop, no hooks intercepting your actions, no MCP server
+holding tool definitions open. What is left on disk is markdown your agent reads and you can
+edit in any editor.
+## What does it solve?
+**What you need to do right now isn't visible.**
+The current goal ends up scattered across state files, task lists, and design documents.
+You can't open one file and immediately see what to do next — and neither can your agent,
+which is worse, because it will confidently proceed from whichever fragment it read last.
+In OpenGoal, one question maps to one file.
+```text
+ROADMAP.md  ─────────  where am I in the big picture?
+     CONTEXT.md  ──────  what is this project?
+            ● GOAL.md  ──  what do I do now?
+```
+**Keeping context shouldn't cost more than the context.**
+Frameworks that maintain state across sessions tend to reach for CLIs, hooks, and MCP servers.
+Light exploration triggers a CLI run, hooks intercept every action, and a configured MCP server
+spends tokens on tool definitions in sessions that never call them. Persistence is worth paying
+for; that price isn't.
+## Quick start
+```bash
+npx @opellen/opengoal init
+```
+Markdown commands are installed in your project. No CLI needed after this.
+```
+/opgl:scout          # Start session — just remember this
+```
+Whether it's a new project or an existing codebase, scout reads the current state and guides you to the next step.
+Got existing code? It starts with context setup (`/opgl:context`). Empty project? It starts by exploring your idea through conversation.
+Most commands auto-run `init` on first use — `/opgl:goal "my goal"` works immediately without typing `init`.
+### Options
+```bash
+opengoal init --docs .planning      # Use a different path instead of docs/
+opengoal init --codebase src        # Point templates at a sub-directory codebase (default: .)
+opengoal init --tools cursor        # Install for a specific tool
+opengoal init --tools cursor,windsurf  # Multiple tools
+opengoal init --no-subagent         # Disable subagent delegation (enabled by default)
+opengoal init --root path/to/proj   # Install into a different project directory
+opengoal init --force               # Overwrite existing files
+opengoal init --dry-run             # Preview files to install
+opengoal init --prefix <name>       # Slash-command prefix (default: opgl)
+opengoal init --from-prefix <name>  # Clean up command files left by a previous prefix
+```
+`--tools` targets `Claude Code`, `Cursor`, `Windsurf`, and [20+ others](docs/supported-tools.md).
+## Document structure
+```
+docs/
+├── CONTEXT.md       ← Project context, principles, workflow
+├── GOAL.md          ← Current objective and checklist
+├── CHECKPOINT.md    ← Last session progress
+├── DESIGN.md        ← Implementation design (as needed)
+├── PLAN.md          ← Implementation plan (auto-generated for complex tasks)
+├── ROADMAP.md       ← Milestone-based overall plan
+├── BACKLOG.md       ← Priority queue for out-of-scope discoveries (max 3 lines)
+├── backlog/          ← Detailed findings (open/) and dropped archive (archive/)
+├── OVERVIEW.md      ← Full project overview (as needed)
+└── suspended/       ← Suspended goals and parked sub-goals
+```
+| Document | Question it answers | Lifespan |
+|----------|-------------------|----------|
+| `CONTEXT.md` | What is this project and how do I work on it? | Project lifetime |
+| `GOAL.md` | What should I do right now? | Until goal is achieved |
+| `CHECKPOINT.md` | Where did the last session leave off? | Per session (overwritten) |
+| `DESIGN.md` | How do I implement this? | Until goal is achieved |
+| `PLAN.md` | How do I implement this task? | Auto-generated → auto-archived |
+| `ROADMAP.md` | Where am I in the big picture? | Project lifetime |
+| `BACKLOG.md` | What did I discover but defer? | Swept on goal archive |
+| `backlog/` | What are the detailed findings and dropped records? | Persistent / archived |
+| `OVERVIEW.md` | What does this whole project look like? | Project lifetime |
+Start with just `GOAL.md` and expand to `ROADMAP.md`, or lay out the big picture in `ROADMAP.md` and drill down to `GOAL.md`. Either way, OpenGoal keeps "what to do now" visible on markdown.
+<details>
+<summary>GOAL.md example</summary>
+```markdown
+---
+id: session-auth
+goal: Migrate auth from JWT to session-based
+status: in-progress
+started: 2026-04-04
+---
+## Tasks
+- [x] 1. Set up session store
+- [ ] 2. Replace middleware — Step 1/2 (session middleware in progress)
+  - [x] 2.1. Implement session middleware
+  - [ ] 2.2. Remove legacy JWT code
+- [ ] 3. DB schema migration
+- [ ] 4. Integration tests
+```
+</details>
+<details>
+<summary>CONTEXT.md example</summary>
+```markdown
+# Project Overview
+Express + PostgreSQL REST API server.
+Auth migration from JWT to session-based in progress.
+# Architecture
+- src/server/ — HTTP routing (Express)
+- src/auth/ — Auth middleware
+- src/db/ — Database access layer
+# Principles
+- Zero downtime during migration
+- Backward compatibility with existing clients
+# Resources
+- DB: PostgreSQL 14, migrations via prisma
+- Auth: express-session + connect-pg-simple
+```
+</details>
+<details>
+<summary>ROADMAP.md example</summary>
+```markdown
+---
+id: api-v2
+title: API v2 migration
+status: active
+started: 2026-03-01
+---
+- [x] **M1: Auth migration**
+- [ ] **M2: Rate limiting**
+- [ ] **M3: API versioning**
+```
+</details>
+## Commands
+| | Command | Description |
+|---|---------|-------------|
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-scout-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-scout.webp" alt="" width="20"/></picture> | `/opgl:scout` | Start session — read docs, assess current state, suggest next action |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-go-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-go.webp" alt="" width="20"/></picture> | `/opgl:go` | Execute goal — proceed through `GOAL.md` tasks in order |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-context-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-context.webp" alt="" width="20"/></picture> | `/opgl:context` | Create and sync `CONTEXT.md` |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-goal-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-goal.webp" alt="" width="20"/></picture> | `/opgl:goal` | `GOAL.md` management (init, breakdown, checkpoint, suspend, resume, subgoal, archive) |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-design-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-design.webp" alt="" width="20"/></picture> | `/opgl:design` | `DESIGN.md` management (init, sync, archive) |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-roadmap-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-roadmap.webp" alt="" width="20"/></picture> | `/opgl:roadmap` | `ROADMAP.md` milestone management (init, add, archive) |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-overview-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-overview.webp" alt="" width="20"/></picture> | `/opgl:overview` | `OVERVIEW.md` full project overview |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-verify-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-verify.webp" alt="" width="20"/></picture> | `/opgl:verify` | Verify consistency across goal, design, and implementation |
+| <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-recap-dark.webp"><img src="https://raw.githubusercontent.com/opellen/opengoal/main/assets/icons/opengoal-icon-recap.webp" alt="" width="20"/></picture> | `/opgl:recap` | Session wrap-up — sync decisions into living documents |
+Two skills install alongside them — `opengoal-flow` (when to document, when to checkpoint,
+and when a discovery becomes a goal of its own) and `opengoal-subagent` (how work is split,
+and what the main agent never hands off). You never invoke a skill directly; the commands
+load them when they need them.
+### Invocation
+You don't always need to type `/opgl:` — when intent is clear from context, natural language works too.
+| Path | `/opgl` required? | Example |
+|------|-------------------|---------|
+| **Explicit invocation** | Yes | `/opgl goal init`, `/opgl:goal init & design init` |
+| **Confirming a recent recommendation** | No | AI: "Recommend `/opgl:goal init`" → User: "ok" / "go" |
+| **Continuation in active flow** | No | (after goal init) User: "breakdown now" |
+| **Task-execution intent** | No | "proceed with task 6" → `/opgl:go`, "save progress" → `/opgl:goal checkpoint` |
+With clear context, natural language alone triggers execution. `/opgl` serves as an escape hatch when context is ambiguous.
+## Usage flow
+### Applying to an existing project
+```
+You: /opgl:scout
+AI:  Found an existing codebase. No CONTEXT.md yet.
+     Set up project context with `/opgl:context`?
+You: /opgl:context init
+AI:  ✓ docs/CONTEXT.md created
+     To set a goal: `/opgl:goal init`
+You: /opgl:goal Migrate auth module from JWT to session-based
+AI:  ✓ docs/GOAL.md created (5 tasks)
+     Recommend `/opgl:design init` — implementation task with file-level decisions.
+You: /opgl:design init
+AI:  ✓ docs/DESIGN.md created
+     Session store selection, migration strategy, rollback plan included
+You: /opgl:go
+AI:  Task 1/5: Set up session store... ✓ done
+     Task 2/5: Replace middleware... ✓ done
+     Task 3/5 requires DB schema changes. Proceed?
+```
+### New project
+```
+You: /opgl:scout Let's discuss building a real-time collaborative editor
+AI:  (Discovery Mode — exploring tech stack, requirements, constraints)
+     ...
+     ✓ docs/CONTEXT.md created
+You: /opgl:roadmap init
+AI:  ✓ docs/ROADMAP.md created
+     ├── M1: Core editor engine
+     ├── M2: Real-time sync (CRDT)
+     └── M3: Deployment & infrastructure
+You: /opgl:goal
+AI:  Selecting M1 from ROADMAP.md.
+     ✓ docs/GOAL.md created
+You: /opgl:goal breakdown
+AI:  Decomposed into 7 subtasks
+You: /opgl:goal breakdown 3
+AI:  Decomposed Task 3 into 4 subtasks (3.1–3.4)
+You: /opgl:go
+AI:  Task 1/7: Project initialization... ✓ done
+     Task 2/7: Editor core implementation... ✓ done
+     Task 3/7: CRDT sync engine... ✓ done
+You: /opgl:goal checkpoint
+AI:  ✓ docs/CHECKPOINT.md saved
+     (If the session drops, the next one picks up where you left off)
+     ... (continue in next session, all tasks complete)
+You: /opgl:goal archive
+AI:  ✓ Archived 4 files to docs/archive/goals/2026-04-04-editor-core/
+     (GOAL.md, DESIGN.md, PLAN.md, CHECKPOINT.md)
+     Marked M1 done in ROADMAP.md.
+```
+### Resuming work
+```
+You: /opgl:scout
+AI:  CONTEXT.md ✓ | GOAL.md ✓ (3/5 complete)
+     You were working on API endpoints in the previous session.
+     Resume with `/opgl:go`?
+```
+### After a context compaction
+When the conversation gets compacted mid-work, just re-invoke the command:
+```
+You: /opgl:go
+AI:  GOAL.md ✓ (3/7 complete) — Task 4, Step 2/3
+     Resuming: conflict resolution in the CRDT sync engine.
+```
+One command brings everything back — `GOAL.md`, and the checkpoint if you made one — and work continues from the `— Step N/M` annotation instead of starting over. Use `/opgl:scout` if you want a state report first.
+### Handling blockers
+When something comes up mid-goal that must be fixed first:
+```
+You: (during Goal A) Let's fix this dependency bug first.
+AI:  Suggest: /opgl:goal suspend + /opgl:goal init "Fix dependency bug"
+You: ok
+AI:  ✓ Goal A suspended to docs/suspended/goal-a/
+     ✓ New GOAL.md created for the blocker.
+     ... (work through the blocker, archive when done)
+You: /opgl:goal resume
+AI:  Resumed: Goal A. Continue with /opgl:go?
+```
+Nested blockers follow the same pattern — suspend stacks, resume presents a list when multiple goals are paused. If a sub-goal is active, park it first with `/opgl:goal subgoal pause` — `suspend` and `init` are refused while one is active.
+### Handling sub-goals
+Sometimes what comes up isn't a blocker — the goal can still move forward — but it's bigger than a task, needed now, and a different kind of work than the goal itself, so it can't just wait in `BACKLOG.md` either:
+```
+You: (during Goal A: job-application pipeline) I need a YAML→PDF portfolio builder for this — it needs its own architecture decisions first.
+AI:  Doesn't block Goal A, but it's too big to just do inline. Suggest: /opgl:goal subgoal init "Portfolio PDF builder"
+You: ok
+AI:  ✓ Goal A parked to docs/suspended/job-application-pipeline/
+     ✓ New GOAL.md created, linked to Goal A.
+     ... (design and build the portfolio tool, archive when done)
+AI:  ✓ Sub-goal archived. Back on Goal A — pointer task checked off.
+```
+If the goal can't proceed without it, park it as a blocker instead — see above.
+## In the field
+The same goal documents carry a multi-year application build and a weekend plugin.
+That range is the point.
+**Long-horizon builds**
+- [Planura](https://github.com/opellen/Planura) — a native direct-modeling 3D application
+  (C++20 / Qt 6 / OpenGL): half-edge geometry kernel, CSG solid modeling, inference-driven
+  drawing, on [Ordo](https://github.com/opellen/Ordo), its purpose-built application framework.
+- [Ordo](https://github.com/opellen/Ordo) — a typed-event application framework for C++20, extracted from
+  Planura. An event is a plain struct: the type is the identity, the fields are the payload.
+- Reverse-engineering campaigns — the domain OpenGoal was designed in, where the goal is
+  large, the path is unknown, and progress depends on splitting it finely.
+**Applications & tools**
+- [SeedNote](https://github.com/opellen/Seed-Note) — a structured block editor for Android (Kotlin / Jetpack Compose)
+- [ScreenUse](https://github.com/opellen/Screen-Use) — a scenario-driven UI replay and verification tool that drives a real app and records it
+- [OpenIllust](https://github.com/opellen/OpenIllust) — campaign-driven AI vector asset production for Claude Code and
+  Codex; the logo set in this repository was produced with it
+**Focused tools**
+- [Hilo](https://github.com/opellen/Hilo) — an Obsidian highlighting plugin
+- [Loft](https://github.com/opellen/Loft) — an Obsidian image upload plugin
+## From the **gap**
+> **It didn't start with application development.**
+>
+> OpenGoal was built for work where the goal is large, the path is unknown, and progress
+> only comes from splitting the unknown into small, verifiable steps that a human and an
+> agent can hand back and forth over a long horizon — long reverse-engineering campaigns,
+> in the original case. Everything else it is used for inherited that shape.
+>
+> **Heavy workflows weren't always necessary.**
+>
+> All I wanted was a small fix — did I really need all this?
+> Exhaustive discussions with question bombardment and airtight specifications weren't always necessary.
+> Thorough processes are appealing. But AI kept absorbing more and more,
+> and I started to think that maybe the safety nets we want to lean on were, in many cases, becoming excessive shackles.
+> Yet context needed to persist.
+>
+> **I wanted to focus on the present.**
+>
+> I wanted to pull the "current goal" out from under specs and task lists.
+> I wanted to create a "present" that both I and AI could immediately understand and focus on.
+> Whether you grow from small to large, or descend from the big picture —
+> either direction, I wanted a structure where "what to do now" is immediately visible.
+>
+> **I wanted to fill the gap.**
+>
+> I sometimes start with OpenSpec and cross over to OpenGoal, and vice versa.
+> Sometimes I equip Superpowers.
+> What works well should still be used well.
+> I needed something that could sit in front of — or between — completeness and power.
+## Notation
+OpenGoal's commands and skills aren't written as plain prose. They follow a small markdown notation — `## Constraints`, `(condition) => action` dispatch rules, `for each`, `loop until`.
+The form follows published work on pseudocode prompting. CodeAgents (2025) reported that describing agent workflows as pseudocode rather than prose cut token usage by 55–87% while improving task performance by 3–36 points.
+The syntax and priority rules are documented in [docs/NOTATION.md](docs/NOTATION.md) — useful if you tweak the installed commands in your own project. For the rationale and research background behind the notation, see [docs/notation-guide.md](docs/notation-guide.md).
+## Contributing
+Issues are welcome — bugs, questions, ideas, disagreements.
+Pull requests are accepted for platform adapters (`src/platforms/`); I maintain the
+prompt templates myself. See [CONTRIBUTING.md](CONTRIBUTING.md).
+### Development
+```bash
+git clone https://github.com/opellen/OpenGoal.git
+cd OpenGoal
+npm install
+npm run build
+npm test
+```
+## License
+MIT License — see [LICENSE](LICENSE) for details.

package/README.zh-CN.md CHANGED Viewed

@@ -89,7 +89,8 @@ docs/
 ├── DESIGN.md        ← 实现设计（按需）
 ├── PLAN.md          ← 实现计划（复杂任务时自动生成）
 ├── ROADMAP.md       ← 以里程碑组织的整体计划
-├── BACKLOG.md       ← 暂缓处理的范围外发现
+├── BACKLOG.md       ← 优先级队列（最多3行，目标归档时整理）
+├── backlog/          ← 详细发现（open/）与已放弃/归档记录（archive/）
 ├── OVERVIEW.md      ← 项目全貌总览（按需）
 └── suspended/       ← 被中止的目标与暂存的子目标
 ```
@@ -102,7 +103,8 @@ docs/
 | `DESIGN.md` | 这个要怎么实现？ | 直到目标达成 |
 | `PLAN.md` | 这个任务要怎么实现？ | 自动生成 → 自动归档 |
 | `ROADMAP.md` | 我在大局中处于哪个位置？ | 项目全程 |
-| `BACKLOG.md` | 我发现了什么，但先放一放？ | 项目全程 |
+| `BACKLOG.md` | 我发现了什么，但先放一放？ | 目标归档时整理 |
+| `backlog/` | 详细分析与已放弃的记录在哪？ | 长期保留 / 归档 |
 | `OVERVIEW.md` | 整个项目大致是什么样子？ | 项目全程 |
 可以只从 `GOAL.md` 开始，再逐步扩展到 `ROADMAP.md`；也可以先在 `ROADMAP.md` 里画出

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@opellen/opengoal",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Goal-centric AI harness. Plain markdown, zero runtime — nothing runs but your agent.",
   "type": "module",
   "license": "MIT",

package/templates/commands/context.md CHANGED Viewed

@@ -64,7 +64,7 @@ Creates `$DocsDir/CONTEXT.md`.
 - Tasks live in `$DocsDir/GOAL.md` `## Tasks`. Front-matter requires an `id` (slug format).
 - Implementation happens in `$CodebaseDir`.
 - Session progress: `/$CommandPrefix:goal checkpoint` → `$DocsDir/CHECKPOINT.md` (overwritten per session).
-- Deferred discoveries: out-of-scope findings go to `$DocsDir/BACKLOG.md` (persistent parking lot).
+- Deferred discoveries: out-of-scope findings go to `$DocsDir/BACKLOG.md` (priority queue, max 3 lines per entry, swept on goal archive; details in `$DocsDir/backlog/open/`).
 - Work larger than a task, subordinate to the current goal, needed now, and not blocking it: `/$CommandPrefix:goal subgoal init` (the parent resumes automatically on completion; a *blocking* discovery is a blocker, not a sub-goal).
 ```

package/templates/commands/goal.md CHANGED Viewed

@@ -63,8 +63,10 @@ Creates `$DocsDir/GOAL.md`.
 5. Assess task granularity:
    - (tasks are complex, embed multiple implicit steps) => recommend `/$CommandPrefix:goal breakdown` with 1-line rationale
    - (tasks are specific and actionable) => recommend `/$CommandPrefix:design init` (implementation task) or `/$CommandPrefix:go` (analysis task) with 1-line rationale
-6. If the goal was created from a `$DocsDir/BACKLOG.md` item, remove that item from BACKLOG.md (promotion = deletion).
+6. If the goal was created from a `$DocsDir/BACKLOG.md` item, remove that item from BACKLOG.md (promotion = deletion). If the item referenced a file under `$DocsDir/backlog/open/`, move it to `$DocsDir/backlog/archive/`.
 7. Report: `"Created [GOAL.md]($DocsDir/GOAL.md)."`
+   - (promoted from a backlog item without a detail file) => append `" Promoted from backlog: removed item from [$DocsDir/BACKLOG.md]($DocsDir/BACKLOG.md)."`
+   - (promoted from a backlog item with a detail file) => append `" Promoted from backlog: removed item from [$DocsDir/BACKLOG.md]($DocsDir/BACKLOG.md), moved detail file to [$DocsDir/backlog/archive/]($DocsDir/backlog/archive/)."`
 GOAL.md format:
 ```yaml
@@ -339,7 +341,7 @@ Both `parent:` checks read the front-matter of each `$DocsDir/suspended/*/GOAL.m
    - (any file was held back by step 3's collision rule or step 4's mismatch guard) => append `" Not moved: <files> — left in place for triage."`
    - (peer goals remain under `$DocsDir/suspended/`) => close with `" Resume a parked goal with /$CommandPrefix:goal resume."`
    - (no peer goals remain) => close with `" Set a new goal with /$CommandPrefix:goal init."`
-7. If `$DocsDir/BACKLOG.md` has open items, suggest promoting one as the next goal.
+7. If `$DocsDir/BACKLOG.md` has items resolved during this goal or carrying completion/dropped notes, sweep them following `opengoal-flow`'s `Backlog Disposal` section without exception, and report the sweep actions taken (e.g. `"Swept [$DocsDir/BACKLOG.md]($DocsDir/BACKLOG.md): <N> resolved item(s) deleted, <M> dropped item(s) indexed to [$DocsDir/backlog/archive/DROPPED.md]($DocsDir/backlog/archive/DROPPED.md)."`). Then, if open items remain, suggest promoting one as the next goal.
 ### archive (sub-goal completion)

package/templates/commands/verify.md CHANGED Viewed

@@ -11,6 +11,7 @@ Cross-checks the current implementation state against GOAL.md and DESIGN.md to s
 ## Constraints
+- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE reporting verification results, and say so in one line. A reference is not a load: its rules (backlog handling and disposal, self-verification, checkpoint triggers) only bind once the skill's content is actually in context.
 <!-- @if subagent -->
 - **Delegate** evidence gathering (e.g., reading files, running checks) to **subagents** — verification synthesis stays with main. Direct work is limited to one-line fixes, except where `opengoal-subagent` designates work main-only (iterative collaboration, 2nd-iteration rework, evolving design).
 - Report subagent results to the user.

package/templates/skills/opengoal-flow/SKILL.md CHANGED Viewed

@@ -130,9 +130,19 @@ A bare "pause" now has three readings: stop working (the `/$CommandPrefix:go` lo
 When a discovery falls outside the current goal's scope but does not block it (unrelated bug, improvement idea, tech debt):
-- (out-of-scope discovery, current GOAL can still progress) => offer to append a one-line entry to `$DocsDir/BACKLOG.md`, then continue the current task
-- (diagnosis is substantial) => record it in `$DocsDir/logs/` or `discussion/`; the backlog entry keeps only the one-liner + a pointer
-- Entry format: `- [ ] YYYY-MM-DD <one-liner> (found during <goal-id>)`
+- **Pre-check**: Before appending, check `$DocsDir/backlog/archive/DROPPED.md` (via fast search). State the pre-check result in one line (e.g. `"Checked DROPPED.md: no prior determination"`). If already recorded as dropped, do not re-add unless new counter-evidence invalidates the previous decision.
+- (out-of-scope discovery, fits in 3 lines) => offer to append a concise entry to `$DocsDir/BACKLOG.md` (max 3 lines), then continue the current task:
+  - Format: `- [ ] YYYY-MM-DD <one-liner> (found during <goal-id>)`
+- (diagnosis/context exceeds 3 lines) => write details to `$DocsDir/backlog/open/YYYY-MM-DD-<slug>.md` (escape hatch); the backlog entry keeps only the one-liner + link to that file.
+### Backlog Disposal (Sweep)
+`$DocsDir/BACKLOG.md` is a priority queue, not an audit log. Completed or dropped entries must not accumulate inline reports:
+- **Resolved by Goal (promoted or incidental)**: Delete from `$DocsDir/BACKLOG.md`. Implementation history lives in the goal archive. If the item referenced a file under `$DocsDir/backlog/open/`, move it to `$DocsDir/backlog/archive/`. If unreflected lessons/guidelines exist in notes, migrate them to permanent docs before deleting.
+- **Partial completion**: Confirm uncompleted parts are re-homed into a new item or document before deleting the original.
+- **Dropped / Won't-fix**: Delete from `$DocsDir/BACKLOG.md` and append a one-line entry to `$DocsDir/backlog/archive/DROPPED.md` with pointer (`- YYYY-MM-DD <topic>: <rationale> -> <audit/commit/archive pointer>`). If a detailed file exists in `$DocsDir/backlog/open/`, move it to `$DocsDir/backlog/archive/`.
+- (stale dropped premise) => purge from `$DocsDir/backlog/archive/DROPPED.md` when the underlying architectural premise is obsolete.
 Blocking discoveries belong to Blocker Handling (suspend); non-blocking ones split between Sub-goal Handling and here — run them through that section's discriminant, never default them into the backlog.