🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

@clawplays/ospec-cli

Package Overview
Dependencies
Maintainers
1
Versions
43
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@clawplays/ospec-cli - npm Package Compare versions

Comparing version
1.8.5
 to
1.8.6
+1
-1
assets/for-ai/ar/execution-protocol.md

@@ -42,3 +42,3 @@ ---

- يجب أن تتقارب عمليات review repair. ترث task downstream التي تعدل ملفات مشتركة التزامات regression من upstream المتعدية، وتقتصر كل من task-review repair وgrouped final-review repair على جولتين افتراضيا. عندما تكون final review بحالة `BLOCKED` يجب التوقف لحل blocker وعدم بدء grouped repair. لا ترفع `--max-task-repair-rounds` أو `--max-final-repair-rounds` قبل عرض findings غير المحلولة والحصول على تفويض صريح من المستخدم.
- يجب أن يكون انتظار native child محدوداً في كل harness. يعيد `wait_agent` في Codex/GPT وpolling لـ Claude Task وأي native wait آخر التحكم خلال 60 ثانية؛ حدّث كل child حي قبل `heartbeatDueAt`، واحفظ كل نتيجة مكتملة فوراً، ثم أعد tick بعد كل poll. عند غياب capacity يقتصر implementation batch على مهمتين من دون تقليل توازي review الآمن.
- يجب أن يكون انتظار native child محدوداً في كل harness. يعيد `wait_agent` في Codex/GPT وpolling لـ Claude Task وأي native wait آخر التحكم خلال 60 ثانية؛ هذا حد poll واحدة للـ controller وليس حد تشغيل child. حدّث كل child حي قبل `heartbeatDueAt`، وعند الاكتمال استخدم `loop finalize` الصادر مع action لحفظ evidence وresult ذرياً، ثم أعد tick بعد كل poll. يمكن للـ child الاستمرار عبر عدة polls حتى action deadline، وتوجد result grace محدودة بعد اكتمال evidence. عند غياب capacity يقتصر implementation batch على مهمتين من دون تقليل توازي review الآمن.
- عند بدء أو استئناف active change واحد، استخدم `ospec execute bootstrap [changes/active/<change>]` لكتابة `artifacts/agents/bootstrap.json` و`artifacts/agents/bootstrap.md` مع project session brief snapshot، ثم اتبع الإجراء الآمن التالي المسجل فيه

@@ -45,0 +45,0 @@ - عند نقل change بين agents أو tools أو worktrees أو shells أو operators بشريين، استخدم `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` لكتابة `artifacts/agents/handoff.json` و`artifacts/agents/handoff.md`؛ يسجل هذا الأمر project session brief snapshot وtool mapping وقواعد السلامة فقط ولا يشغّل workers أو يعدّل source files

+1
-1
assets/for-ai/en-US/execution-protocol.md

@@ -44,3 +44,3 @@ ---

- Review repair is convergent. A downstream task that shares files inherits transitive upstream regression obligations. Automatic task-review repair and grouped final-review repair each default to two rounds. A blocked final review stops for blocker resolution; it never enters grouped repair. Never raise `--max-task-repair-rounds` or `--max-final-repair-rounds` without explicit user authorization after showing the unresolved findings.
- Native child waiting is bounded on every harness. Codex/GPT `wait_agent`, Claude Task polling, and other native waits return within 60 seconds; refresh every live child before `heartbeatDueAt`, persist each completed result immediately, and re-tick after every poll. Unknown capacity caps implementation batches at two but does not reduce safe review parallelism.
- Native child waiting is bounded on every harness. Codex/GPT `wait_agent`, Claude Task polling, and other native waits return within 60 seconds; this limits one controller poll, not the child runtime. Refresh every live child before `heartbeatDueAt`, persist each completed result with its emitted `loop finalize` command, and re-tick after every poll. A live child may continue across polls up to its action deadline, and evidence-complete work receives a bounded result grace period. Unknown capacity caps implementation batches at two but does not reduce safe review parallelism.
- When starting or resuming one active change, use `ospec execute bootstrap [changes/active/<change>]` to write `artifacts/agents/bootstrap.json` and `artifacts/agents/bootstrap.md` with the project session brief snapshot, then follow its next safe action

@@ -47,0 +47,0 @@ - Use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules without launching workers or editing source files

+1
-1
assets/for-ai/ja-JP/execution-protocol.md

@@ -42,3 +42,3 @@ ---

- review repair は収束させる。共有ファイルを変更する downstream task は推移的 upstream の regression obligation を継承し、task review と grouped final review の自動 repair はそれぞれ既定で 2 round までとする。final review が `BLOCKED` の場合は blocker の解決まで停止し、grouped repair に進めない。未解決 findings を示してユーザーの明示的承認を得るまで `--max-task-repair-rounds` または `--max-final-repair-rounds` を引き上げない。
- すべての harness で native child の待機を bounded にする。Codex/GPT の `wait_agent`、Claude Task polling、その他の native wait は 60 秒以内に戻り、各 live child の `heartbeatDueAt` 前に更新し、完了結果を直ちに保存して poll ごとに再 tick する。capacity 不明時は implementation batch を 2 件までに制限するが、安全な review 並列性は維持する。
- すべての harness で native child の待機を bounded にする。Codex/GPT の `wait_agent`、Claude Task polling、その他の native wait は 60 秒以内に戻る。この 60 秒は controller poll 1 回の上限であり、child runtime の上限ではない。各 live child を `heartbeatDueAt` 前に更新し、完了時は action の `loop finalize` で evidence と result を atomic に保存して poll ごとに再 tick する。child は action deadline まで複数 poll にまたがって実行でき、evidence 完了後には bounded result grace がある。capacity 不明時は implementation batch を 2 件までに制限するが、安全な review 並列性は維持する。
- one active change を開始または再開するときは、`ospec execute bootstrap [changes/active/<change>]` で project session brief snapshot を含む `artifacts/agents/bootstrap.json` と `artifacts/agents/bootstrap.md` を書き、そこにある次の安全な action に従う

@@ -45,0 +45,0 @@ - change を agent、tool、worktree、shell、human operator の間で引き渡すときは、`ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` で `artifacts/agents/handoff.json` と `artifacts/agents/handoff.md` を書く。このコマンドは project session brief snapshot、target tool mapping、safety rules のみを記録し、worker 起動や source file 編集は行わない

+1
-1
assets/for-ai/zh-CN/execution-protocol.md

@@ -44,3 +44,3 @@ ---

- review repair 必须收敛。共享文件的下游任务要继承传递上游的回归义务；每个 task 的自动 review-repair 和 grouped final-review repair 都默认最多两轮。final review 为 `BLOCKED` 时必须停下解决 blocker，不得进入 grouped repair。展示未解决 findings 并获得用户明确授权前，不得提高 `--max-task-repair-rounds` 或 `--max-final-repair-rounds`。
- 所有 harness 的 native child 等待都必须有界。Codex/GPT 的 `wait_agent`、Claude Task 轮询以及其它原生等待必须在 60 秒内返回；每个 live child 都要在 `heartbeatDueAt` 前续租，完成一个立即持久化一个，并在每轮 poll 后重新 tick。capacity 未知时 implementation 批次最多两个，但不降低安全 review 的并行度。
- 所有 harness 的 native child 等待都必须有界。Codex/GPT 的 `wait_agent`、Claude Task 轮询以及其它原生等待必须在 60 秒内返回；60 秒只限制一次 controller poll，不是 child 的执行上限。每个 live child 都要在 `heartbeatDueAt` 前续租，完成后用 action 给出的 `loop finalize` 原子提交证据和结果，并在每轮 poll 后重新 tick。child 可跨多个 poll 运行到 action 的绝对期限，证据完成后还有有界的结果宽限期。capacity 未知时 implementation 批次最多两个，但不降低安全 review 的并行度。
- 开始或恢复单个 active change 时，用 `ospec execute bootstrap [changes/active/<change>]` 写入带 project session brief snapshot 的 `artifacts/agents/bootstrap.json` 和 `artifacts/agents/bootstrap.md`，然后按其中的下一步安全动作继续

@@ -47,0 +47,0 @@ - change 需要在 agent、工具、worktree、shell 或人工操作者之间交接时，用 `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` 写入 `artifacts/agents/handoff.json` 和 `artifacts/agents/handoff.md`；它只记录 project session brief snapshot、目标工具映射和安全规则，不会启动 worker 或编辑源码

+1
-1
assets/global-skills/codex/ospec-goal/SKILL.md

@@ -17,3 +17,3 @@ ---

- **Harness capability is explicit and target-bound.** In Codex create executable work with `--target codex --execution-model controller --harness-interactive true --native-subagents supported`; use the equivalent actual target in other IDEs. A target name alone never proves that native children exist. `runtimeAdapter.selected` exists only when the capability target matches, the session is current, and native subagents are supported. There is no Orca, target-CLI, or current-controller fallback.
- **Executor lifecycle is durable and bounded.** After native subagent dispatch, record `ospec loop heartbeat <goal> --action-item <id> --executor <child-id>` and refresh every live child before its `heartbeatDueAt`. Never make one indefinite native wait: Codex/GPT use `wait_agent` for at most 60 seconds per poll, Claude uses bounded background Task polling when available, and every other native adapter follows its published `maxWaitMs`. Record each child independently with `ospec loop result ...`, persist completed siblings immediately, and re-run `loop run --once --json` after every poll. Use `ospec loop recover --force` only when the prior session/child is known to be gone. Expired items requeue; completed siblings do not.
- **Executor lifecycle is durable and bounded.** After native subagent dispatch, record `ospec loop heartbeat <goal> --action-item <id> --executor <child-id>` and refresh every live child before its `heartbeatDueAt`. Never make one indefinite native wait: Codex/GPT use `wait_agent` for at most 60 seconds per poll, Claude uses bounded background Task polling when available, and every other native adapter follows its published `maxWaitMs`. Sixty seconds limits one controller poll, not the child runtime; a live child continues across polls up to its action deadline. Commit each finished child with its emitted `ospec loop finalize ...` command, persist completed siblings immediately, and re-run `loop run --once --json` after every poll. Successful finalize requires authoritative durable evidence; evidence-complete work receives a bounded result grace period. Legacy `loop result` remains supported. Use `ospec loop recover --force` only when the prior session/child is known to be gone. Expired items requeue; completed siblings do not.
- **Independent document reviewers are bound to a native child.** Read `dispatch.runtimeAdapter.selected.nativeSubagent`, start one fresh model-native reviewer, immediately claim its real child id, refresh long reviews with `--heartbeat-executor`, and finish with `--complete-executor`. Reviews bind the target, controller session, child, timestamp, document hash, and findings provenance.

@@ -20,0 +20,0 @@ - **Safety level chosen at creation via a decision gate.** Prefer presenting an `AskUserQuestion` for L1/L2/L3 as the first decision; otherwise pass `ospec goal <name> --level L1|L2|L3` (default L1). L1 = report-only (findings go to triage, no code changes); L2 = assisted (real changes but required-decision gates hard-block); L3 = unattended within an allowlist.

+1
-1
dist/cli.js

@@ -65,3 +65,3 @@ #!/usr/bin/env node

const services_1 = require("./services");
const CLI_VERSION = '1.8.5';
const CLI_VERSION = '1.8.6';
function showInitUsage() {

@@ -68,0 +68,0 @@ console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language en-US|zh-CN|ja-JP|ar]');

+24
-14
dist/commands/LoopCommand.js

@@ -42,3 +42,3 @@ "use strict";

const BaseCommand_1 = require("./BaseCommand");
const LOOP_ACTIONS = ['run', 'watch', 'status', 'pause', 'resume', 'level', 'configure', 'allowlist', 'tick-plan', 'heartbeat', 'result', 'recover'];
const LOOP_ACTIONS = ['run', 'watch', 'status', 'pause', 'resume', 'level', 'configure', 'allowlist', 'tick-plan', 'heartbeat', 'result', 'finalize', 'recover'];
class LoopCommand extends BaseCommand_1.BaseCommand {

@@ -82,2 +82,5 @@ async execute(action = 'status', ...args) {

return;
case 'finalize':
await this.recordResult(args, true);
return;
case 'recover':

@@ -223,3 +226,3 @@ await this.recover(args);

if (args.includes('--json')) {
console.log(JSON.stringify({ version: '1.8.5', changePath, config, state, reviewGovernance }, null, 2));
console.log(JSON.stringify({ version: '1.8.6', changePath, config, state, reviewGovernance }, null, 2));
return;

@@ -456,2 +459,6 @@ }

options.promptMaxChars = nullableNumber('--prompt-max-chars') ?? undefined;
options.implementationMaxRuntimeMinutes = nullableNumber('--implementation-max-runtime-minutes') ?? undefined;
options.reviewMaxRuntimeMinutes = nullableNumber('--review-max-runtime-minutes') ?? undefined;
options.verificationMaxRuntimeMinutes = nullableNumber('--verification-max-runtime-minutes') ?? undefined;
options.evidenceResultGraceMinutes = nullableNumber('--evidence-result-grace-minutes') ?? undefined;
const changePath = await this.resolveChangePath(inputPath);

@@ -569,10 +576,10 @@ const replacesPaths = allowPaths.length > 0;

}
async recordResult(args) {
async recordResult(args, finalize = false) {
const inputPath = args[0] && !args[0].startsWith('--') ? args[0] : undefined;
const actionItemId = this.parseFlagValue(args, '--action-item');
if (!actionItemId)
throw new Error('loop result requires --action-item <id>.');
throw new Error(`loop ${finalize ? 'finalize' : 'result'} requires --action-item <id>.`);
const executorId = this.parseFlagValue(args, '--executor');
if (!executorId)
throw new Error('loop result requires --executor <child-id>.');
throw new Error(`loop ${finalize ? 'finalize' : 'result'} requires --executor <child-id>.`);
const exitValue = this.parseFlagValue(args, '--exit-code');

@@ -588,11 +595,14 @@ const exitCode = exitValue === undefined ? null : Number(exitValue);

const changePath = await this.resolveChangePath(inputPath);
const state = await services_1.services.loopService.recordExecutionResults(changePath, [{
actionItemId,
executorId,
exitCode,
timedOut: args.includes('--timed-out'),
tokensUsed,
summary: this.parseFlagValue(args, '--summary'),
}]);
this.success(`Loop result recorded for ${actionItemId}; pending=${state.pendingControllerAction?.actionId || 'none'}.`);
const result = {
actionItemId,
executorId,
exitCode,
timedOut: args.includes('--timed-out'),
tokensUsed,
summary: this.parseFlagValue(args, '--summary'),
};
const state = finalize
? await services_1.services.loopService.finalizeExecutionItem(changePath, result)
: await services_1.services.loopService.recordExecutionResults(changePath, [result]);
this.success(`Loop ${finalize ? 'finalize' : 'result'} recorded for ${actionItemId}; pending=${state.pendingControllerAction?.actionId || 'none'}.`);
}

@@ -599,0 +609,0 @@ async recover(args) {

+15
-0
dist/services/LoopService.d.ts

@@ -79,2 +79,6 @@ import { FileService } from './FileService';

promptMaxChars: number;
implementationMaxRuntimeMinutes: number;
reviewMaxRuntimeMinutes: number;
verificationMaxRuntimeMinutes: number;
evidenceResultGraceMinutes: number;
}

@@ -96,2 +100,3 @@ export interface LoopActionItem {

heartbeatDueAt?: string;
absoluteExpiresAt?: string;
resultCommand?: string;

@@ -132,2 +137,5 @@ verificationCommand?: string | null;

leaseExpiresAt: string;
absoluteExpiresAt?: string;
evidenceReadyAt?: string | null;
evidenceResultDeadlineAt?: string | null;
executorId: string | null;

@@ -278,2 +286,6 @@ completedAt: string | null;

promptMaxChars?: number;
implementationMaxRuntimeMinutes?: number;
reviewMaxRuntimeMinutes?: number;
verificationMaxRuntimeMinutes?: number;
evidenceResultGraceMinutes?: number;
nativeHarnessMetadata?: RuntimeNativeHarnessExecutionMetadata | null;

@@ -335,2 +347,3 @@ }

recordExecutionResults(changePath: string, results: LoopExecutionResult[]): Promise<LoopState>;
finalizeExecutionItem(changePath: string, result: LoopExecutionResult): Promise<LoopState>;
private recordExecutionResultsUnlocked;

@@ -345,2 +358,3 @@ private countPendingRequiredDecisions;

private recommendedHeartbeatDueAt;
private actionMaxRuntimeMs;
private extendControllerCapabilitySession;

@@ -363,2 +377,3 @@ private isTerminalItemStatus;

private observePending;
private refreshPendingEvidenceReadiness;
private readLatestVerificationEvidence;

@@ -365,0 +380,0 @@ private issueAction;

+1
-1
dist/services/TemplateGenerator.js

@@ -284,3 +284,3 @@ "use strict";

version: '1.0',
contract_version: '1.8.5',
contract_version: '1.8.6',
feature: featureName,

@@ -287,0 +287,0 @@ status: 'pending',

+1
-1
dist/services/templates/ExecutionTemplateBuilder.js

@@ -757,3 +757,3 @@ "use strict";

version: '1.0',
contract_version: '1.8.5',
contract_version: '1.8.6',
feature: context.feature,

@@ -760,0 +760,0 @@ status: 'pending',

+1
-1
package.json
{
"name": "@clawplays/ospec-cli",
"version": "1.8.5",
"version": "1.8.6",
"description": "Official OSpec CLI package for spec-driven development (SDD) and document-driven development in AI coding agent and CLI workflows.",

@@ -5,0 +5,0 @@ "main": "dist/index.js",

+2
-2
README.md

@@ -148,3 +148,3 @@ <h1><a href="https://ospec.ai/" target="_blank" rel="noopener noreferrer">OSpec.ai</a></h1>

`launch` writes `artifacts/agents/launch-plan.md`; it does not start workers by itself. Codex/GPT use `spawn_agent` plus bounded `wait_agent`, Claude Code uses bounded background Task polling when available, Gemini uses `@generalist`, and OpenCode uses `@mention`. Every native adapter returns from one wait within 60 seconds, refreshes heartbeats, persists each completed child immediately, and re-ticks. OSpec never starts Orca, Codex, Claude, or another agent CLI as a fallback. If the current model harness cannot provide native subagents, executable dispatch blocks until a supported harness reports a fresh capability.
`launch` writes `artifacts/agents/launch-plan.md`; it does not start workers by itself. Codex/GPT use `spawn_agent` plus bounded `wait_agent`, Claude Code uses bounded background Task polling when available, Gemini uses `@generalist`, and OpenCode uses `@mention`. Every native adapter returns from one wait within 60 seconds, refreshes heartbeats, persists each completed child immediately, and re-ticks. The 60-second boundary limits one controller poll, not the AI task runtime: a live child continues across polls up to its configurable absolute action deadline. OSpec never starts Orca, Codex, Claude, or another agent CLI as a fallback. If the current model harness cannot provide native subagents, executable dispatch blocks until a supported harness reports a fresh capability.

@@ -215,3 +215,3 @@ ### 3. Archive After Acceptance

To see progress, child executor ids, heartbeat due times, leases, review rounds, token sources, and concurrency/guard reasons, run `ospec loop status --brief` or `--json`. Use `ospec loop configure` for concurrency and budgets; allowlist flags replace the complete selected list and print a diff. For L3, prefer `ospec loop allowlist derive/check/apply --from-task-graph`, whose CAS-bound apply requires explicit approval for permission expansion. IDE controllers persist child ownership with `ospec loop heartbeat` and each result with `ospec loop result`; after a confirmed session/child loss, `ospec loop recover --force` expires only unfinished items so they can be requeued without duplicating completed siblings. Task-review and grouped final-review repair each default to two automatic rounds, configurable with `--max-task-repair-rounds` and `--max-final-repair-rounds`; a blocked final review stops for blocker resolution rather than dispatching an invalid repair wave. Dependent downstream reviews inherit shared-file regression obligations instead of repeatedly invalidating approved upstream reviews. The 1.8.5 bounded native wait, task-review freshness, capacity guard, and task-boundary additions are documented in [docs/goal-1.8.5-interface.md](docs/goal-1.8.5-interface.md); the 1.8.4 review contract remains in [docs/goal-1.8.4-interface.md](docs/goal-1.8.4-interface.md). Advanced loop and triage commands are documented in [docs/loop-engineering.md](docs/loop-engineering.md).
To see progress, child executor ids, heartbeat due times, leases, review rounds, token sources, and concurrency/guard reasons, run `ospec loop status --brief` or `--json`. Use `ospec loop configure` for concurrency, budgets, action runtime limits, and evidence-result grace; allowlist flags replace the complete selected list and print a diff. For L3, prefer `ospec loop allowlist derive/check/apply --from-task-graph`, whose CAS-bound apply requires explicit approval for permission expansion. IDE controllers persist child ownership with `ospec loop heartbeat` and atomically commit successful evidence plus executor outcome with `ospec loop finalize`; legacy `ospec loop result` remains supported. After a confirmed session/child loss, `ospec loop recover --force` expires only unfinished items so they can be requeued without duplicating completed siblings. Task-review and grouped final-review repair each default to two automatic rounds, configurable with `--max-task-repair-rounds` and `--max-final-repair-rounds`; a blocked final review stops for blocker resolution rather than dispatching an invalid repair wave. Dependent downstream reviews inherit shared-file regression obligations instead of repeatedly invalidating approved upstream reviews. The 1.8.6 runtime, finalize, directory snapshot, approval-cache, and scheduling changes are documented in [docs/goal-1.8.6-interface.md](docs/goal-1.8.6-interface.md); the 1.8.5 bounded native wait contract remains in [docs/goal-1.8.5-interface.md](docs/goal-1.8.5-interface.md). Advanced loop and triage commands are documented in [docs/loop-engineering.md](docs/loop-engineering.md).

@@ -218,0 +218,0 @@ Internally, OSpec keeps implementation and independent review separate, bounds specialist document review by round/time/no-progress guards, preserves immutable convergence history, feeds blocked work and review findings into transactional retry or grouped repair, and requires current test evidence before the goal is considered complete.

dist/services/LoopService.js

Sorry, the diff of this file is too big to display

dist/services/ProjectService.js

Sorry, the diff of this file is too big to display

dist/services/TaskGraphExecutionService.d.ts

Sorry, the diff of this file is too big to display

dist/services/TaskGraphExecutionService.js

Sorry, the diff of this file is too big to display

dist/services/templates/ProjectTemplateBuilder.js

Sorry, the diff of this file is too big to display

dist/tools/build-index.js

Sorry, the diff of this file is too big to display