Release 1.8.17

Author: clawplays

README.md

@@ -92,7 +92,7 @@ CLI notes:
 - `--document-language`: generated doc language, choose from `en-US`, `zh-CN`, `ja-JP`, or `ar`
 - AI-first language resolution order: explicit language request in the conversation -> current conversation language -> persisted project language in `.skillrc`
 - CLI language resolution order: explicit `--document-language` -> persisted project language in `.skillrc` -> existing project docs / managed `for-ai/*` guidance / asset manifest -> fallback `en-US`
-- OSpec persists the chosen project document language in `.skillrc` and reuses it for `for-ai` guidance, `ospec new`, and `ospec update`
+- OSpec persists the chosen project document language in `.skillrc` and reuses it for `for-ai` guidance, `ospec change`, and `ospec update`
 - new projects initialized by `ospec init` default to the nested layout: root `.skillrc` and `README.md`, with OSpec-managed files under `.ospec/`
 - plain init does not create optional knowledge maps such as `.ospec/knowledge/src/` or `.ospec/knowledge/tests/`; those appear only when a project already has legacy knowledge content to migrate or when future explicit knowledge-generation flows create them
 - CLI commands still accept shorthand like `changes/active/<change-name>`, but the physical path in nested projects is `.ospec/changes/active/<change-name>`
@@ -122,9 +122,9 @@ Claude / Codex skill mode:
 <summary>Command line</summary>
 
 ```bash
-ospec new docs-homepage-refresh .
-ospec new fix-login-timeout .
-ospec new update-billing-copy .
+ospec change docs-homepage-refresh .
+ospec change fix-login-timeout .
+ospec change update-billing-copy .
 ```
 
 </details>
@@ -185,7 +185,7 @@ Archive notes:
 
 ### Goal: Use It For Work That Needs More Care
 
-Use a goal when the work touches several parts of the project, has important design choices, changes an API or data, carries security or migration risk, or will take several rounds to finish. For a small, well-defined edit, use `ospec new` instead.
+Use a Goal only when you choose the full workflow. A user-selected Change remains a Change regardless of complexity, file count, risk, or batch size; create it with `ospec change` (`ospec new` remains an alias).
 
 Start from a terminal:
 
@@ -271,7 +271,7 @@ If you want to convert an older classic project to the new layout, run `ospec la
                               ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  3. EXECUTION                                                  │
-│     ospec new <change-name>      # classic fast change          │
+│     ospec change <change-name>   # classic fast change          │
 │     ospec goal <goal-name>       # full goal workflow           │
 │     ospec brainstorm / plan (optional pre-change aids)         │
 │     ospec session                                              │
@@ -321,7 +321,7 @@ If you want to convert an older classic project to the new layout, run `ospec la
 - **Scoped review evidence and cost metrics**: task and final review dispatches write `artifacts/agents/review-packages/*.diff` with scoped Git evidence, while `artifacts/agents/execution-metrics.json` records packet/report/package bytes and task duration. Goal task graphs can enable `documentation_updates` so missing or undeclared project docs block archive.
 - **Tracked requirement execution**: small changes keep proposal, tasks, state, verification, and review files aligned; full goals also keep design, implementation plan, task graph, handoff, review, worker status, and evidence artifacts aligned.
 - **Goal experience contracts**: every goal runs with `Announce-Before-Act` (the AI announces its skill and stage, the `ospec execute …` command and the artifact it writes, and each subagent dispatch), `Brainstorm-First` (open direction, architecture, API, UI, risk, and scope decisions are asked one at a time through the native question UI before design is locked), and `Zero-Setup` (you only start a goal and describe the requirement — the AI runs every `ospec` command itself). In Claude Code, `ospec session hook --target claude --apply` adds hooks that announce every dispatch and hard-block subagent dispatch while a required decision is still pending.
-- **Optional pre-change aids**: `ospec brainstorm` writes durable exploration artifacts under `.ospec/brainstorms/`, with an optional static visual companion; `ospec plan` writes plan drafts under `.ospec/plans/` and only updates `implementation-plan.md` when `--apply` is passed. The default small-change flow starts with `ospec new`; the full workflow starts with `ospec goal`.
+- **Optional pre-change aids**: `ospec brainstorm` writes durable exploration artifacts under `.ospec/brainstorms/`, with an optional static visual companion; `ospec plan` writes plan drafts under `.ospec/plans/` and only updates `implementation-plan.md` when `--apply` is passed. The Change flow starts with `ospec change` (`ospec new` is an alias); the Goal flow starts with `ospec goal` only when selected by the user.
 - **Session brief and hooks**: `ospec session` writes `.ospec/session-brief.json` and `.ospec/session-brief.md` so agents or humans entering an existing project can see active changes, queued changes, queue-run state, indexed document and archived-feature counts, a cache fingerprint, and the next safe command before touching a change; `ospec session hook --target claude` writes opt-in harness startup artifacts plus a Claude Code hook bundle under `.ospec/hooks/`, and `--apply` idempotently merges it into `.claude/settings.json`.
 - **Integrated goal loop**: `ospec loop run --once` emits token-bounded task/review/verification action batches for fresh model-native subagents. It uses packet paths instead of duplicating the whole goal, persists pending actions and feedback, routes review failures through retry or one grouped repair wave, and enforces required decisions, L3 allowlists, budgets, no-progress stops, and comprehension-review pauses. The removed `loop watch` path now returns migration guidance without starting an agent process.
 - **Task graph controller**: `ospec execute bootstrap` writes a one-change startup/resume snapshot with the project session brief snapshot and next safe action; `handoff` writes a cross-tool worker handoff guide; `doc-review` creates design and implementation-plan reviewer packets; `status` and `next` report controller state; `workspace` records git workspace safety; `worktree` manages explicit git worktree plans/runs; `dispatch`, `launch`, `complete`, and `review` create and settle native-subagent packets; `retry` reopens blocked or needs-context work; `debug`, `tdd`, and `verify` record durable evidence; `sync` rebuilds `worker-status.md`. `orchestrate`, `launch --run --command`, and `review --run --command` are retained only as migration errors and never launch agent CLIs.

SKILL.md

@@ -18,9 +18,9 @@ Do not hand-write an approximation of `ospec init`. Do not assume a web stack, a
 
 ## Workflow Router
 
-- Use `ospec new` / `ospec-change` for routine, scoped work. Its source of truth is `changes/active/<change>/proposal.md`, `changes/active/<change>/tasks.md`, `state.json`, `verification.md`, and `review.md`.
-- Use `ospec goal` / `ospec-goal` for complex, cross-cutting, high-risk, parallel, or evidence-heavy work. It additionally owns `changes/active/<change>/design.md`, `changes/active/<change>/implementation-plan.md`, `changes/active/<change>/artifacts/agents/task-graph.json`, worker/reviewer artifacts, and evidence gates.
-- Do not silently promote a change to a goal or create goal-only artifacts for a classic change. A routing recommendation may explain why one workflow fits, but the user's explicit choice remains authoritative.
+- Use `ospec change` / `ospec-change` when the user selects a Change. Its source of truth is `changes/active/<change>/proposal.md`, `changes/active/<change>/tasks.md`, `state.json`, `verification.md`, and `review.md`; `ospec new` remains a compatibility alias.
+- Use `ospec goal` / `ospec-goal` only when the user selects a Goal. It additionally owns `changes/active/<change>/design.md`, `changes/active/<change>/implementation-plan.md`, `changes/active/<change>/artifacts/agents/task-graph.json`, worker/reviewer artifacts, and evidence gates.
+- Never auto-promote, reject, or replace a user-selected Change because of complexity, risk, file count, parallelism, or batch size. The user's explicit profile choice is authoritative.
 - Enter queue mode only when the user explicitly asks to queue or execute multiple changes.
 
 For an initialized project, read in this order:
@@ -77,7 +77,7 @@ Use `ospec docs generate` for a docs-only repair or refresh. Do not create a cha
 
 ```text
 Initialize:  ospec init [path] -> verify generated project shell
-Change:      ospec new <name> -> implement -> ospec verify -> ospec finalize
+Change:      ospec change <name> -> implement -> ospec verify -> ospec finalize
 Goal:        ospec goal <name> -> session/bootstrap -> design/plan reviews -> dispatch/review -> verify/finalize
 Docs:        ospec docs generate [path] -> ospec docs status -> ospec index check
 Resume:      ospec session [path] -> read brief/index -> run the persisted next safe command

assets/for-ai/ar/ai-guide.md

@@ -28,8 +28,8 @@ tags: [ai, guide, ospec]
 - استخدم الفهرس لتحديد موقع المعرفة قبل قراءة الملفات الهدف
 - عند الدخول إلى مشروع OSpec موجود، شغّل `ospec session [path]` لكتابة `.ospec/session-brief.json` و`.ospec/session-brief.md` مع active change وqueued change وqueue run وcache fingerprint والأمر الآمن التالي؛ هذا project entry brief لا يستبدل `ospec execute bootstrap` للـ active change
 - تعامل مع خطوات built-in quality policy المفعّلة مثل `tdd_cycle` و`root_cause_debug` و`verification_evidence` كـ `optional_steps` خاضعة لـ archive gate؛ غطّها في `tasks.md` و`verification.md` وملفات evidence المطابقة قبل closeout
-- استخدم `ospec new` / `ospec-change` للتغييرات الصغيرة والروتينية، وأبقها على تدفق 1.0 السريع: `proposal.md` و`tasks.md` والتنفيذ و`verification.md` و`review.md` و`state.json`
-- استخدم `ospec goal` / `ospec-goal` للعمل المعقد الذي يحتاج `design.md` و`implementation-plan.md` وtask graph وdocument review وworker/reviewer handoff وevidence gates
+- استخدم `ospec change` / `ospec-change` عندما يختار المستخدم Change، ويبقى `ospec new` alias. أبقها على تدفق 1.0 السريع بغض النظر عن التعقيد أو flags أو عدد الملفات أو المخاطر أو حجم الدفعة: `proposal.md` و`tasks.md` والتنفيذ و`verification.md` و`review.md` و`state.json`
+- استخدم `ospec goal` / `ospec-goal` فقط عندما يختار المستخدم Goal صراحة
 - طبقة التحكم `ospec execute …` (bootstrap وdoc-review وdispatch وlaunch وreview وworktree وfinish وcollect وretry وsync) وكل artifacts الخاصة بـ goal تنتمي إلى `workflow_profile_id: goal`. وبالنسبة لـ `workflow_profile_id: change`، التزم بالتدفق السريع الكلاسيكي — لا تقرأ ولا تشغّل طبقة execute أو artifacts الخاصة بـ goal؛ حرّر `proposal.md` و`tasks.md`، ونفّذ، وسجّل `verification.md` و`review.md`، ثم أغلق بـ `ospec verify` و`ospec finalize` — ما لم يطلب المستخدم صراحةً تنفيذ agent/worker على هذا الـ change
 - عند تنفيذ goal بمساعدة AI، لا تطلب من المستخدم كتابة `design.md` أو `implementation-plan.md` يدوياً؛ أنشئهما أو حدّثهما من المتطلب و`proposal.md` وسياق المشروع قبل اشتقاق `artifacts/agents/task-graph.json` أو تعديل `tasks.md` أو الكود
 - عند تنفيذ classic change، لا تنشئ goal-only files ما لم يطلب المستخدم ترقية العمل صراحة إلى goal

assets/for-ai/ar/change-protocol.md

@@ -0,0 +1,29 @@
+# بروتوكول Classic Change
+
+استخدم هذا البروتوكول المختصر عندما يختار المستخدم OSpec change. اختيار profile للمستخدم؛ لا ترقِّ change تلقائياً إلى Goal ولا ترفضها أو تستبدلها بسبب التعقيد أو flags أو عدد الملفات أو حجم الدفعة.
+
+## السياق
+
+في البداية اقرأ `.skillrc` والعناصر ذات الصلة من `SKILL.index.json` و`proposal.md` و`tasks.md` و`state.json` فقط. اقرأ `verification.md` عند التحقق و`review.md` عند closeout. اقرأ `ai-guide.md` أو `execution-protocol.md` الكامل فقط عند غياب هذا الملف أو تفعيل plugin حاجب أو وجود قاعدة محددة غامضة.
+
+## دورة الحياة
+
+1. أنشئ العمل الجديد عبر `ospec change <change-name> [path]`، ويبقى `ospec new` alias للتوافق.
+2. إذا وُجد active change مطابق فتابعه ولا تنشئ نسخة مكررة.
+3. تدخل تغييرات batch إلى queue وتُنفذ بالتتابع في worktree المشترك.
+4. حافظ فقط على `proposal.md` و`tasks.md` و`state.json` و`verification.md` و`review.md`، ولا تنشئ design أو plan أو task graph أو worker أو review provenance artifacts الخاصة بـ Goal.
+5. شغّل فحوص المشروع المرتبطة فعلاً بالتغيير وسجّل الأوامر والنتائج في `verification.md`، ولا تفرض build أو lint أو test أو TDD أو debug غير ذي صلة.
+6. ينفذ AI الحالي مراجعة خفيفة واحدة. يمكن إغلاق `APPROVED` و`APPROVED_WITH_CONCERNS` تلقائياً، بينما توقف `PENDING` و`NEEDS_CHANGES` و`BLOCKED` الإغلاق.
+7. شغّل `ospec verify` عند الحاجة إلى preview صريح. بعد اكتمال التنفيذ والتحقق وسياسة الوثائق وplugin gates والمراجعة، شغّل `ospec finalize` فوراً لمزامنة classic state والأرشفة بشكل ذري.
+
+## سياسة الوثائق
+
+اضبط `change_type` على `bugfix` أو `feature` أو `maintenance` أو `docs`، واضبط `documentation_impact` على `none` أو `required`.
+
+- يمكن للـ bugfix استخدام `none` مع `documentation_reason` واضح، إلا إذا غيّر سلوك المستخدم أو API أو عقد التشغيل.
+- يجب أن تستخدم feature أو docs change القيمة `required` وأن تسجل وثيقة مشروع أو module أو API أو user حقيقية واحدة على الأقل في `documentation_updates`.
+- لا يُحتسب ملخص `docs/project/changes/...` المولد تلقائياً كوثائق feature.
+- حدّث `SKILL.md` فقط عند تغير قواعد module أو تعليمات AI أو عقود الاستخدام.
+- يعاد بناء `SKILL.index.json` تلقائياً بعد archive وليس task يدوية.
+
+توقف فقط لقرار مستخدم حقيقي أو فشل تحقق أو review غير محلولة أو plugin gate حاجب أو pause صريح.