scene-capability-engine 3.3.16 → 3.3.18

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.18] - 2026-02-26
+
+### Added
+- Curated `errorbook` command set for high-signal failure remediation knowledge:
+  - `sce errorbook record`
+  - `sce errorbook list`
+  - `sce errorbook show <id>`
+  - `sce errorbook find --query <text>`
+  - `sce errorbook promote <id>`
+  - `sce errorbook deprecate <id> --reason <text>`
+  - `sce errorbook requalify <id> --status <candidate|verified>`
+
+### Changed
+- Added strict curation/promotion policy to command reference (`宁缺毋滥，优胜略汰`):
+  - fingerprint-based deduplication on record
+  - promotion gate requires validated root cause, fix actions, verification evidence, ontology tags, and minimum quality score
+
+## [3.3.17] - 2026-02-26
+
+### Added
+- Orchestrator rate-limit profile management commands:
+  - `sce orchestrate profile list`
+  - `sce orchestrate profile show`
+  - `sce orchestrate profile set <conservative|balanced|aggressive> [--reset-overrides]`
+- Runtime one-shot profile override:
+  - `sce orchestrate run --rate-limit-profile <profile>`
+- New anti-429 regression shortcut:
+  - `npm run test:orchestrator-429`
+- Added default orchestrator baseline config files:
+  - `.sce/config/orchestrator.json`
+  - `template/.sce/config/orchestrator.json`
+- Added profile runbook:
+  - `docs/agent-runtime/orchestrator-rate-limit-profiles.md`
+
+### Changed
+- Orchestration engine now supports runtime config overrides for one execution without mutating persisted config.
+- Command reference updated with profile workflow and recommended anti-429 usage.
+
 ## [3.3.16] - 2026-02-26
 
 ### Added

package/README.md

@@ -775,6 +775,6 @@ A deep conversation about AI development trends, Neo-Confucian philosophy, and s
 
 ---
 
-**Version**: 3.3.16  
+**Version**: 3.3.17  
 **Last Updated**: 2026-02-26
 

package/README.zh.md

@@ -636,7 +636,7 @@ sce spec bootstrap --name 01-00-my-first-feature --non-interactive
 
 ---
 
-**版本**：3.3.16  
+**版本**：3.3.17  
 **最后更新**：2026-02-26
 
 

package/bin/scene-capability-engine.js

@@ -817,6 +817,10 @@ registerLockCommands(program);
 const { registerKnowledgeCommands } = require('../lib/commands/knowledge');
 registerKnowledgeCommands(program);
 
+// Errorbook commands
+const { registerErrorbookCommands } = require('../lib/commands/errorbook');
+registerErrorbookCommands(program);
+
 // Studio orchestration commands
 const { registerStudioCommands } = require('../lib/commands/studio');
 registerStudioCommands(program);

package/docs/agent-runtime/orchestrator-rate-limit-profiles.md

@@ -0,0 +1,66 @@
+# Orchestrator Rate-Limit Profiles
+
+This document defines the default anti-429 presets used by SCE multi-agent orchestration.
+
+## Profiles
+
+| Profile | Positioning | Best for |
+|---|---|---|
+| `conservative` | strongest throttling, safest | unstable provider quota windows, repeated `429` spikes |
+| `balanced` | default baseline | normal daily multi-agent runs |
+| `aggressive` | higher throughput, lower safety margin | stable quota windows with strict delivery deadlines |
+
+## Effective Preset Values
+
+| Key | conservative | balanced | aggressive |
+|---|---:|---:|---:|
+| `rateLimitMaxRetries` | 10 | 8 | 6 |
+| `rateLimitBackoffBaseMs` | 2200 | 1500 | 1000 |
+| `rateLimitBackoffMaxMs` | 90000 | 60000 | 30000 |
+| `rateLimitCooldownMs` | 60000 | 45000 | 20000 |
+| `rateLimitLaunchBudgetPerMinute` | 4 | 8 | 16 |
+| `rateLimitSignalWindowMs` | 45000 | 30000 | 20000 |
+| `rateLimitSignalThreshold` | 2 | 3 | 4 |
+| `rateLimitSignalExtraHoldMs` | 5000 | 3000 | 2000 |
+| `rateLimitDynamicBudgetFloor` | 1 | 1 | 2 |
+
+## Usage
+
+Persistent (writes `.sce/config/orchestrator.json`):
+
+```bash
+sce orchestrate profile set conservative
+sce orchestrate profile set balanced --reset-overrides
+```
+
+One-shot for a single run (does not change file):
+
+```bash
+sce orchestrate run --specs "spec-a,spec-b,spec-c" --rate-limit-profile conservative
+```
+
+Inspect current effective state:
+
+```bash
+sce orchestrate profile show --json
+```
+
+## Validation Checklist
+
+Run anti-429 regression:
+
+```bash
+npm run test:orchestrator-429
+```
+
+Run full suite before release:
+
+```bash
+npm test -- --runInBand
+```
+
+Release readiness criteria:
+
+1. No failing test in orchestrator/rate-limit scope.
+2. `orchestrate profile show --json` returns expected profile and effective values.
+3. Multi-agent run no longer stalls under sustained `429`; launch budget and hold telemetry progress over time.

package/docs/command-reference.md

@@ -295,15 +295,72 @@ sce repo health [--json]
 # Start orchestration for multiple specs
 sce orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3
 
+# One-shot anti-429 profile override (without editing orchestrator.json)
+sce orchestrate run --specs "spec-a,spec-b,spec-c" --rate-limit-profile conservative
+
 # Show orchestration status
 sce orchestrate status [--json]
 
 # Stop all running sub-agents
 sce orchestrate stop
+
+# List/show/set persistent rate-limit profile
+sce orchestrate profile list
+sce orchestrate profile show --json
+sce orchestrate profile set conservative
+sce orchestrate profile set balanced --reset-overrides
 ```
 
 When you pass `--specs` to `sce spec bootstrap|pipeline run|gate run`, sce now defaults to this orchestrate mode automatically.
 
+Rate-limit profiles:
+- `conservative`: strongest anti-429 throttling (recommended for unstable quota windows)
+- `balanced`: default profile for normal multi-agent runs
+- `aggressive`: higher throughput with lower protection margins
+
+### Errorbook (Curated Failure Knowledge)
+
+```bash
+# Record curated remediation entry
+sce errorbook record \
+  --title "Order approval queue saturation" \
+  --symptom "Approval queue backlog exceeded SLA" \
+  --root-cause "Worker pool under-provisioned and retries amplified load" \
+  --fix-action "Increase workers from 4 to 8" \
+  --fix-action "Reduce retry burst window" \
+  --verification "Load test confirms p95 < SLA threshold" \
+  --ontology "entity,relation,decision_policy" \
+  --tags "moqui,order,performance" \
+  --status verified \
+  --json
+
+# List/show/find entries
+sce errorbook list --status promoted --min-quality 75 --json
+sce errorbook show <entry-id> --json
+sce errorbook find --query "approve order timeout" --limit 10 --json
+
+# Promote only after strict gate checks pass
+sce errorbook promote <entry-id> --json
+
+# Eliminate obsolete/low-value entries (curation)
+sce errorbook deprecate <entry-id> --reason "superseded by v2 policy" --json
+
+# Requalify deprecated entry after remediation review
+sce errorbook requalify <entry-id> --status verified --json
+```
+
+Curated quality policy (`宁缺毋滥，优胜略汰`) defaults:
+- `record` requires: `title`, `symptom`, `root_cause`, and at least one `fix_action`.
+- Fingerprint dedup is automatic; repeated records merge evidence and increment occurrence count.
+- `promote` enforces strict gate:
+  - `root_cause` present
+  - `fix_actions` non-empty
+  - `verification_evidence` non-empty
+  - `ontology_tags` non-empty
+  - `quality_score >= 75`
+- `deprecate` requires explicit `--reason` to preserve elimination traceability.
+- `requalify` only accepts `candidate|verified`; `promoted` must still go through `promote` gate.
+
 ### Studio Workflow
 
 ```bash
@@ -408,6 +465,7 @@ Contract/baseline files:
 - `docs/agent-runtime/capability-mapping-report.schema.json`
 - `docs/agent-runtime/agent-result-summary-contract.schema.json`
 - `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`
+- `docs/agent-runtime/orchestrator-rate-limit-profiles.md`
 
 Multi-agent merge governance default:
 - `sce orchestrate run` loads `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`.
@@ -1327,6 +1385,7 @@ Recommended `.sce/config/orchestrator.json`:
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitProfile": "balanced",
   "rateLimitMaxRetries": 8,
   "rateLimitBackoffBaseMs": 1500,
   "rateLimitBackoffMaxMs": 60000,
@@ -1335,13 +1394,25 @@ Recommended `.sce/config/orchestrator.json`:
   "rateLimitCooldownMs": 45000,
   "rateLimitLaunchBudgetPerMinute": 8,
   "rateLimitLaunchBudgetWindowMs": 60000,
+  "rateLimitSignalWindowMs": 30000,
+  "rateLimitSignalThreshold": 3,
+  "rateLimitSignalExtraHoldMs": 3000,
+  "rateLimitDynamicBudgetFloor": 1,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
 }
 ```
 
-`rateLimit*` settings provide dedicated retry/backoff and adaptive parallel throttling when providers return 429 / too-many-requests errors. Engine retry honors `Retry-After` / `try again in ...` hints from provider error messages and clamps final retry waits by `rateLimitBackoffMaxMs` to avoid unbounded pause windows. During active backoff windows, new pending spec launches are paused to reduce request bursts (launch hold remains active even if adaptive parallel throttling is disabled). `orchestrate stop` now interrupts pending retry waits immediately so long backoff does not look like a deadlock.
+`rateLimitProfile` applies preset anti-429 behavior (`conservative|balanced|aggressive`). Any explicit `rateLimit*` field in `orchestrator.json` overrides the selected profile value.
+
+`rateLimit*` settings provide dedicated retry/backoff and adaptive throttling when providers return 429 / too-many-requests errors. Engine retry honors `Retry-After` / `try again in ...` hints from provider error messages and clamps final retry waits by `rateLimitBackoffMaxMs` to avoid unbounded pause windows. During active backoff windows, new pending spec launches are paused to reduce request bursts (launch hold remains active even if adaptive parallel throttling is disabled). Sustained 429 spikes are additionally controlled by:
+- `rateLimitSignalWindowMs`: rolling signal window for spike detection
+- `rateLimitSignalThreshold`: signals required inside window before escalation
+- `rateLimitSignalExtraHoldMs`: extra launch hold per escalation unit
+- `rateLimitDynamicBudgetFloor`: lowest dynamic launch budget allowed during sustained pressure
+
+`orchestrate stop` interrupts pending retry waits immediately so long backoff windows do not look like deadlocks.
 
 Codex sub-agent permission defaults:
 - `--sandbox danger-full-access` is always injected by orchestrator runtime.