@opellen/opengoal 1.0.5 → 1.0.7

package/README.ja.md

@@ -330,9 +330,9 @@ AI:  ✓ サブゴールをアーカイブしました。Goal Aに戻ります
 
 **長期にわたるビルド**
 
-- [Planura](https://github.com/opellen/Planura) — ネイティブなダイレクトモデリング3Dアプリケーション(C++20 / Qt 6 / OpenGL): half-edgeジオメトリカーネル、CSGソリッドモデリング、推論駆動の描画を、専用フレームワーク [Ordo](https://github.com/opellen/Ordo) の上に実装。
-- [Ordo](https://github.com/opellen/Ordo) — Planura から切り出された C++20 の型付きイベント・アプリケーションフレームワークです。イベントはただの構造体で、型がアイデンティティ、フィールドがペイロードです。
+- [Ordo](https://github.com/opellen/Ordo) — C++20 の型付きイベント・アプリケーションフレームワークです。イベントはただの構造体で、型がアイデンティティ、フィールドがペイロードです。OrdoStateDesigner と Planura はこの上に構築されています。
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — Ordo の上に構築したステートチャート・デザイナー(C++20 / Qt 6)です。キャンバスに状態機械を描き、その場でシミュレートし、それを動かす C++ を生成します。
+- [Planura](https://github.com/opellen/Planura) — ネイティブなダイレクトモデリング3Dアプリケーション(C++20 / Qt 6 / OpenGL): half-edgeジオメトリカーネル、CSGソリッドモデリング、推論駆動の描画を Ordo の上に実装。Ordo はこのプロジェクトから切り出されたものです。
 - リバースエンジニアリングのキャンペーン — OpenGoalが設計された本来の領域であり、ゴールは大きく、道筋は不明で、進捗が細かく分割できるかどうかにかかっています。
 
 **アプリケーションとツール**

package/README.ko.md

@@ -328,13 +328,13 @@ AI:  ✓ 서브골 아카이브 완료. Goal A로 복귀 — 포인터 태스크
 
 **긴 호흡의 개발**
 
-- [Planura](https://github.com/opellen/Planura) — 네이티브 다이렉트 모델링 3D 애플리케이션
-  (C++20 / Qt 6 / OpenGL). half-edge 지오메트리 커널, CSG 솔리드 모델링, 추론 기반 드로잉을
-  자체 프레임워크인 [Ordo](https://github.com/opellen/Ordo) 기반으로 구현했습니다.
-- [Ordo](https://github.com/opellen/Ordo) — Planura에서 추출된 C++20용 타입 이벤트 애플리케이션 프레임워크입니다.
-  이벤트는 평범한 구조체이며, 타입이 곧 정체성이고 필드가 곧 페이로드입니다.
+- [Ordo](https://github.com/opellen/Ordo) — C++20용 타입 이벤트 애플리케이션 프레임워크입니다.
+  이벤트는 평범한 구조체이며, 타입이 곧 정체성이고 필드가 곧 페이로드입니다. OrdoStateDesigner와 Planura가 이 위에서 만들어졌습니다.
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — Ordo 기반의 상태차트 디자이너입니다
   (C++20 / Qt 6). 캔버스에 상태 머신을 그리고, 실시간으로 시뮬레이션하고, 그것을 실행하는 C++ 코드를 생성합니다.
+- [Planura](https://github.com/opellen/Planura) — 네이티브 다이렉트 모델링 3D 애플리케이션
+  (C++20 / Qt 6 / OpenGL). half-edge 지오메트리 커널, CSG 솔리드 모델링, 추론 기반 드로잉을
+  Ordo 기반으로 구현했고, Ordo는 이 프로젝트에서 추출됐습니다.
 - 리버스엔지니어링 캠페인 — OpenGoal이 처음 고안된 도메인입니다. 목표는 거대하고 길은
   보이지 않아서, 목표를 잘게 쪼갤 수 있을 때에만 전진할 수 있는 영역입니다.
 

package/README.md

@@ -336,13 +336,13 @@ 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.
+- [Ordo](https://github.com/opellen/Ordo) — a typed-event application framework for C++20. An event is a
+  plain struct: the type is the identity, the fields are the payload. OrdoStateDesigner and Planura are built on it.
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — a statechart designer built on Ordo
   (C++20 / Qt 6): draw a state machine on a canvas, simulate it live, and generate the C++ that runs it.
+- [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, which was extracted from it.
 - 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.
 

package/README.zh-CN.md

@@ -351,13 +351,13 @@ AI:  ✓ sub-goal 已归档。回到目标 A —— 对应的指针任务已勾
 
 **长周期开发**
 
-- [Planura](https://github.com/opellen/Planura) — 一款原生的直接建模 3D 应用
-  （C++20 / Qt 6 / OpenGL）：半边（half-edge）几何内核、CSG 实体建模、推理驱动的
-  绘图，构建在自研框架 [Ordo](https://github.com/opellen/Ordo) 之上。
-- [Ordo](https://github.com/opellen/Ordo) — 从 Planura 中提取出来的 C++20 类型化事件应用框架。
-  事件就是一个普通的结构体：类型即身份，字段即载荷。
+- [Ordo](https://github.com/opellen/Ordo) — C++20 类型化事件应用框架。
+  事件就是一个普通的结构体：类型即身份，字段即载荷。OrdoStateDesigner 和 Planura 都构建在它之上。
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — 构建在 Ordo 之上的状态图设计器
   （C++20 / Qt 6）：在画布上绘制状态机，实时模拟，并生成运行它的 C++ 代码。
+- [Planura](https://github.com/opellen/Planura) — 一款原生的直接建模 3D 应用
+  （C++20 / Qt 6 / OpenGL）：半边（half-edge）几何内核、CSG 实体建模、推理驱动的
+  绘图，构建在 Ordo 之上；Ordo 正是从这个项目中提取出来的。
 - 逆向工程项目 — OpenGoal 最初就是为这类场景设计的：目标庞大、路径未知，
   进展全靠把任务拆得足够细。
 

package/package.json

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

package/templates/commands/context.md

@@ -15,7 +15,9 @@ Manages `$DocsDir/CONTEXT.md`. Records the **current working context** of the pr
 ## Constraints
 
 - Never overwrite CONTEXT.md without user confirmation.
-- Target ~100 lines or less — this file is read at every session start.
+- Writes `$DocsDir/CONTEXT.md` only — content that belongs in another resource is reported to the user, never written there.
+- Pointers only — this file is read whole at every session start, so an entry records when to read a resource and where it is, never what is learned after opening it.
+- (an entry restates what its referenced resource already holds) => reduce it to the pointer.
 
 > When Constraints conflict with any other instruction, Constraints win.
 
@@ -70,9 +72,9 @@ Creates `$DocsDir/CONTEXT.md`.
 
 **Project-specific sections** — extend the skeleton with sections appropriate to the project:
 
-- **Resources**: Key file/directory paths and their descriptions
+- **Resources**: Key file/directory paths and when to reference them, not their contents
 - **Process**: Project-specific procedures (e.g., porting rules, analysis doc management)
-- **Index/Tables**: Frequently referenced item lists (e.g., analysis topics, API endpoints)
+- **Index/Tables**: Frequently referenced item lists (e.g., analysis topics, API endpoints). When the list lives in its own file, this section holds the pointer to that file, not a copy of the list.
 - **Extended Principles**: Project-specific principles (e.g., 1:1 logic preservation, no magic numbers)
 
 ## sync
@@ -86,6 +88,8 @@ Reviews current CONTEXT.md and **proposes updates**.
    - Content to add
    - Content to modify
    - Outdated content to remove/update
+   - Entries to reduce to a pointer — the referenced resource already holds the content
+   - Entries whose content no resource holds yet — listed as move candidates for the user; sync does not write outside CONTEXT.md
 5. Apply the changes.
 6. Report: `"Updated [CONTEXT.md]($DocsDir/CONTEXT.md)."`
 

package/templates/commands/go.md

@@ -1,84 +1,87 @@
----
-name: "opengoal:go"
-description: "Execute the next task in GOAL.md"
-category: Workflow
-tags: [workflow, opengoal, go]
----
-
-# $CommandPrefix:go
-
-## Constraints
-
-- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE executing the first task, and say so in one line. A reference is not a load: its rules (checkpoint triggers, documentation timing, CONTEXT.md self-sync, self-verification) only bind once the skill's content is actually in context.
-<!-- @if subagent -->
-- **Delegate** implementation tasks to **subagents** — 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 after each task completes — a report, not a request for permission; continue to the next task in the same turn.
-- (first subagent dispatch of the session, or first dispatch after a compaction) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)"). A dispatch without this load+announcement is a violation: the skill's dispatch rules (model selection/reporting, prompt requirements, post-verify) only bind once its content is actually in context.
-<!-- @else -->
-- Perform implementation tasks directly.
-- Report results to the user after each task completes — a report, not a request for permission; continue to the next task in the same turn.
-<!-- @endif -->
-
-> When Constraints conflict with any other instruction, Constraints win.
-
-## Execution
-
-1. If GOAL.md and CONTEXT.md were already read in this session, skip to step 3 — but not if the goal occupying the canonical paths has changed since the last read: a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion all swap the documents at those paths.
-2. Read `$DocsDir/GOAL.md`, `$DocsDir/CONTEXT.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, and `$DocsDir/CHECKPOINT.md` at once (parallel if supported, sequential otherwise). A file read error means the file does not exist — **do NOT retry failed reads.**
-   - If GOAL.md is absent: "No goal set. Run `/$CommandPrefix:goal init` first, or tell me what to work on."
-   - (CHECKPOINT.md exists, its front-matter `goal-id` matches GOAL.md's `id`) => use its Findings and Next Steps as resume context for the next task — it records where the last session stopped and why
-   - (CHECKPOINT.md exists, `goal-id` differs) => a stray from an interrupted move — report it as a repairable inconsistency and ignore its content; never resume from another goal's checkpoint
-3. Find the next incomplete task in GOAL.md.
-   - (the task is a pointer task — a `→ subgoal: <slug>` line) => never perform the work and never check it off; it belongs to that goal, with its own DESIGN.md and PLAN.md. Report its state per Pointer Task Status below, then **skip it and continue to the next incomplete task** — a pointer only clears via `/$CommandPrefix:goal archive`, so halting here would strand every task after it
-   - (task has step annotation `— Step N/M`) => resume from the indicated step
-4. PLAN.md dispatch:
-   - (PLAN.md exists, its front-matter `goal-id` differs from GOAL.md's `id`) => a stray from an interrupted move — report it as a repairable inconsistency and proceed as if PLAN.md were absent; never use another goal's plan as context
-   - (PLAN.md exists — no `goal-id`, or it matches) => read the corresponding task section for implementation context
-   - (PLAN.md absent, task complexity ≥ multi-file) => generate PLAN.md with the front-matter below, then report: `"Created [PLAN.md]($DocsDir/PLAN.md)."`
-   - (PLAN.md absent, task complexity < multi-file) => proceed without PLAN.md
-5. Execute tasks using the Task Outcome loop below.
-6. Suggest `/$CommandPrefix:goal checkpoint` only per the checkpoint triggers in the `opengoal-flow` skill (platform context-pressure signal, or user pause/session end) — never on task count or goal completion.
-
-PLAN.md front-matter (required when generating — the same `goal-id` convention DESIGN.md and CHECKPOINT.md carry, and what lets `scout`/`goal archive` tell a stray PLAN.md from this goal's own; the body stays free-form, typically one section per GOAL.md task):
-```yaml
----
-goal-id: <GOAL.md id>
-created: YYYY-MM-DD
----
-```
-
-### Pointer Task Status
-
-`go` reads only the canonical paths, so it does not know a pointer's state until it resolves the slug. Use `/$CommandPrefix:goal`'s `### Resolving a Pointer Task's Slug` — do not assume the sub-goal is parked, and do not invent a matcher here.
-
-- (parked) => name it and note `/$CommandPrefix:goal subgoal switch <slug>` works it
-- (archived) => report that it completed with the pointer left unchecked; nothing is blocked — bare `/$CommandPrefix:goal subgoal` offers the check-off
-- (dangling) => report it as a repairable interrupted `subgoal init`, and point at `/$CommandPrefix:goal subgoal`
-
-## Task Outcome
-
-loop until (every task is complete or a pointer task OR user pause):
-  - (task complete, task has no Steps annotation) => mark task done in GOAL.md, update PLAN.md if implementation approach changed, then continue to the next incomplete task in the same turn
-  - (task complete, task had Steps) => mark task done AND remove its step progress annotation; update PLAN.md if implementation approach changed; continue to the next incomplete task in the same turn
-  - (a step completed, more steps remain — the task itself is not complete) => update GOAL.md task with step progress: `— Step N/M (status)`; do not mark the task done
-  - (blocked) => report issue and ask user how to proceed
-  - (all tasks complete) => suggest `/$CommandPrefix:goal archive` once; do not repeat if user does not act on it
-  - (every remaining incomplete task is a pointer task, at least one parked) => stop; report each per Pointer Task Status and suggest `/$CommandPrefix:goal subgoal switch <slug>` for the first parked one — only `/$CommandPrefix:goal archive` on that sub-goal clears its pointer
-  - (every remaining incomplete task is a pointer task, none parked) => stop; report each per Pointer Task Status and suggest `/$CommandPrefix:goal archive` — it succeeds in this state; nothing is blocked, and bare `/$CommandPrefix:goal subgoal` offers an archived pointer's check-off and a dangling pointer's repair
-
-"user pause" means an explicit user request to stop, or a branch above that says stop. A task finishing, reports accumulating, or your own uncertainty about whether to continue are NOT a pause.
-
-- (a task completed and incomplete tasks remain) => do NOT ask "shall I continue?" — continue; asking here is a violation
-- Asking is correct only when: blocked, a genuine decision fork the user owns, or an action that is outward-facing or hard to reverse (publishing, renaming a remote repository, deleting user files)
-
-## Diverge Check
-
-- (DESIGN.md and PLAN.md both exist, Files lists differ) => warn: `"[DESIGN.md]($DocsDir/DESIGN.md) and [PLAN.md]($DocsDir/PLAN.md) file lists differ. Run /$CommandPrefix:design sync to review."`
-
-## Work Principles
-- Load the `opengoal-flow` skill, then follow its main-agent flow principles (documentation timing, CONTEXT.md self-sync, OVERVIEW.md reactive read, checkpoints, self-verification).
-<!-- @if subagent -->
-- Load the `opengoal-subagent` skill, then follow its delegation principles and workflow.
-<!-- @endif -->
-
-> When Constraints conflict with any other instruction, Constraints win.
+---
+name: "opengoal:go"
+description: "Execute the next task in GOAL.md"
+category: Workflow
+tags: [workflow, opengoal, go]
+---
+
+# $CommandPrefix:go
+
+## Constraints
+
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE executing the first task, and say so in one line — its rules (checkpoint triggers, documentation timing, CONTEXT.md self-sync, self-verification) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
+<!-- @if subagent -->
+- **Delegate** implementation tasks to **subagents** — 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 after each task completes — a report, not a request for permission; continue to the next task in the same turn.
+- (subagent dispatch, `opengoal-subagent`'s own text not visible in your current context) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)") — a dispatch without this load and announcement is a violation, because its dispatch rules (model selection/reporting, prompt requirements, post-verify) bind only while that text is in context.
+- (subagent dispatch, `opengoal-subagent`'s own text visible) => do not re-read it.
+<!-- @else -->
+- Perform implementation tasks directly.
+- Report results to the user after each task completes — a report, not a request for permission; continue to the next task in the same turn.
+<!-- @endif -->
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Execution
+
+1. If the text of GOAL.md and CONTEXT.md is visible in your current context, skip to step 3 — but not if the goal occupying the canonical paths has changed since the last read: a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion all swap the documents at those paths.
+2. Read `$DocsDir/GOAL.md`, `$DocsDir/CONTEXT.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, and `$DocsDir/CHECKPOINT.md` at once (parallel if supported, sequential otherwise). A file read error means the file does not exist — **do NOT retry failed reads.**
+   - If GOAL.md is absent: "No goal set. Run `/$CommandPrefix:goal init` first, or tell me what to work on."
+   - (CHECKPOINT.md exists, its front-matter `goal-id` matches GOAL.md's `id`) => use its Findings and Next Steps as resume context for the next task — it records where the last session stopped and why
+   - (CHECKPOINT.md exists, `goal-id` differs) => a stray from an interrupted move — report it as a repairable inconsistency and ignore its content; never resume from another goal's checkpoint
+3. Find the next incomplete task in GOAL.md.
+   - (the task is a pointer task — a `→ subgoal: <slug>` line) => never perform the work and never check it off; it belongs to that goal, with its own DESIGN.md and PLAN.md. Report its state per Pointer Task Status below, then **skip it and continue to the next incomplete task** — a pointer only clears via `/$CommandPrefix:goal archive`, so halting here would strand every task after it
+   - (task has step annotation `— Step N/M`) => resume from the indicated step
+4. PLAN.md dispatch:
+   - (PLAN.md exists, its front-matter `goal-id` differs from GOAL.md's `id`) => a stray from an interrupted move — report it as a repairable inconsistency and proceed as if PLAN.md were absent; never use another goal's plan as context
+   - (PLAN.md exists — no `goal-id`, or it matches) => read the corresponding task section for implementation context
+   - (PLAN.md absent, task complexity ≥ multi-file) => generate PLAN.md with the front-matter below, then report: `"Created [PLAN.md]($DocsDir/PLAN.md)."`
+   - (PLAN.md absent, task complexity < multi-file) => proceed without PLAN.md
+5. Execute tasks using the Task Outcome loop below.
+6. Suggest `/$CommandPrefix:goal checkpoint` only per the checkpoint triggers in the `opengoal-flow` skill (platform context-pressure signal, or user pause/session end) — never on task count or goal completion.
+
+PLAN.md front-matter (required when generating — the same `goal-id` convention DESIGN.md and CHECKPOINT.md carry, and what lets `scout`/`goal archive` tell a stray PLAN.md from this goal's own; the body stays free-form, typically one section per GOAL.md task):
+```yaml
+---
+goal-id: <GOAL.md id>
+created: YYYY-MM-DD
+---
+```
+
+### Pointer Task Status
+
+`go` reads only the canonical paths, so it does not know a pointer's state until it resolves the slug. Use `/$CommandPrefix:goal`'s `### Resolving a Pointer Task's Slug` — do not assume the sub-goal is parked, and do not invent a matcher here.
+
+- (parked) => name it and note `/$CommandPrefix:goal subgoal switch <slug>` works it
+- (archived) => report that it completed with the pointer left unchecked; nothing is blocked — bare `/$CommandPrefix:goal subgoal` offers the check-off
+- (dangling) => report it as a repairable interrupted `subgoal init`, and point at `/$CommandPrefix:goal subgoal`
+
+## Task Outcome
+
+loop until (every task is complete or a pointer task OR user pause):
+  - (task complete, task has no Steps annotation) => mark task done in GOAL.md, update PLAN.md if implementation approach changed, then continue to the next incomplete task in the same turn
+  - (task complete, task had Steps) => mark task done AND remove its step progress annotation; update PLAN.md if implementation approach changed; continue to the next incomplete task in the same turn
+  - (a step completed, more steps remain — the task itself is not complete) => update GOAL.md task with step progress: `— Step N/M (status)`; do not mark the task done
+  - (blocked) => report issue and ask user how to proceed
+  - (all tasks complete) => suggest `/$CommandPrefix:goal archive` once; do not repeat if user does not act on it
+  - (every remaining incomplete task is a pointer task, at least one parked) => stop; report each per Pointer Task Status and suggest `/$CommandPrefix:goal subgoal switch <slug>` for the first parked one — only `/$CommandPrefix:goal archive` on that sub-goal clears its pointer
+  - (every remaining incomplete task is a pointer task, none parked) => stop; report each per Pointer Task Status and suggest `/$CommandPrefix:goal archive` — it succeeds in this state; nothing is blocked, and bare `/$CommandPrefix:goal subgoal` offers an archived pointer's check-off and a dangling pointer's repair
+
+"user pause" means an explicit user request to stop, or a branch above that says stop. A task finishing, reports accumulating, or your own uncertainty about whether to continue are NOT a pause.
+
+- (a task completed and incomplete tasks remain) => do NOT ask "shall I continue?" — continue; asking here is a violation
+- Asking is correct only when: blocked, a genuine decision fork the user owns, or an action that is outward-facing or hard to reverse (publishing, renaming a remote repository, deleting user files)
+
+## Diverge Check
+
+- (DESIGN.md and PLAN.md both exist, Files lists differ) => warn: `"[DESIGN.md]($DocsDir/DESIGN.md) and [PLAN.md]($DocsDir/PLAN.md) file lists differ. Run /$CommandPrefix:design sync to review."`
+
+## Work Principles
+- Load the `opengoal-flow` skill, then follow its main-agent flow principles (documentation timing, CONTEXT.md self-sync, OVERVIEW.md reactive read, checkpoints, self-verification).
+<!-- @if subagent -->
+- Load the `opengoal-subagent` skill, then follow its delegation principles and workflow.
+<!-- @endif -->
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/goal.md

@@ -11,7 +11,9 @@ Manages `$DocsDir/GOAL.md`.
 
 ## Constraints
 
-- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE writing or moving any document, and say so in one line. A reference is not a load: its rules (self-verification before marking anything done, User Decision Support format) only bind once the skill's content is actually in context.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE writing or moving any document, and say so in one line — its rules (self-verification before marking anything done, User Decision Support format) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 - GOAL.md is the single source of truth for the current goal's state.
 - Never overwrite GOAL.md without user confirmation.
 - Preserve existing check states when updating tasks.
@@ -106,7 +108,7 @@ Usage: `/$CommandPrefix:goal breakdown [task-number]`
 
 ### Steps
 
-1. Read `$DocsDir/GOAL.md` and `$DocsDir/DESIGN.md` at once (parallel if supported, sequential otherwise). Skip if already loaded — but re-read if the goal occupying the canonical paths has changed since the last read: a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion all swap the documents at those paths. A file read error means the file does not exist — **do NOT retry failed reads.**
+1. Read `$DocsDir/GOAL.md` and `$DocsDir/DESIGN.md` at once (parallel if supported, sequential otherwise). Skip a file whose text is visible in your current context — but re-read if the goal occupying the canonical paths has changed since the last read: a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion all swap the documents at those paths. A file read error means the file does not exist — **do NOT retry failed reads.**
 2. Identify target tasks based on targeting rules above.
 3. Derive sub-tasks:
    - If DESIGN.md was found and has an Execution Order section, use it as a reference for deriving sub-tasks.
@@ -137,7 +139,7 @@ Saves a progress snapshot to `$DocsDir/CHECKPOINT.md`.
 Single file, overwritten each time — the AI only needs the latest state to resume.
 Prevents loss of mid-goal progress when context is compacted.
 
-1. Read `$DocsDir/GOAL.md` and `$DocsDir/PLAN.md` at once (parallel if supported, sequential otherwise). Skip if already loaded — but re-read if the goal occupying the canonical paths has changed since the last read: a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion all swap the documents at those paths. A file read error means the file does not exist — **do NOT retry failed reads.**
+1. Read `$DocsDir/GOAL.md` and `$DocsDir/PLAN.md` at once (parallel if supported, sequential otherwise). Skip a file whose text is visible in your current context — but re-read if the goal occupying the canonical paths has changed since the last read: a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion all swap the documents at those paths. A file read error means the file does not exist — **do NOT retry failed reads.**
 2. Requires GOAL.md front-matter `id`.
 3. If `$ARGUMENTS` has content, incorporate it.
 4. Write based on the current session:

package/templates/commands/recap.md

@@ -13,7 +13,9 @@ Wraps up the current session by syncing important decisions and findings into th
 
 ## Constraints
 
-- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE writing to any document, and say so in one line. A reference is not a load: its rules (the blocker / sub-goal / backlog discriminant that decides where a scanned finding belongs, self-verification before marking anything done) only bind once the skill's content is actually in context.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE writing to any document, and say so in one line — its rules (the blocker / sub-goal / backlog discriminant that decides where a scanned finding belongs, self-verification before marking anything done) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 - Living documents only — recap updates CONTEXT.md, DESIGN.md, OVERVIEW.md, GOAL.md. Never create new archival files.
 - No duplication — if a change is already reflected in a document, skip it.
 - No session transcripts — show what changes, not conversation replay.
@@ -46,7 +48,9 @@ Wraps up the current session by syncing important decisions and findings into th
 
 Route each finding to its target document. Only the active goal's documents are routing targets — see Constraints. Recap applies the updates itself in Phase 3 (diff, then apply) — it never invokes another command's procedure.
 
-- (working context changes: principles, workflow, resources) => CONTEXT.md
+- (working context changes: principles, workflow, resources) => CONTEXT.md, as a pointer — when to read a resource and where it is
+- (detail only useful after opening a resource, a bullet below routes it) => that document, never CONTEXT.md
+- (detail only useful after opening a resource, no bullet below routes it) => report it to the user — recap writes living documents only
 - (implementation decisions, design changes) => DESIGN.md
 - (project-level understanding: architecture, stack, strategy) => OVERVIEW.md
 - (a routed target — CONTEXT.md, DESIGN.md, OVERVIEW.md, or GOAL.md — does not exist) => skip that routing entirely; a document the project never created is one it has not needed, so there is nothing to sync. This includes one altitude of a dual-altitude finding — the existing altitude's target still writes. Do not create the absent document and do not suggest creating it — Phase 3's report already lists only the documents actually updated. This rule precedes every routing bullet in this Phase, Constraints' project-scoped note included.
@@ -64,6 +68,7 @@ Route each finding to its target document. Only the active goal's documents are
    ### CONTEXT.md
    - Add: new workflow step for ...
    - Update: resource path changed to ...
+   - Trim: <entry> → pointer only (detail already in <resource>)
 
    ### DESIGN.md
    - Add: decision to use X instead of Y ...

package/templates/commands/scout.md

@@ -9,11 +9,14 @@ tags: [workflow, opengoal, scout]
 
 ## Constraints
 
-- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE reporting status, and say so in one line. A reference is not a load: its rules (checkpoint triggers, documentation timing, CONTEXT.md self-sync, self-verification) only bind once the skill's content is actually in context.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE reporting status, and say so in one line — its rules (checkpoint triggers, documentation timing, CONTEXT.md self-sync, self-verification) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 <!-- @if subagent -->
 - **Delegate** exploration tasks (e.g., file discovery, keyword search, tracing) to **subagents** — analysis and judgment stay with main. Direct implementation 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.
-- (first subagent dispatch of the session, or first dispatch after a compaction) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)"). A dispatch without this load+announcement is a violation: the skill's dispatch rules (model selection/reporting, prompt requirements, post-verify) only bind once its content is actually in context.
+- (subagent dispatch, `opengoal-subagent`'s own text not visible in your current context) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)") — a dispatch without this load and announcement is a violation, because its dispatch rules (model selection/reporting, prompt requirements, post-verify) bind only while that text is in context.
+- (subagent dispatch, `opengoal-subagent`'s own text visible) => do not re-read it.
 <!-- @else -->
 - Perform analysis and implementation tasks directly.
 - Report results to the user.

package/templates/commands/verify.md

@@ -11,11 +11,14 @@ 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.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE reporting verification results, and say so in one line — its rules (backlog handling and disposal, self-verification, checkpoint triggers) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 <!-- @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.
-- (first subagent dispatch of the session, or first dispatch after a compaction) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)"). A dispatch without this load+announcement is a violation: the skill's dispatch rules (model selection/reporting, prompt requirements, post-verify) only bind once its content is actually in context.
+- (subagent dispatch, `opengoal-subagent`'s own text not visible in your current context) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)") — a dispatch without this load and announcement is a violation, because its dispatch rules (model selection/reporting, prompt requirements, post-verify) bind only while that text is in context.
+- (subagent dispatch, `opengoal-subagent`'s own text visible) => do not re-read it.
 <!-- @else -->
 - Perform analysis and verification tasks directly.
 - Report results to the user.

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

@@ -32,6 +32,8 @@ Execute when any of:
 
 > Destructive operations (overwriting existing files, archive) still follow state-aware prompts — in-context confirmation does not bypass those guards.
 
+- (a recognized command's own instructions are visible in your current context) => execute from them — do not re-read the command file.
+
 ## Documentation Timing
 
 - (implementation plan crystallizes — files, design decisions, execution order) => suggest `/$CommandPrefix:design init`
@@ -73,7 +75,7 @@ When a reactive trigger fires (the user-invoked-procedure exemption skips this
 1. Confirm `$DocsDir/OVERVIEW.md` exists (existence check only).
 2. If absent, inform the user and proceed without it.
 3. If present, surface the affordance to the user — *do not auto-read*. Example: "Architectural ambiguity detected. `$DocsDir/OVERVIEW.md` is available — load it?"
-4. Read only after explicit user approval, then keep the result in session (skip-if-loaded for subsequent triggers).
+4. Read only after explicit user approval; on a later trigger, use it without re-reading while its text is visible in your current context.
 
 > Bias control: when the trigger condition is uncertain, **default to NOT reading**. The cost of missing one read is small; the cost of always-loading is structural.